ekala-project/corepkgs / .agents/skills/python
python
VerifiedPackage a Python project for corepkgs. Use when writing or editing python/pkgs/<name>/default.nix — covers buildPythonPackage, pyproject, build-system, dependencies, testPaths, pytestCheckHook, disabledTests, and pythonImportsCheck.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
SKILL.md
View on GitHub---
name: python
description: Package a Python project for corepkgs. Use when writing or editing python/pkgs/<name>/default.nix — covers buildPythonPackage, pyproject, build-system, dependencies, testPaths, pytestCheckHook, disabledTests, and pythonImportsCheck.
---
# Python Packages
Python packages live in `python/pkgs/<name>/default.nix`.
## Minimal Example
```nix
{
lib,
buildPythonPackage,
fetchFromGitHub,
setuptools,
pytestCheckHook,
}:
buildPythonPackage (finalAttrs: {
pname = "example";
version = "1.0.0";
pyproject = true;
src = fetchFromGitHub {
owner = "example";
repo = "example";
tag = "v${finalAttrs.version}";
hash = "sha256-...";
};
build-system = [ setuptools ];
nativeCheckInputs = [ pytestCheckHook ];
testPaths = [ "tests" ];
pythonImportsCheck = [ "example" ];
meta = {
description = "Example Python library";
license = lib.licenses.mit;
};
})
```
## Essential Attributes
- `pyproject = true;` — use pyproject.toml-based build (preferred over legacy `format = "setuptools"`)
- `build-system` — list of build backends: `setuptools`, `hatchling`, `flit-core`, `poetry-core`, `maturin`, `pdm-backend`, `setuptools-scm`
- `dependencies` — runtime Python dependencies
- `optional-dependencies` — attrset of extras groups
- `disabled = pythonOlder "3.9";` — skip on older interpreters
## Testing
`passthru.tests.python` is auto-generated whenever a package has test inputs
(`nativeCheckInputs` or `nativeTestOnlyCheckInputs`).
### With `testPaths` (preferred)
When `testPaths` is set, only the listed files/dirs are copied into a `test_src`
output and used by the test derivation:
```nix
nativeCheckInputs = [ pytestCheckHook ];
testPaths = [ "tests" ];
```
For suites needing extra files: `testPaths = [ "tests" "src/helpers" "README.rst" ];`
### Without `testPaths`
When `testPaths` is omitted but check inputs exist, the test derivation uses
the full source. This is useful when tests live alongside the source code.
### Breaking circular dependencies
For packages in the pytest dependency chain (e.g. `attrs`, `pluggy`), use
`nativeTestOnlyCheckInputs` instead of `nativeCheckInputs`. These deps are
completely invisible to the main derivation and only appear in the test
derivation, avoiding cycles:
```nix
nativeTestOnlyCheckInputs = [ pytestCheckHook ];
testPaths = [ "tests" ];
```
### Forwarded attributes
These attributes are forwarded automatically to the test derivation:
- `disabledTests`, `disabledTestPaths`, `enabledTestPaths`
- `pytestFlags`, `pytestFlagsArray`, `unittestFlagsArray`
- `preCheck`, `postCheck`, `preInstallCheck`, `postInstallCheck`
### Disabling Tests
```nix
disabledTests = [
"test_network_access" # requires internet
"test_flaky_timing" # non-deterministic
];
disabledTestPaths = [
"tests/integration/" # needs running service
];
```
Platform-conditional disabling:
```nix
disabledTests = [
"test_basic"
] ++ lib.optionals stdenv.hostPlatform.isDarwin [
"test_linux_specific"
];
```
## Smoke Checks
`pythonImportsCheck` runs automatically during `buildPythonPackage` — no need to enable `doInstallCheck`:
```nix
pythonImportsCheck = [ "requests" "requests.auth" ];
```
## Removing Unwanted Build Dependencies
When upstream pins a dependency unavailable in corepkgs:
```nix
pythonRemoveDeps = [ "some-unavailable-dep" ];
```
## Complete Example
```nix
{
lib,
stdenv,
buildPythonPackage,
fetchFromGitHub,
pythonOlder,
setuptools,
certifi,
charset-normalizer,
idna,
urllib3,
pysocks,
pytest-mock,
pytestCheckHook,
}:
buildPythonPackage (finalAttrs: {
pname = "requests";
version = "2.34.2";
pyproject = true;
disabled = pythonOlder "3.9";
src = fetchFromGitHub {
owner = "psf";
repo = "requests";
tag = "v${finalAttrs.version}";
hash = "sha256-...";
};
build-system = [ setuptools ];
dependencies = [
certifi
charset-normalizer
idna
urllib3
];
optional-dependencies = {
socks = [ pysocks ];
};
nativeCheckInputs = [
pytest-mock
pytestCheckHook
] ++ finalAttrs.optional-dependencies.socks;
disabledTests = [
"test_redirecting_to_bad_url" # requires network
] ++ lib.optionals stdenv.hostPlatform.isDarwin [
"test_basic_response" # Fatal Python error on aarch64-darwin
];
testPaths = [ "tests" ];
pythonImportsCheck = [ "requests" ];
meta = {
description = "HTTP library for Python";
homepage = "https://docs.python-requests.org/";
license = lib.licenses.asl20;
};
})
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |