Metadata-Version: 2.4
Name: pkpm
Version: 1.0.0
Summary: A Python-based CLI package manager that works like npm.
Author: pkpm authors
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: networkx>=3.0
Requires-Dist: pyvis>=0.3.2
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic>=2.0.0

# 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:

```bash
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
