pkpm 1.0.0

A Python-based CLI package manager that works like npm.

pkpm - The Python Package Manager

A Python-based CLI package manager that works like npm, designed to bring modern package management workflows to the Python ecosystem. pkpm simplifies dependency management, virtual environments, graph visualization, and environment variable handling.

Features

• Project Initialization: Instantly scaffold pkpm.json, create an isolated virtual environment (.pkpm/venv), and setup .gitignore / .pkpmignore.
• NPM-like CLI: Familiar commands like install, remove, update, and run.
• Smart Visualizations: Built-in AST-based import scanning to visualize your project's dependency graph in the terminal or export it as an interactive HTML graph.
• Environment Management: Auto-generate .env files based on static analysis of your source code.
• Shell Auto-activation: Optional shell hooks to automatically activate your virtual environment when you cd into your project directory.

---

Installation

You can install pkpm from PyPI using pip:

pip install pkpm

---

Usage

🚀 Getting Started

pkpm init

Initialize a new project in the current directory.

• Generates a pkpm.json manifest file.
• Creates an isolated virtual environment in .pkpm/venv.
• Generates .gitignore and .pkpmignore files.

---

📦 Package Management

pkpm install [packages]...

Install one or multiple packages.

• If no packages are provided, it installs all dependencies listed in pkpm.json.
• Uses --dry-run to preview what would be installed without modifying the system.

pkpm remove <packages>...

Uninstall one or multiple packages from the project's virtual environment.

• Uses --dry-run to preview removal.

pkpm update [packages]...

Update specific packages or all packages if none are specified.

pkpm run <script>

Execute a custom script defined in the scripts section of your pkpm.json.

---

🔍 Visualization & Analysis

pkpm viz [OPTIONS]

Visualize your project's structure or dependencies.

• --mode folder (default): Prints a visual folder tree in the terminal.
• --mode imports: Scans the AST to detect imports and generates an interactive, browser-based HTML dependency graph. Highlights circular imports if detected!
• --depth <int>: Set the maximum depth for the visualization (0 for infinite).

pkpm scan

Perform a fast scan of the project and print a file-level import graph directly in your terminal.

pkpm tree

Show the package dependency tree (similar to npm list). Available with --depth option.

pkpm doctor

Detect conflicts with existing package managers globally or locally within your project.

• --global: Scan the global pkpm registry for conflicts.

---

⚙️ Environment Variables (pkpm env)

pkpm includes experimental tools to statically analyze your code for os.environ or python-dotenv usage and scaffold .env files automatically.

pkpm env generate

Auto-generate .env files based on a project scan.

• --env <name>: Specify the environment target (e.g., development, production). Defaults to development.
• --all: Generate variants for development, production, and test simultaneously.

pkpm env check

Validate your current .env file against the variables actually expected by the codebase.

pkpm env export

Export your .env configuration.

• --format <docker|shell|json>: Export format.

---

💻 Shell Integration (pkpm shell)

Say goodbye to manually typing source venv/bin/activate!

pkpm shell init

Initialize shell hooks for auto-activation. Supports bash, zsh, and fish.

• --shell <name>: Target shell (default is bash). Provides a script snippet to add to your ~/.bashrc or ~/.zshrc. Once added, changing into a pkpm initialized directory will automatically activate your environment.

pkpm shell status

Check if you currently have a pkpm virtual environment active.

---

📄 License

MIT