Skip to content

README.md

Latest commit

 

History

History
171 lines (129 loc) · 4.95 KB

README.md

File metadata and controls

171 lines (129 loc) · 4.95 KB

Python Environment Manager (PEM)

CI License Platform

Python Environment Manager (PEM)

A production-grade, cross-platform Python environment manager that enforces clean development practices and streamlines virtual environment workflows with IDE awareness.

Version

Current: 1.1.0 License: MIT

Key Features

🧠 IDE-Aware Virtual Environment Management (NEW in v1.1.0)

  • Automatic IDE Detection: Recognizes VSCode, PyCharm, Cursor, AntiGravity, Windsorf, and Jupyter
  • Project Type Detection: Identifies jupyter, data-science, web, and standard projects
  • Managed Environments: Centralized venvs in ~/.venvs/* (default, jupyter, IDE-specific)
  • Smart Priority Logic: Project Root → Jupyter Managed → IDE Managed → Default Fallback
  • Host Python Protection: All pip installs go to managed venvs, never to system Python

New CLI Commands:

pem init-venvs    # Initialize all managed virtual environments
pem list-venvs    # List all managed venvs with Python versions

🌍 Cross-Platform Package Management (NEW in v1.1.0)

Universal package manager abstraction supporting:

  • Linux: apt, dnf, yum, pacman, zypper, apk
  • macOS: brew
  • Windows: choco

🔒 Production-Grade Project Templates (ENHANCED in v1.1.0)

All templates now include:

  • ✅ Pinned dependency versions for reproducibility
  • ✅ Security-focused package selection
  • ✅ Testing and code quality tools

Available Templates:

  • standard: Modern Python with pyproject.toml, pytest, ruff, black, mypy
  • web: FastAPI stack with uvicorn, pydantic, sqlalchemy, authentication
  • jupyter: JupyterLab with pandas, matplotlib, plotly, ipywidgets
  • data-science: Conda environment with scikit-learn, numpy, seaborn
  • devops: Ansible, boto3, docker, kubernetes, cloud SDKs

🧪 Testing Infrastructure (NEW in v1.1.0)

  • bats-core: Unit testing for shell scripts
  • Code Coverage: kcov integration
  • Makefile Targets: test-unit, test-all, test-coverage

✨ Core Features (from v1.0.0)

  • Unified CLI: Single pem command for all operations
  • Cross-Platform Support: Linux (Debian, RHEL, Arch), macOS, Windows WSL2
  • Configuration: Customizable via ~/.config/python-env-manager/config.env
  • Security: Vulnerability scanning with pem scan
  • Health Checks: System diagnostics with pem doctor
  • Analytics: Local usage tracking (opt-in)
  • Shell Completion: Bash and Zsh support

Quick Start

Installation

git clone https://github.com/freddiedfre/python-env-manager.git
cd python-env-manager
make install

Initialize Managed Virtual Environments

# Create all managed venvs (~/.venvs/*)
pem init-venvs

# List all managed environments
pem list-venvs

Create a New Project

# Standard Python project
pem init my-project --type standard

# Jupyter/Data Science project (auto-uses ~/.venvs/jupyter)
pem init my-notebook --type jupyter

# Web application with FastAPI
pem init my-api --type web

Usage

Virtual Environment Priority

PEM automatically selects the best virtual environment:

  1. Project Root (.venv in project directory) - always first choice
  2. Jupyter Managed (~/.venvs/jupyter) - for jupyter/data-science projects
  3. IDE Managed (~/.venvs/vscode, ~/.venvs/pycharm, etc.) - for IDE-specific work
  4. Default Fallback (~/.venvs/default) - keeps host Python clean

Management Commandsnd backups.

  • Configurable: Customize default packages, paths, and behavior via config.env.

📥 Installation

  1. Clone the repository:

    git clone https://github.com/freddiedfre/python-env-manager.git
cd python-env-manager

  2. Install:

    make install

    This installs pem to ~/.local/bin and sets up configuration.

  3. Shell Completion (Optional): Add the following to your .bashrc or .zshrc:

    source ~/.local/share/python-env-manager/scripts/utils/completion.sh

🛠️ Usage

Initialize a Project

pem init my-app standard

Creates a new project with a .venv, installs dependencies, and configures VS Code.

List Projects

pem list

Check System Health

pem doctor

Scan for Vulnerabilities

pem scan

Manage Backups

pem backup

📚 Documentation

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.