PyDepM

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.

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

pip install pydepm

This installs both pydep and pydepx commands globally.

Quick Start

Create a New Project

# Create an application
pydep init --type app

# Or create a reusable module
pydep init my-module --type module 

Manage Dependencies

# 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

# 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
• pydep Commands
• pydepx Usage
• Configuration
• Advanced Features
• Examples
• Contributing

Project Structure

PyDepM uses a pypackage.json file to manage project configuration:

{
  "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:

# 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

pydep init [name] [--type app|module]  # Initialize new project
pydep install [-e] [-g]                # Install dependencies
pydep build                            # Build package/executable

Dependency Management

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

pydep audit [--json] [--extended]      # Security audit
pydep convert --to lock [--hashes]     # Generate lockfile
pydep convert --to toml [-o dir]       # Generate pyproject.toml

Script Execution

pydep run <script>                     # Run project script

pydepx Usage

pydepx enhances command execution with rich output and better handling:

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

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

# 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

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

{
  "executable": {
    "target": "main.py",
    "parameters": ["--onefile", "--name=myapp"],
    "output": "dist/"
  }
}

Build with:

pydep build

Custom pyproject.toml

For advanced use cases, you can provide custom pyproject.toml content:

{
  "pyproject": {
    "[project.urls]": "https://github.com/ZtaMDev/PyDepM.git"
  }
}

or you can use the _raw option to put pyproject.toml content directly:

{
  "_raw": "[project.urls] = 'https://github.com/ZtaMDev/PyDepM.git'"
}

Examples

Complete Workflow

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

{
  "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 for details.

License

MIT License - see LICENSE for details.

---

PyDepM makes Python dependency management intuitive and powerful, combining the best practices from modern development workflows with Python's rich ecosystem.