---
name: python-packaging-patterns-ac6ff58887c5
description: Structure Python projects for distribution with pyproject.toml, src layouts, dependency management, and publishing workflows. Covers packaging tools (hatch, setuptools, flit, poetry), versioning strategies, and editable installs. Triggers on Python project setup, packaging configuration, or dependency management requests.
license: MIT
complexity: intermediate
time_to_learn: 30min
tags:
  - python
  - packaging
  - pyproject
  - dependencies
  - distribution
governance_phases: [shape, build]
governance_norm_group: repo-hygiene
organ_affinity: [organ-i, organ-iv, organ-v, organ-vi, organ-vii, meta]
triggers: [user-asks-about-python-packaging, project-has-pyproject-toml, project-has-setup-py, context:new-python-project, file-type:pyproject.toml]
complements: [deployment-cicd, testing-patterns, coding-standards-enforcer]
---

# Python Packaging Patterns

Structure Python projects for reliable distribution and dependency management.

## Project Layout

### The `src` Layout (Recommended)

```
my-project/
├── pyproject.toml
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       └── cli.py
├── tests/
│   ├── conftest.py
│   └── test_core.py
└── README.md
```

**Why src layout:** Prevents accidental imports from the working directory. Forces installation before testing, catching packaging errors early.

### Flat Layout (Simple Projects)

```
my-project/
├── pyproject.toml
├── my_package/
│   ├── __init__.py
│   └── core.py
└── tests/
```

Acceptable for internal tools and single-organ repos where distribution is not a concern.

## pyproject.toml Configuration

### Minimal Configuration

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-package"
version = "0.1.0"
description = "A concise description"
requires-python = ">=3.11"
license = "MIT"
dependencies = [
    "httpx>=0.27",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "ruff>=0.5",
    "mypy>=1.10",
]
```

### Build Backend Selection

| Backend | When to Use |
|---------|-------------|
| **hatchling** | Default choice. Fast, minimal config, good monorepo support |
| **setuptools** | Legacy projects, C extensions, complex build needs |
| **flit** | Pure Python, minimal config, simple projects |
| **poetry-core** | When using Poetry for dependency management |

### Optional Dependency Groups

Organize optional dependencies by use case:

```toml
[project.optional-dependencies]
dev = ["pytest>=8.0", "ruff>=0.5", "mypy>=1.10"]
docs = ["sphinx>=7.0", "myst-parser"]
dashboard = ["fastapi>=0.110", "uvicorn"]
metrics = ["prometheus-client"]
```

Install specific groups: `pip install -e ".[dev,dashboard]"`

## Entry Points

### Console Scripts

```toml
[project.scripts]
my-cli = "my_package.cli:main"
```

### Plugin Entry Points

```toml
[project.entry-points."my_app.plugins"]
csv = "my_package.plugins.csv:CsvPlugin"
json = "my_package.plugins.json:JsonPlugin"
```

## Version Management

### Single Source of Truth

```toml
# In pyproject.toml
[project]
dynamic = ["version"]

[tool.hatch.version]
path = "src/my_package/__init__.py"
```

```python
# In __init__.py
__version__ = "0.1.0"
```

### CalVer for System Packages

For infrastructure packages where semantic versioning adds little value:

```python
__version__ = "2026.03.1"  # YYYY.MM.patch
```

## Dependency Pinning Strategy

| Context | Strategy | Tool |
|---------|----------|------|
| Library | Loose bounds (`>=1.0,<2.0`) | pyproject.toml |
| Application | Exact pins | pip-compile / uv lock |
| CI | Lockfile | uv.lock / requirements.txt |

### Generating Lockfiles

```bash
# Using uv (recommended)
uv pip compile pyproject.toml -o requirements.txt
uv pip compile pyproject.toml --extra dev -o requirements-dev.txt

# Using pip-tools
pip-compile pyproject.toml -o requirements.txt
```

## Editable Installs

```bash
# Standard editable install
pip install -e .

# With dev dependencies
pip install -e ".[dev]"

# In a fresh venv
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

## Tool Configuration in pyproject.toml

### Ruff

```toml
[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP"]
```

### Pytest

```toml
[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
pythonpath = ["."]
```

### Mypy

```toml
[tool.mypy]
strict = true
python_version = "3.11"
```

## Publishing

### To PyPI

```bash
# Build
python -m build

# Upload (use trusted publishing when possible)
python -m twine upload dist/*
```

### Trusted Publishing (GitHub Actions)

```yaml
- uses: pypa/gh-action-pypi-publish@release/v1
  with:
    password: ${{ secrets.PYPI_API_TOKEN }}
```

## Common Patterns

### Namespace Packages

For multi-repo packages sharing a namespace:

```
# Repo A
src/organvm/engine/__init__.py

# Repo B
src/organvm/dashboard/__init__.py
```

Use implicit namespace packages (no `__init__.py` at namespace level).

### Conditional Dependencies

```toml
dependencies = [
    "tomli>=2.0; python_version < '3.11'",
    "typing-extensions>=4.0; python_version < '3.12'",
]
```

### Package Data

```toml
[tool.hatch.build.targets.wheel]
packages = ["src/my_package"]

[tool.hatch.build.targets.wheel.force-include]
"assets" = "my_package/assets"
```

## Anti-Patterns to Avoid

- **setup.py without pyproject.toml** — Always use pyproject.toml as the single config source
- **Pinning exact versions in libraries** — Use compatible ranges to avoid dependency conflicts
- **Importing from project root in tests** — Use src layout or ensure editable install
- **Multiple version sources** — Keep version in exactly one place
- **requirements.txt as sole dependency spec** — Use pyproject.toml; generate lockfiles from it


---
Source attribution: luokai0
Original project: https://github.com/luokai0/ai-agent-skills-by-luo-kai/blob/4d2fb89cdfb75f3f6fd3c6c5ec9ad90ea129eb3c/ai-agent-skills/21-external-registries/18-organvm-skills/development/python-packaging-patterns/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: luokai0
Original project: https://github.com/luokai0/ai-agent-skills-by-luo-kai/blob/4d2fb89cdfb75f3f6fd3c6c5ec9ad90ea129eb3c/ai-agent-skills/21-external-registries/18-organvm-skills/development/python-packaging-patterns/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering
Roles: Backend Developer, Data Engineer, ML / AI Engineer
Specialties: API, Backend, Cross Platform
Tools: Flit, Hatch, Poetry, Setuptools
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: c970f6bfc1aa51e9cdce348da8f4c7c53fe02d5cc83ddefb661883d457d2cc7f