Build Python Library

Implements pip-installable Python libraries by scaffolding the project structure, building core abstractions with adapters, and verifying each module with pytest before proceeding.

Workflow

1. Scaffold the project — create src layout, pyproject.toml, package structure, and py.typed marker. See SCAFFOLDING.md.
2. Define the public API — write __init__.py with explicit exports and __all__. Only types and functions users need. See SCAFFOLDING.md.
3. Implement core abstractions — build protocols/ABCs, data classes, and shared types that all concrete implementations depend on. See PATTERNS.md.
4. Test core abstractions — write pytest tests for core types and protocols. Run pytest and verify zero failures before proceeding. See TESTING.md.
5. Implement concrete modules — build one module at a time (proxy wrappers, provider clients, adapters). See PATTERNS.md.
6. Test each module before the next — write tests for the module just implemented. Run pytest and verify zero failures before starting the next module. See TESTING.md.
7. Install and verify — run pip install -e ".[dev]" and verify the package imports correctly from a clean script. See TESTING.md.
8. Run full test suite — run pytest -v and verify all tests pass, then run python -c "from packagename import ..." to verify public API. See TESTING.md.

Self-review checklist

Before delivering, verify ALL:

• Project uses src layout: src/packagename/ not packagename/ at root
• pyproject.toml exists with [build-system], [project], and [project.optional-dependencies]
• py.typed marker file exists in the package directory
• __init__.py has explicit __all__ listing only public names
• Every public function and class has a type-hinted signature (all parameters and return type)
• Every module has a corresponding test file (src/pkg/foo.py → tests/test_foo.py)
• pytest -v passes with zero failures
• pip install -e ".[dev]" succeeds
• python -c "from packagename import ..." imports all public API names without error
• No third-party imports in core modules that lack a corresponding optional dependency group
• Proxy/wrapper classes delegate unknown attributes via __getattr__ to the wrapped object

Golden rules

Hard rules. Never violate these.

1. Src layout always. Every project uses src/packagename/ structure. Never place the package at the repository root. This prevents accidental imports from the source directory instead of the installed package.
2. Test before you proceed. Never implement module N+1 until module N has passing tests. Run pytest after each module. This catches integration errors early instead of at the end.
3. Explicit public API. __init__.py must define __all__ and import only the names users need. Internal modules start with underscore (_internal.py) or live in a _private/ subdirectory. Never expose implementation details.
4. Type hints on every signature. Every function parameter and return type must have a type annotation. Use Protocol for duck-typed interfaces, not ABC unless you need shared implementation.
5. Optional dependencies in extras. Third-party framework imports (langchain, chromadb, openai) must be in [project.optional-dependencies] groups and imported lazily with try/except at usage point, not at module top level.
6. Proxy delegates everything. Wrapper classes must implement __getattr__ to forward unknown attribute access to the wrapped object. Never enumerate and re-implement every method — the proxy must work with future methods the wrapped library adds.

Reference files