mirror of
https://github.com/wshobson/agents.git
synced 2026-03-18 09:37:15 +00:00
style: format all files with prettier
This commit is contained in:
@@ -21,18 +21,22 @@ Comprehensive guidance for implementing asynchronous Python applications using a
|
||||
## Core Concepts
|
||||
|
||||
### 1. Event Loop
|
||||
|
||||
The event loop is the heart of asyncio, managing and scheduling asynchronous tasks.
|
||||
|
||||
**Key characteristics:**
|
||||
|
||||
- Single-threaded cooperative multitasking
|
||||
- Schedules coroutines for execution
|
||||
- Handles I/O operations without blocking
|
||||
- Manages callbacks and futures
|
||||
|
||||
### 2. Coroutines
|
||||
|
||||
Functions defined with `async def` that can be paused and resumed.
|
||||
|
||||
**Syntax:**
|
||||
|
||||
```python
|
||||
async def my_coroutine():
|
||||
result = await some_async_operation()
|
||||
@@ -40,15 +44,19 @@ async def my_coroutine():
|
||||
```
|
||||
|
||||
### 3. Tasks
|
||||
|
||||
Scheduled coroutines that run concurrently on the event loop.
|
||||
|
||||
### 4. Futures
|
||||
|
||||
Low-level objects representing eventual results of async operations.
|
||||
|
||||
### 5. Async Context Managers
|
||||
|
||||
Resources that support `async with` for proper cleanup.
|
||||
|
||||
### 6. Async Iterators
|
||||
|
||||
Objects that support `async for` for iterating over async data sources.
|
||||
|
||||
## Quick Start
|
||||
|
||||
@@ -22,24 +22,28 @@ Comprehensive guide to creating, structuring, and distributing Python packages u
|
||||
## Core Concepts
|
||||
|
||||
### 1. Package Structure
|
||||
|
||||
- **Source layout**: `src/package_name/` (recommended)
|
||||
- **Flat layout**: `package_name/` (simpler but less flexible)
|
||||
- **Package metadata**: pyproject.toml, setup.py, or setup.cfg
|
||||
- **Distribution formats**: wheel (.whl) and source distribution (.tar.gz)
|
||||
|
||||
### 2. Modern Packaging Standards
|
||||
|
||||
- **PEP 517/518**: Build system requirements
|
||||
- **PEP 621**: Metadata in pyproject.toml
|
||||
- **PEP 660**: Editable installs
|
||||
- **pyproject.toml**: Single source of configuration
|
||||
|
||||
### 3. Build Backends
|
||||
|
||||
- **setuptools**: Traditional, widely used
|
||||
- **hatchling**: Modern, opinionated
|
||||
- **flit**: Lightweight, for pure Python
|
||||
- **poetry**: Dependency management + packaging
|
||||
|
||||
### 4. Distribution
|
||||
|
||||
- **PyPI**: Python Package Index (public)
|
||||
- **TestPyPI**: Testing before production
|
||||
- **Private repositories**: JFrog, AWS CodeArtifact, etc.
|
||||
@@ -111,11 +115,13 @@ my-package/
|
||||
```
|
||||
|
||||
**Advantages:**
|
||||
|
||||
- Prevents accidentally importing from source
|
||||
- Cleaner test imports
|
||||
- Better isolation
|
||||
|
||||
**pyproject.toml for source layout:**
|
||||
|
||||
```toml
|
||||
[tool.setuptools.packages.find]
|
||||
where = ["src"]
|
||||
@@ -135,6 +141,7 @@ my-package/
|
||||
```
|
||||
|
||||
**Simpler but:**
|
||||
|
||||
- Can import package without installing
|
||||
- Less professional for libraries
|
||||
|
||||
@@ -297,7 +304,8 @@ version = {attr = "my_package.__version__"}
|
||||
write_to = "src/my_package/_version.py"
|
||||
```
|
||||
|
||||
**In __init__.py:**
|
||||
**In **init**.py:**
|
||||
|
||||
```python
|
||||
# src/my_package/__init__.py
|
||||
__version__ = "1.0.0"
|
||||
@@ -344,12 +352,14 @@ if __name__ == "__main__":
|
||||
```
|
||||
|
||||
**Register in pyproject.toml:**
|
||||
|
||||
```toml
|
||||
[project.scripts]
|
||||
my-tool = "my_package.cli:main"
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pip install -e .
|
||||
my-tool greet World
|
||||
@@ -441,6 +451,7 @@ twine upload dist/*
|
||||
```
|
||||
|
||||
**Using API tokens (recommended):**
|
||||
|
||||
```bash
|
||||
# Create ~/.pypirc
|
||||
[distutils]
|
||||
@@ -511,6 +522,7 @@ my_package = [
|
||||
```
|
||||
|
||||
**Accessing data files:**
|
||||
|
||||
```python
|
||||
# src/my_package/loader.py
|
||||
from importlib.resources import files
|
||||
@@ -546,7 +558,7 @@ company/
|
||||
└── routes.py
|
||||
```
|
||||
|
||||
**Do NOT include __init__.py in the namespace directory (company/):**
|
||||
**Do NOT include **init**.py in the namespace directory (company/):**
|
||||
|
||||
```toml
|
||||
# company-core/pyproject.toml
|
||||
@@ -567,6 +579,7 @@ include = ["company.api*"]
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
|
||||
```python
|
||||
# Both packages can be imported under same namespace
|
||||
from company.core import models
|
||||
@@ -587,6 +600,7 @@ ext-modules = [
|
||||
```
|
||||
|
||||
**Or with setup.py:**
|
||||
|
||||
```python
|
||||
# setup.py
|
||||
from setuptools import setup, Extension
|
||||
@@ -617,6 +631,7 @@ __version__ = "1.2.3"
|
||||
```
|
||||
|
||||
**Version constraints in dependencies:**
|
||||
|
||||
```toml
|
||||
dependencies = [
|
||||
"requests>=2.28.0,<3.0.0", # Compatible range
|
||||
@@ -644,6 +659,7 @@ local_scheme = "dirty-tag"
|
||||
```
|
||||
|
||||
**Creates versions like:**
|
||||
|
||||
- `1.0.0` (from git tag)
|
||||
- `1.0.1.dev3+g1234567` (3 commits after tag)
|
||||
|
||||
@@ -688,7 +704,7 @@ rm -rf test-env
|
||||
|
||||
### Pattern 18: README.md Template
|
||||
|
||||
```markdown
|
||||
````markdown
|
||||
# My Package
|
||||
|
||||
[](https://pypi.org/project/my-package/)
|
||||
@@ -702,6 +718,7 @@ Brief description of your package.
|
||||
```bash
|
||||
pip install my-package
|
||||
```
|
||||
````
|
||||
|
||||
## Quick Start
|
||||
|
||||
@@ -733,7 +750,8 @@ pytest
|
||||
## License
|
||||
|
||||
MIT
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
## Common Patterns
|
||||
|
||||
@@ -762,7 +780,7 @@ jobs:
|
||||
- uses: actions/upload-artifact@v3
|
||||
with:
|
||||
path: ./wheelhouse/*.whl
|
||||
```
|
||||
````
|
||||
|
||||
### Pattern 20: Private Package Index
|
||||
|
||||
|
||||
@@ -22,18 +22,21 @@ Comprehensive guide to profiling, analyzing, and optimizing Python code for bett
|
||||
## Core Concepts
|
||||
|
||||
### 1. Profiling Types
|
||||
|
||||
- **CPU Profiling**: Identify time-consuming functions
|
||||
- **Memory Profiling**: Track memory allocation and leaks
|
||||
- **Line Profiling**: Profile at line-by-line granularity
|
||||
- **Call Graph**: Visualize function call relationships
|
||||
|
||||
### 2. Performance Metrics
|
||||
|
||||
- **Execution Time**: How long operations take
|
||||
- **Memory Usage**: Peak and average memory consumption
|
||||
- **CPU Utilization**: Processor usage patterns
|
||||
- **I/O Wait**: Time spent on I/O operations
|
||||
|
||||
### 3. Optimization Strategies
|
||||
|
||||
- **Algorithmic**: Better algorithms and data structures
|
||||
- **Implementation**: More efficient code patterns
|
||||
- **Parallelization**: Multi-threading/processing
|
||||
@@ -113,6 +116,7 @@ if __name__ == "__main__":
|
||||
```
|
||||
|
||||
**Command-line profiling:**
|
||||
|
||||
```bash
|
||||
# Profile a script
|
||||
python -m cProfile -o output.prof script.py
|
||||
@@ -144,6 +148,7 @@ def process_data(data):
|
||||
```
|
||||
|
||||
**Manual line profiling:**
|
||||
|
||||
```python
|
||||
from line_profiler import LineProfiler
|
||||
|
||||
@@ -483,7 +488,7 @@ print(f"With cache (1000 runs): {fast_time:.4f}s")
|
||||
print(f"Cache info: {fibonacci_fast.cache_info()}")
|
||||
```
|
||||
|
||||
### Pattern 13: Using __slots__ for Memory
|
||||
### Pattern 13: Using **slots** for Memory
|
||||
|
||||
```python
|
||||
import sys
|
||||
|
||||
@@ -23,22 +23,26 @@ Comprehensive guide to implementing robust testing strategies in Python using py
|
||||
## Core Concepts
|
||||
|
||||
### 1. Test Types
|
||||
|
||||
- **Unit Tests**: Test individual functions/classes in isolation
|
||||
- **Integration Tests**: Test interaction between components
|
||||
- **Functional Tests**: Test complete features end-to-end
|
||||
- **Performance Tests**: Measure speed and resource usage
|
||||
|
||||
### 2. Test Structure (AAA Pattern)
|
||||
|
||||
- **Arrange**: Set up test data and preconditions
|
||||
- **Act**: Execute the code under test
|
||||
- **Assert**: Verify the results
|
||||
|
||||
### 3. Test Coverage
|
||||
|
||||
- Measure what code is exercised by tests
|
||||
- Identify untested code paths
|
||||
- Aim for meaningful coverage, not just high percentages
|
||||
|
||||
### 4. Test Isolation
|
||||
|
||||
- Tests should be independent
|
||||
- No shared state between tests
|
||||
- Each test should clean up after itself
|
||||
|
||||
@@ -23,6 +23,7 @@ Comprehensive guide to using uv, an extremely fast Python package installer and
|
||||
## Core Concepts
|
||||
|
||||
### 1. What is uv?
|
||||
|
||||
- **Ultra-fast package installer**: 10-100x faster than pip
|
||||
- **Written in Rust**: Leverages Rust's performance
|
||||
- **Drop-in pip replacement**: Compatible with pip workflows
|
||||
@@ -32,6 +33,7 @@ Comprehensive guide to using uv, an extremely fast Python package installer and
|
||||
- **Lockfile support**: Reproducible installations
|
||||
|
||||
### 2. Key Features
|
||||
|
||||
- Blazing fast installation speeds
|
||||
- Disk space efficient with global cache
|
||||
- Compatible with pip, pip-tools, poetry
|
||||
@@ -41,6 +43,7 @@ Comprehensive guide to using uv, an extremely fast Python package installer and
|
||||
- Built-in virtual environment support
|
||||
|
||||
### 3. UV vs Traditional Tools
|
||||
|
||||
- **vs pip**: 10-100x faster, better resolver
|
||||
- **vs pip-tools**: Faster, simpler, better UX
|
||||
- **vs poetry**: Faster, less opinionated, lighter
|
||||
|
||||
Reference in New Issue
Block a user