Skip to content

architecture.md

Latest commit

 

History

History
104 lines (92 loc) · 3.38 KB

architecture.md

File metadata and controls

104 lines (92 loc) · 3.38 KB

Architecture & Design

Core Philosophy: The Clean Host

PEM is built on the principle that the host operating system's Python installation should never be used for project execution. It is strictly for bootstrapping and system tools.

Virtual Environment Strategy

PEM uses a priority-based logic to determine which virtual environment to use for a given context:

  1. Priority 1: Project Root (.venv)

    • If a .venv directory exists in the project root, it is always preferred.
    • This ensures project isolation and reproducibility.

  2. Priority 2: Jupyter Fallback (~/.venvs/jupyter)

    • If the project is identified as a Jupyter project (via template or detection) and no local .venv exists, PEM uses a centralized managed environment optimized for Data Science.

  3. Priority 3: IDE Fallback (~/.venvs/${IDE_NAME})

    • If running within a known IDE (VS Code, PyCharm, etc.) and no other environment is found, PEM uses a centralized environment specific to that IDE.

  4. Priority 4: Default Fallback (~/.venvs/default)

    • Last resort for generic scripts.

Directory Structure

  • bin/: CLI entry point (pem).
  • scripts/lib/: Core logic libraries (logging, config, venv-manager).
  • scripts/commands/: Implementation of CLI commands.
  • configs/: Configuration templates.
  • docs/: Documentation.
  • tests/: Extensive Testing Suite.
  • examples/: End-to-End python-env-manager usage example scenarios.

Directory Structure Tree

python-env-manager/
├── bin/
│   └── pem
├── CHANGELOG.md
├── configs/
│   ├── antigravity/
│   ├── config.env.example
│   ├── cursor/
│   ├── jupyter/
│   ├── pycharm/
│   ├── vscode/
│   └── windsorf/
├── docs/
│   ├── advanced-usage.md
│   ├── architecture.md
│   ├── commands.md
│   ├── contributing.md
│   ├── ide-integration.md
│   ├── setup-guide.md
│   └── troubleshooting.md
├── examples/
│   ├── basic-usage/
│   ├── ci-cd-integration/
│   ├── custom-templates/
│   ├── demo-workflow.sh
│   └── multi-project-setup/
├── LICENSE
├── Makefile
├── README.md
├── scripts/
│   ├── commands/
│   │   ├── analytics.sh
│   │   ├── backup.sh
│   │   ├── doctor.sh
│   │   ├── init.sh
│   │   ├── list.sh
│   │   └── scan.sh
│   ├── create-ide-envs.sh
│   ├── init-system.sh
│   ├── lib/
│   │   ├── config.sh
│   │   ├── logging.sh
│   │   ├── os-detector.sh
│   │   ├── registry.sh
│   │   ├── utils.sh
│   │   └── venv-manager.sh
│   ├── project-templates/
│   │   ├── data-science/
│   │   ├── devops/
│   │   ├── install-templates.sh
│   │   ├── jupyter/
│   │   ├── standard/
│   │   └── web/
│   └── utils/
│       ├── analytics.sh
│       ├── backup.sh
│       ├── env-detector.sh
│       ├── os-detector.sh
│       ├── project-registry.sh
│       ├── security-scanner.sh
│       └── setup-tooling.sh
└── tests/
    ├── fixtures/
    ├── integration/
    ├── run_tests.sh
    ├── test_integration.sh
    └── unit/