Developer guide#

Welcome to the conda-pypi developer guide! This section provides comprehensive documentation for contributors and developers working on conda-pypi.

Overview#

conda-pypi is built as a conda plugin that provides better PyPI interoperability for the conda ecosystem. Understanding the architecture and development workflow is essential for contributing to the project.

Contents#

Architecture

Technical architecture, plugin system design, and data flow

Architecture

Developer Notes

Implementation details, technical insights, and development considerations

Developer notes

Marker conversion

How PEP 508 environment markers become repodata (when / extras)

PEP 508 marker conversion

Testing

Complete guide to running tests, writing tests, and using test infrastructure

Testing Guide

Getting Started with Development#

This project uses pixi for environment management. All development commands should be run through pixi.

The dev task installs the checkout in editable mode with pip after Pixi resolves and installs the dependencies. Conda now depends on a released conda-pypi, so including an editable PyPI dependency in the same solve causes a conflict. The editable install uses the locked dependencies and build tools without resolving additional packages. Tests, benchmarks, and docs run dev automatically.

Run pixi run -e <environment> dev before using the checkout in other commands, and again after reinstalling an environment. Changes to Python source files are available without reinstalling. Package versions continue to come from Git via hatch-vcs.

Python 3.10 remains supported. Its build and test environments prioritize Anaconda’s main channel and use conda-forge for dependencies unavailable there. The Python 3.10 feature also sets CONDA_CHANNELS for commands run inside these environments. Other environments use conda-forge, with Python 3.11 for docs.

Initial Setup#

# Clone the repository
git clone https://github.com/conda-incubator/conda-pypi.git
cd conda-pypi

# Setup the development environment
pixi run dev

Common Development Tasks#

# Run tests (Python 3.14)
pixi run -e test-py314 test

# Run tests with another Python version
pixi run -e test-py310 test
pixi run -e test-py311 test
pixi run -e test-py312 test
pixi run -e test-py313 test

# Run linting and formatting
pixi run pre-commit

# Build documentation
pixi run -e docs build-docs

# Run benchmarks
pixi run benchmark

Project Structure#

conda-pypi/
├── conda_pypi/          # Main package code
│   ├── plugin.py        # Conda plugin registration
│   ├── cli/             # Command-line interface
│   ├── build.py         # Wheel to conda conversion
│   ├── translate.py     # Python ↔ conda package metadata translation
│   ├── name_mapping.py  # Grayskull PyPI → conda package names
│   ├── markers.py       # PEP 508 markers → `[when=…]` on repodata
│   ├── convert_tree.py  # Dependency resolution
│   └── ...
├── tests/               # Test suite
├── docs/                # Documentation (Sphinx)
├── recipe/              # Conda recipe for building the package
└── pyproject.toml       # Python package and Pixi configuration

Contributing#

When contributing to conda-pypi:

Test with Multiple Python Versions: Use the provided pixi environments (test-py310 through test-py314)
Run Pre-commit Hooks: Always run pixi run pre-commit before committing
Update Documentation: Keep documentation in sync with code changes
Write Tests: Add tests for new features and bug fixes
Follow the Code Style: The project uses ruff for linting and formatting