Initial commit

skills/nix-packaging/python/python.md

@@ -0,0 +1,47 @@
+# Package a Python Module with Nix
+
+Packaging a Python module (`buildPythonPackage`) involves determining the source, dependencies, and build system, typically from `pyproject.toml`. Ensure all dependencies are already packaged before referencing them.
+
+More complex cases require special handling. Below are examples for different scenarios.
+
+## Normal Python Module
+
+See the simple example: [tyro](./tyro/package.nix)
+
+## Customize Build System and Disable Tests
+
+Some Python modules require additional build tools, or have tests that cannot run in the Nix sandbox. See [Swanboard](./swanboard/package.nix) for an example.
+
+## Customize Source Root and Optional Dependencies
+
+See [agno](./agno/package.nix) for examples of:
+
+- Using `sourceRoot` when the Python module's root differs from the project root (specify the relative path).
+- Handling optional dependencies: include them in `optional-dependencies` when available, or safely omit them if not yet packaged.
+
+## Rust-Backed Python Module
+
+For Python packages implemented in Rust with Python bindings, use `rustPlatform` as a helper. See [tantivy](./tantivy/package.nix) for an example.
+
+## Relax or Remove Dependencies
+
+When dependency requirements cannot be satisfied, investigate further:
+
+1. **Version mismatch**: If the dependency is packaged but the version requirement is too strict, add it to `pythonRelaxDeps` to bypass version checking.
+2. **Missing dependency**: If the dependency is not packaged, assess whether it's essential for your use case. If not, add it to `pythonRemoveDeps`.
+
+See [darts](./darts/package.nix) for an example.
+
+## Updating an Existing Python Package
+
+Besides the general update steps, also:
+
+1. **Update dependencies**: Check `pyproject.toml` or `setup.py` for changed dependencies and update:
+   - `dependencies` - Runtime dependencies
+   - `build-system` - Build-time dependencies (e.g., setuptools, poetry-core)
+   - `optional-dependencies` - If relevant to your use case
+
+2. **Handle breaking changes**: New versions may:
+   - Drop Python version support (update `pythonOlder` or `disabled`)
+   - Change build backends (update `build-system` based on `pyproject.toml`)
+   - Add new test dependencies (update `nativeCheckInputs` or `checkInputs`)