pydepm 1.1.2
PyDepM — Python Dependency Manager
Requires Python: >=3.9

<h1 align="center">PyDepM</h1>

<p align="center">
  <img src="./pydep.png" alt="Dars Framework Logo" width="200" />
</p>

<p align="center">
  <em>PyDepM (Python Dependency Manager) is a modern, dependency management tool for Python projects that combines the simplicity of npm with Python's powerful packaging ecosystem. It provides two main tools: `pydep` for dependency management and project scaffolding, and `pydepx` for enhanced script execution.</em>
</p>

[![PyPI version](https://img.shields.io/pypi/v/pydepm.svg)](https://pypi.org/project/pydepm/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)


## Features

### **Pydep - Core Dependency Manager**
- **Project Scaffolding**: Initialize apps or modules with sensible defaults
- **Dependency Management**: Add, remove, and update dependencies with version pinning
- **Virtual Environment Management**: Automatic venv creation and management
- **Lockfile Support**: Generate and use `pypackage-lock.json` for reproducible installs
- **Build System**: Build wheels, sdists, and PyInstaller executables
- **Security Auditing**: Vulnerability scanning with `pip-audit`
- **Script Runner**: npm-like script execution from `pypackage.json`
- **Dependency Analysis**: Understand why packages are installed with `pydep why`
- **Easy migration** from pyproject.toml with ``` pydep convert --from toml ```

### **Pydepx - Enhanced Execution Tool**
- **Rich Output**: Beautiful, colorized command output with real-time streaming
- **Smart Module Execution**: Automatic Python module detection and execution
- **Cross-Platform**: Consistent behavior on Windows, macOS, and Linux
- **Signal Handling**: Graceful interrupt handling for long-running processes
- **Encoding Support**: Robust handling of various terminal encodings

## Installation

```bash
pip install pydepm
```

This installs both `pydep` and `pydepx` commands globally.

## Quick Start

### Create a New Project

```bash
# Create an application
pydep init --type app

# Or create a reusable module
pydep init my-module --type module 
```

### Manage Dependencies

```bash
# Install all dependencies
pydep install

# Add a package
pydep add requests
pydep add "flask>=2.0.0"

# Add with caret syntax (equivalent to npm's ^)
pydep add "numpy^1.24.0"

# Remove a package
pydep remove requests
```

### Run Scripts

```bash
# Run scripts defined in pypackage.json
pydep run dev
pydep run test

# Use pydepx for enhanced execution
pydepx black .                    # Run code formatter
pydepx -m pytest tests/          # Run tests as module
pydepx -m http.server 8000       # Run HTTP server
```

## Table of Contents

- [Project Structure](#project-structure)
- [pydep Commands](#pydep-commands)
- [pydepx Usage](#pydepx-usage)
- [Configuration](#configuration)
- [Advanced Features](#advanced-features)
- [Examples](#examples)
- [Contributing](#contributing)

## Project Structure

PyDepM uses a `pypackage.json` file to manage project configuration:

```json
{
  "type": "app",
  "name": "my-project",
  "version": "0.1.0",
  "description": "My Python application",
  "dependencies": {
    "requests": "^2.28.0",
    "rich": "==12.6.0"
  },
  "optionalDependencies": {
    "dev": {
      "pytest": ">=7.0.0",
      "pytest-cov": ">=4.0.0",
      "black": ">=23.0.0",
      "mypy": ">=1.0.0"
    },
    "test": {
      "pytest": ">=7.0.0",
      "pytest-asyncio": ">=0.20.0",
      "httpx": ">=0.23.0"
    },
    "docs": {
      "sphinx": ">=6.0.0",
      "sphinx-rtd-theme": ">=1.0.0"
    }
  },
  "scripts": {
    "dev": "python main.py",
    "test": "pytest tests/"
  },
  "useGlobalDeps": false
}
```

### Managing Optional Dependencies

Optional dependencies are grouped by purpose (e.g., `dev`, `test`, `docs`) and can be installed interactively when running `pydep install`:

```bash
# Install all optional dependencies
pydep install
```

PyDepM will prompt you to select which optional dependency groups to install during the installation process.

## pydep Commands

### Project Management
```bash
pydep init [name] [--type app|module]  # Initialize new project
pydep install [-e] [-g]                # Install dependencies
pydep build                            # Build package/executable
```

### Dependency Management
```bash
pydep add <package> [--global]         # Add package(s)
pydep remove <package> [--global]      # Remove package(s)
pydep update [packages] [--global]     # Update packages
pydep list                             # List installed packages
pydep why <package>                    # Show dependency reason
pydep outdated                         # Check for outdated packages
pydep config [--auto-resolve/--no-auto-resolve] [--resolve-strategy constraints|pin]
pydep clear-cache [--max-age DAYS]     # Clear package cache (default max-age is 30 days)
```

### Security & Quality
```bash
pydep audit [--json] [--extended]      # Security audit
pydep convert --to lock [--hashes]     # Generate lockfile
pydep convert --to toml [-o dir]       # Generate pyproject.toml
```

### Script Execution
```bash
pydep run <script>                     # Run project script
```

## pydepx Usage

`pydepx` enhances command execution with rich output and better handling:

```bash
# Direct command execution
pydepx black

# Module execution (python -m style)
pydepx -m pytest -v tests/
pydepx -m pip install package
pydepx -m http.server --bind 127.0.0.1 8000
```

## Configuration

### Project Types

**Application (app)**: Standalone applications with executable support
- Default project type
- Can build executables with PyInstaller
- Optional `pyproject.toml` generation

**Module (module)**: Reusable Python packages
- Always generates `pyproject.toml`
- Supports setuptools packaging
- CLI entry point generation

### Conflict Auto-Resolution and Output UX

- PyDepM now provides compact, colorized pip output by default. Noisy lines like "Collecting/Downloading/Building/Successfully ..." and PATH hints are hidden unless you pass `--logs`.
- When pip reports dependency conflicts, PyDepM summarizes the conflicts and offers to resolve them:
  - Option 1: Apply compatible constraints automatically (e.g., `starlette>=0.40.0,<0.50.0`).
  - Option 2: Manually specify versions/specs per package (e.g., `==0.49.0`).
  - Option 3: Skip.
- After a successful resolution, PyDepM persists the chosen specs to `pypackage.json` and regenerates the lockfile. If strategy is set to `pin`, PyDepM pins exact installed versions; otherwise it saves the resolved range constraints.
- Use `pydep outdated` to see a table and interactively choose:
  - Update all, select a subset, or exit (with a periodic-update tip). Versions are then pinned and the lockfile is regenerated.
- `pydep audit` shows a spinner while scanning; if 5+ vulnerable packages have fixes, PyDepM offers the same update menu.

Configure auto-resolution behavior at the project level:

```bash
# Always auto-resolve conflicts without prompting
pydep config --auto-resolve

# Choose strategy: ranges (constraints) or exact pins
pydep config --resolve-strategy constraints   # default
pydep config --resolve-strategy pin           # persist exact versions

# Show current settings
pydep config
```

### Publishing Modules

Use `pydep publish` to publish module-type projects to PyPI or TestPyPI. This is not available for app-type projects.

```bash
# Interactive flow (choose repo, enter API token)
pydep publish

# Or preselect repository and .env file
pydep publish --repo pypi --env-file .env
pydep publish --repo testpypi --env-file .env
```

- On first run, you'll be asked to choose repository:
  - `pypi` (live) or `testpypi` (sandbox)
- You'll be prompted for the API token and it will be stored in the `.env` file:
  - For PyPI: `PIPY_API`
  - For TestPyPI: `TESTPIPY_API`
- The following fields are persisted to `pypackage.json` (modules only):
  - `publishRepo`: `pypi` or `testpypi`
  - `publishEnvFile`: path to the `.env` file that contains the API keys

The publish command builds distribution artifacts (wheel and sdist) quietly and uploads them using Twine with `__token__` credentials. Use `--logs` to show full build/upload output; otherwise only concise status and errors are shown.

## Advanced Features

### Configuration Conversion
```bash
# Convert to pyproject.toml
pydep convert --to toml

# Convert from pyproject.toml to pypackage.json
pydep convert --from toml

# Generate lockfile (no hashes)
pydep convert --to lock

# Generate lockfile with SHA256 hashes
pydep convert --to lock --hashes
```

### Executable Building
For app-type projects, configure executables in `pypackage.json`:

```json
{
  "executable": {
    "target": "main.py",
    "parameters": ["--onefile", "--name=myapp"],
    "output": "dist/"
  }
}
```

Build with:
```bash
pydep build
```

### Custom pyproject.toml
For advanced use cases, you can provide custom `pyproject.toml` content:
```json
{
  "pyproject": {
    "[project.urls]": "https://github.com/ZtaMDev/PyDepM.git"
  }
}
```

or you can use the _raw option to put pyproject.toml content directly:

```json
{
  "_raw": "[project.urls] = 'https://github.com/ZtaMDev/PyDepM.git'"
}
```

## Examples

### Complete Workflow

```bash
# Create and set up a new module
pydep init --type module my-package
cd my-package

# Add dependencies
pydep add rich
pydep add "pytest^7.0.0" --dev

# Install everything
pydep install

# Run tests
pydep run test
# or with enhanced output
pydepx -m pytest tests/

# Build package
pydep build

# Security audit
pydep audit
```

### Development Scripts

Define scripts in `pypackage.json`:

```json
{
  "scripts": {
    "dev": "python main.py",
    "test": "pytest tests/ -v",
    "lint": "pylint src/",
    "format": "black . && isort ."
  }
}
```
 
## Branch Protection

The `CrystalMain` branch is protected with the following rules to ensure code quality:

### Required Status Checks
- Unit tests (all Python versions)
- Integration tests
- Performance tests
- Security audit
- No merge conflicts
  
### Pull Request Requirements
- 1 approval required
- Stale approvals dismissed on new commits
- Last push must be approved
- Conversation resolution required
- Linear history required 
 
### Admin Bypass
- Repository owner can bypass branch protection rules when needed

## Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](https://opensource.org/licenses/MIT) for details.

---

**PyDepM** makes Python dependency management intuitive and powerful, combining the best practices from modern development workflows with Python's rich ecosystem.