Skip to content

ekala-project/corepkgs / .agents/skills/python

python

Verified

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.

FileKindSize
SKILL.mdskill md4.5 KB
---
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;
  };
})
```
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 implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall