style: format all files with prettier

This commit is contained in:
Seth Hobson
2026-01-19 17:07:03 -05:00
parent 8d37048deb
commit 56848874a2
355 changed files with 15215 additions and 10241 deletions

View File

@@ -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
[![PyPI version](https://badge.fury.io/py/my-package.svg)](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