Architecture

This page documents the technical architecture of conda-pypi, explaining how it integrates with conda and the internal organization of its components.

Plugin System Integration

conda-pypi is implemented as a conda plugin using conda’s official plugin architecture. This design enables seamless integration with conda’s existing workflows without requiring modifications to conda itself.

The plugin registers several hooks with conda’s plugin system. The subcommand hook adds the conda pypi subcommand to conda through conda_pypi.plugin.conda_subcommands(), providing conda pypi install for installing Python distribution packages with conversion (pending deprecation), conda pypi convert for converting Python projects without installing them, and conda pypi index for indexing a local directory of .whl files to create a local conda channel.

The plugin also registers two post-command hooks that extend conda’s existing commands. The environment protection hook triggers after install, create, update, and remove commands to automatically deploy EXTERNALLY-MANAGED files that prevent accidental pip (or any other Python install tool) usage. This is implemented through ensure_target_env_has_externally_managed().

Data Flow Architecture

Installation Flow

conda pypi install package
         ↓
CLI Argument Parsing
         ↓
Environment Validation
         ↓
Package Classification
         ↓
    Editable (-e)? ----Yes---→ Build local project to .conda --> Install --> Deploy EXTERNALLY-MANAGED
         ↓ No
Dependency Resolution
         ↓
Channel Search for Dependencies
         ↓
Convert Missing Wheels from Package Indexes
         ↓
Install via conda
         ↓
Deploy EXTERNALLY-MANAGED

Conversion Flow

conda pypi convert package
         ↓
Fetch from PyPI
         ↓
Download Wheels
         ↓
Convert to .conda
         ↓
Save to Output Directory

Index Flow

conda pypi index <directory>
         ↓
Validate Directory Structure
         ↓
Scan for .whl Files
         ↓
Extract Wheel Metadata
         ↓
Generate repodata.json
         ↓
noarch/repodata.json Created

Plugin Hook Flow

conda command executed
         ↓
Post-command hook?
    ↓           ↓
install/      install/create/
create        update/remove
    ↓           ↓
Process       Deploy
requirements  EXTERNALLY-
from indexes  MANAGED
    ↓           ↓
Install       Create marker
packages      files
from indexes

Key Design Principles

The architecture of conda-pypi is built around several key design principles that ensure effective integration between conda and Python packaging tools.

Conda-native integration is achieved by using conda’s official plugin system and leveraging conda’s existing infrastructure including solvers, channels, and metadata systems. This approach maintains full compatibility with existing conda workflows.

This hybrid approach resolves packages from conda channels and the local conversion cache, then fetches missing wheels from package indexes (PyPI by default). The system falls back to wheel conversion only when needed.

This architecture enables conda-pypi to provide a seamless bridge between conda and Python packaging tools while maintaining the integrity and benefits of both package management systems.