Metadata-Version: 2.4
Name: puppy-engine
Version: 1.2.3
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Software Distribution
License-File: LICENSE
Summary: Command-line companion for virtual environments, delivering rapid package discovery, deep security auditing, seamless dependency management, and instant updates.
Keywords: pypi,updater,cli,dependency-checker,security-audit,rust
Author-email: "Christian Joyce G. Garcia" <cjggarcia.dev@gmail.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<p align="center">
    <img src="https://gitlab.com/cjggarcia.dev/puppy/-/raw/main/assets/banner.png?ref_type=heads" alt="beaver banner">
</p>

<p align="center">
    <a href="https://pypi.org/project/puppy-engine/"><img src="https://img.shields.io/pypi/v/puppy-engine?style=flat-square&color=blue" alt="PyPI Version"></a>
    <a href="https://pypistats.com/packages/puppy-engine"><img src="https://pypistats.com/api/badges/puppy-engine?period=total" alt="PyPI Stats"></a>
    <a href="https://pypi.org/project/puppy-engine/"><img src="https://img.shields.io/badge/python-%3E%3D3.8-blue?style=flat-square&logo=python&logoColor=white" alt="Python Versions"></a>
    <a href="https://www.rust-lang.org/"><img src="https://img.shields.io/badge/rust-1.70%2B-orange?style=flat-square&logo=rust" alt="Rust Version"></a>
    <a href="https://gitlab.com/cjggarcia.dev/puppy"><img src="https://img.shields.io/badge/GitLab-repo-fc6d26?style=flat-square&logo=gitlab&logoColor=white" alt="GitLab"></a>
    <a href="https://pypi.org/project/puppy-engine/"><img src="https://img.shields.io/pypi/implementation/puppy-engine?style=flat-square" alt="Python Implementation"></a>
    <a href="https://gitlab.com/cjggarcia.dev/puppy-engine/-/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green?style=flat-square" alt="License"></a>
</p>

# Puppy

> Scan, audit and update your virtual environment in one command.

