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:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user