Python Environment Manager (PEM)

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

• Setup Guide
• Architecture & Design
• Command Reference
• IDE Integration
• Advanced Usage
• Troubleshooting
• Contributing

🤝 Contributing

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