Puppy is a high-performance command-line companion for Python virtual environments written in [Rust](https://rust-lang.org/). It checks installed packages against [PyPI](https://pypi.org/) for newer releases and the [OSV](https://osv.dev/) database for known vulnerabilities, then installs, updates and removes packages natively from wheels.

Designed for low overhead and speed, Puppy ships as a single native binary installed through [pip](https://pip.pypa.io/). It works directly on the environment's `site-packages` and needs no external Python process to run (even `--init` is fully implemented natively in Rust).


## Table of Contents

- [Features](#features)
- [Feature Comparison](#feature-comparison)
- [Installation](#installation)
- [Usage](#usage)
    - [Scan](#scan)
    - [Update](#update)
    - [Install](#install)
    - [Uninstall](#uninstall)
    - [List and Inspect](#list-and-inspect)
    - [Export and Lock](#export-and-lock)
    - [Environment](#environment)
- [Arguments](#arguments)
- [Configuration](#configuration)
- [Lockfile Format](#lockfile-format)
- [Exit Codes and Errors](#exit-codes-and-errors)
- [Notes](#notes)
- [Changelog](#changelog)
- [License](#license)
- [Author](#author)


## Features


- **Fast discovery:** concurrent PyPI lookups to find outdated packages in seconds
- **Security auditing:** checks every installed package against the [OSV](https://osv.dev) vulnerability database
- **Cryptographic verification:** SHA-256 integrity checksum validation against trusted PyPI metadata digests
- **Atomic safe updates:** safety-first file swapping with automatic backup and rollback protection
- **Smart wheel selection:** automatic platform-aware matching for operating system, architecture, and universal binary distribution tags
- **Time-based release filtering:** `--exclude-newer` option to skip freshly published releases as a defense against typosquats and malware
- **Malware advisory scanning:** automatic inspection of OSV malware advisory databases (`MAL-` payloads)
- **Project configuration:** native `[tool.puppy]` settings support in `pyproject.toml`
- **Native updates:** downloads and installs wheels directly from PyPI, no `pip` required
- **Dry run:** preview updates without touching the disk
- **Ignore rules:** skip packages with `--ignore` or a `.puppyignore` file
- **Dependency management:** install, uninstall, export to `requirements.txt` and generate a lockfile
- **Environment diagnostics:** summary of the active virtual environment
- **Single binary:** written in Rust, distributed as a Python package


## Feature Comparison

| Feature | Puppy ([puppy-engine](https://pypi.org/project/puppy-engine/)) | [pip](https://pypi.org/project/pip/) | [uv](https://docs.astral.sh/uv/) |
| :--- | :--- | :--- | :--- |
| **Primary Language** | Rust | Python | Rust |
| **Speed & Performance** | **High** (Concurrent async PyPI/OSV checks) | **Slow** (Sequential, high overhead) | **Extremely High** (Blazing fast parallel resolution) |
| **Security Auditing** | **Yes** (OSV vulnerability & `MAL-` malware advisory checks) | **No** (Requires external tools like `pip-audit`) | **Yes** (Audit scanning via integration) |
| **Cryptographic Integrity** | **Yes** (Automatic SHA-256 wheel hash verification) | **Basic** (Relies on hashes if provided) | **Yes** (Strict cryptographic verification) |
| **Atomic Reliability & Rollback** | **Yes** (Automatic safe backup and rollback on extraction failure) | **No** (Can leave environment in a half-deleted/broken state) | **Yes** (Atomic directory replacement) |
| **Dependency Resolution** | **No** (Lightweight direct installation, explicit dependency management) | **Basic** (Linear dependency tree traversal) | **Advanced** (Lightning-fast backtracking resolver) |
| **Lockfile Support** | **Yes** (Generates JSON lockfiles `puppy.lock` / requirements export) | **No** (Native lockfile workflow absent) | **Yes** (Universal lockfiles `uv.lock`) |
| **Project Configuration** | **Yes** (`[tool.puppy]` section in `pyproject.toml`) | **Limited** (`setup.cfg` / `pyproject.toml` metadata only) | **Yes** (`[tool.uv]` section in `pyproject.toml`) |
| **Scope / Footprint** | **Targeted Companion** (Directly manages `site-packages` safely with zero Python overhead) | **Standard Package Manager** (Heavy Python runtime dependency) | **Comprehensive Manager** (Full toolchain, virtual environment & python manager) |

## Installation 

```bash
pip install puppy-engine
```

Verify the installation:

```bash
puppy --version 
```

> Requires Python 3.8 or newer. Most commands operate on the **active virtual environment** (`VIRTUAL_ENV`), so activate one first:
 
**Linux / macOS**
 
```bash
python3 -m venv .venv
source .venv/bin/activate
```
 
**Windows (PowerShell)**
 
```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
```

If PowerShell blocks the script, allow it for the current user once:

```powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```

**Windows (Command Prompt)**

```bat
python -m venv .venv
.venv\Scripts\activate.bat
```


Once activated, `puppy` is available on your `PATH` and every command in the [Usage](#usage) section works the same on all platforms.

## Usage

### Scan

Scan the active environment for outdated packages, vulnerabilities, and malware advisories.

```bash
puppy -s
```

### Update

```bash
puppy -u
```

Update specific packages only:
 
```bash
puppy -u requests django
```

Preview the changes without writing anything:

```bash
puppy -u --dry-run
```


Skip packages during an update:

```bash
puppy -u --ignore django --ignore numpy
```

### Install

Install a single package:

```bash
puppy -i requests
```

Install a single package with cryptographic verification and optional time-based filtering:

```bash
puppy -i requests --exclude-newer 7d
```

Install from a requirements file:

```bash
puppy -f requirements.txt
```

### Uninstall

Remove a package (asks for confirmation):

```bash
puppy -r requests
```

### List and Inspect

List installed packages:

```bash
puppy -l
```

Show PyPI metadata for a package (version, author, license, summary and recent releases):

```bash
puppy -d requests
```

### Export and Lock

Write installed packages to a requirements file:

```bash
puppy -w requirements.txt
```

Generate a lockfile (`puppy.lock`):

```bash
puppy --lock
```

### Environment

Create a new virtual environment (defaults to `.venv`):

```bash
puppy --init
puppy --init myenv
```

> `--init` provisions the virtual environment natively in Rust without invoking `python -m venv`.

Show a diagnostics summary of the active environment:

```bash
puppy --env
```


## Arguments

| Flag | Value | Description |
| --- | --- | --- |
| `-s` | - | Scan for updates and security vulnerabilities |
| `-u` | `[PACKAGE...]` | Update all or specific packages |
| `-l` | - | List installed packages |
| `-i` | `PACKAGE` | Install a package |
| `-f` | `FILE` | Install packages from a requirements file |
| `-d`, `--detail` | `PACKAGE` | Show PyPI metadata for a package |
| `-r`, `--remove` | `PACKAGE` | Uninstall a package |
| `-w` | `FILE` | Write installed packages to a requirements file |
| `--lock` | - | Generate `puppy.lock` |
| `--init` | `[NAME]` | Create a virtual environment (default `.venv`) |
| `--env` | - | Show environment diagnostics |
| `--dry-run` | - | Preview updates without changing anything |
| `--ignore` | `PACKAGE` | Skip a package during update (repeatable) |
| `--exclude-newer` | `DURATION` | Skip package releases published within a timeframe (e.g., `7d`, `24h`) |
| `-h`, `--help` | - | Show help |
| `-V`, `--version` | - | Show version |

## Configuration (`pyproject.toml`)

<selection-tag>If you are working inside a Python project that uses a `pyproject.toml` file, you can configure default `puppy` settings globally for that project by adding a `[tool.puppy]` section:</selection-tag>

```toml
[tool.puppy]
# Packages to ignore during updates
ignore = ["legacy-pkg"]

# Skip releases published within the specified timeframe (defense against fresh malware/typosquats)
exclude_newer = "7d"
```

> `puppy` automatically detects and honors these settings from your project's root `pyproject.toml`. Explicit command-line flags (such as `--ignore` or `--exclude-newer`) will override or extend these project defaults.


## Lockfile Format

`puppy --lock` writes `puppy.lock` to the current directory as pretty-printed JSON, with one entry per installed package:

```json
{
  "packages": [
    {
      "name": "requests",
      "version": "2.32.3"
    },
    {
      "name": "urllib3",
      "version": "2.2.3"
    }
  ]
}
```

`puppy -w <FILE>` writes a plain requirements file with one `name==version` pair per line:

```text
requests==2.32.3
urllib3==2.2.3
```

> Package names and versions are read from the `.dist-info` folders in `site-packages` and are automatically sorted alphabetically for readability.


## Exit Codes and Errors

| Code | Meaning |
| --- | --- |
| `0` | Command finished |
| `1` | Command failed |

When a command fails, Puppy prints `Error:` followed by the reason to standard error and exits with code `1`:

```text
Error: Could not locate active virtual environment site-packages.
```

During `-u` and `-i`, each package reports its own status. A failed package prints `FAILED`, the remaining packages continue, and the command still exits with `0`:

| Status | Cause |
| --- | --- |
| `FAILED (Network)` | The PyPI request could not be sent |
| `FAILED (Parse)` | The PyPI response could not be read |
| `FAILED (No compatible wheel)` | The package has no wheel available |
| `FAILED (Download)` | The wheel could not be downloaded |
| `FAILED (Invalid Wheel)` | The downloaded file is not a valid wheel |
| `FAILED (Extraction)` | The wheel could not be extracted into `site-packages` |

> `puppy -s` exits with `0` even when outdated or vulnerable packages are found.


## Notes

- Packages are installed from **wheels** only, source-only distributions are not supported.
- Supported on Linux, macOS and Windows. Run `puppy` from an activated virtual environment.
- Dependencies are not resolved automatically. Install required dependencies explicitly.
- Vulnerability data is provided by [OSV](https://osv.dev), version data by [PyPI](https://pypi.org).


## Changelog

See [CHANGELOG.md](https://gitlab.com/cjggarcia.dev/puppy/-/blob/main/CHANGELOG.md?ref_type=heads) for the list of changes in each release.

## License

This project is licensed under the [Apache License 2.0](https://gitlab.com/cjggarcia.dev/puppy/-/raw/main/LICENSE?ref_type=heads)

## Author

Created and maintained by [cjggarcia.dev](https://gitlab.com/cjggarcia.dev)
