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.

Python Packages

Python packages live in python/pkgs/<name>/default.nix.

Minimal Example

{
  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:

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:

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

disabledTests = [
  "test_network_access"     # requires internet
  "test_flaky_timing"       # non-deterministic
];

disabledTestPaths = [
  "tests/integration/"      # needs running service
];

Platform-conditional disabling:

disabledTests = [
  "test_basic"
] ++ lib.optionals stdenv.hostPlatform.isDarwin [
  "test_linux_specific"
];

Smoke Checks

pythonImportsCheck runs automatically during buildPythonPackage — no need to enable doInstallCheck:

pythonImportsCheck = [ "requests" "requests.auth" ];

Removing Unwanted Build Dependencies

When upstream pins a dependency unavailable in corepkgs:

pythonRemoveDeps = [ "some-unavailable-dep" ];

Complete Example

{
  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