282 lines
13 KiB
Plaintext
282 lines
13 KiB
Plaintext
Metadata-Version: 2.4
|
|
Name: pipmaster
|
|
Version: 1.0.10
|
|
Summary: A versatile Python package manager utility for simplifying package installation, updates, checks, and environment management.
|
|
Author-email: ParisNeo <parisneoai@gmail.com>
|
|
License-Expression: Apache-2.0
|
|
Project-URL: Homepage, https://github.com/ParisNeo/pipmaster
|
|
Project-URL: Repository, https://github.com/ParisNeo/pipmaster
|
|
Project-URL: Issues, https://github.com/ParisNeo/pipmaster/issues
|
|
Keywords: pip,package manager,installer,dependency,venv,environment
|
|
Classifier: Development Status :: 4 - Beta
|
|
Classifier: Intended Audience :: Developers
|
|
Classifier: Programming Language :: Python :: 3.8
|
|
Classifier: Programming Language :: Python :: 3.9
|
|
Classifier: Programming Language :: Python :: 3.10
|
|
Classifier: Programming Language :: Python :: 3.11
|
|
Classifier: Programming Language :: Python :: 3.12
|
|
Classifier: Operating System :: OS Independent
|
|
Classifier: Topic :: Software Development :: Build Tools
|
|
Classifier: Topic :: System :: Software Distribution
|
|
Classifier: Typing :: Typed
|
|
Requires-Python: >=3.8
|
|
Description-Content-Type: text/markdown
|
|
License-File: LICENSE
|
|
Requires-Dist: packaging>=21.0
|
|
Requires-Dist: ascii_colors>=0.8.0
|
|
Provides-Extra: audit
|
|
Requires-Dist: pip-audit>=2.5.0; extra == "audit"
|
|
Provides-Extra: dev
|
|
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
Requires-Dist: pytest-asyncio>=0.20; extra == "dev"
|
|
Requires-Dist: pip-audit>=2.5.0; extra == "dev"
|
|
Requires-Dist: sphinx>=5.0; extra == "dev"
|
|
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "dev"
|
|
Requires-Dist: myst-parser>=0.17; extra == "dev"
|
|
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
Requires-Dist: mypy>=1.0; extra == "dev"
|
|
Requires-Dist: black; extra == "dev"
|
|
Requires-Dist: cowsay; extra == "dev"
|
|
Provides-Extra: all
|
|
Requires-Dist: pipmaster[audit]; extra == "all"
|
|
Requires-Dist: pipmaster[dev]; extra == "all"
|
|
Dynamic: license-file
|
|
|
|
# `pipmaster`: The Python Package Management Toolkit
|
|
|
|
<!-- Badges -->
|
|
[](https://badge.fury.io/py/pipmaster)
|
|
[](https://pypi.org/project/pipmaster/)
|
|
[](https://github.com/ParisNeo/pipmaster/blob/main/LICENSE)
|
|
[](https://github.com/ParisNeo/pipmaster/actions/workflows/docs.yml)
|
|
[](https://github.com/ParisNeo/pipmaster)
|
|
[](https://parisneo.github.io/pipmaster/)
|
|
|
|
Stop telling your users to `pip install -r requirements.txt`. Start building professional, self-sufficient Python applications that **just work**.
|
|
|
|
`pipmaster` is the ultimate toolkit for declarative and programmatic package management. It provides a robust, unified interface to backends like **`pip`** and **`uv`**, allowing you to automate installations, updates, and environment validation directly from your Python code. With both **synchronous and asynchronous APIs**, it's designed to guarantee that your applications work out-of-the-box by programmatically ensuring all dependencies are correctly installed.
|
|
|
|
**View the full documentation at [parisneo.github.io/pipmaster/](https://parisneo.github.io/pipmaster/).**
|
|
|
|
## Why `pipmaster`? The Power to Build Better Software
|
|
|
|
`pipmaster` bridges the gap between development and deployment, solving the classic "it works on my machine" problem.
|
|
|
|
* **Automate Your Setup:** Create a seamless first-time experience. Instead of manual setup steps, your application can configure its own environment on launch.
|
|
* **Write Self-Healing Applications:** Programmatically verify dependencies every time your app runs. If a user accidentally uninstalls a critical package, your application can detect it and fix itself.
|
|
* **Eliminate "Dependency Hell" for Users:** By managing dependencies automatically, you remove the biggest source of friction for non-technical users and simplify deployment for everyone.
|
|
* **Simplify Complex Projects:** Effortlessly manage dependencies across multiple virtual environments, build servers, or CI/CD pipelines from a single, consistent interface.
|
|
* **Code with Confidence:** Use the `dry_run` mode to safely preview any changes before they are made, and leverage the `verbose` flag for crystal-clear debugging.
|
|
* **Future-Proof Your Scripts:** With a multi-backend architecture (`pip`, `uv`, and `conda` planned), your automation scripts remain stable even as the packaging ecosystem evolves.
|
|
|
|
## Key Use Cases
|
|
|
|
`pipmaster` is the swiss army knife for anyone who builds and ships Python software.
|
|
|
|
* **Desktop GUI Applications (PyQt, Tkinter, etc.):** Ensure all UI libraries and dependencies are met on the very first launch, providing a smooth, installer-like experience.
|
|
* **Command-Line Tools (Click, Typer, Argparse):** Create a fantastic user experience by having your CLI tool install its own dependencies, making it instantly usable.
|
|
* **Data Science & ML Projects:** Guarantee that team members, servers, and Docker containers all share the exact same environment state by running an `ensure_requirements` check at the start of a script.
|
|
* **CI/CD & Automation Scripts:** Programmatically prepare a build environment, install testing tools, and deploy your application with reliable, repeatable Python code instead of brittle shell scripts.
|
|
* **Libraries and Frameworks:** Provide helper scripts for users to set up a correct environment, or use it internally to manage complex testing dependencies.
|
|
|
|
## Feature Overview
|
|
|
|
| Feature | `pip` Backend | `uv` Backend (Experimental) | `async` Support |
|
|
| -------------------------------------------- | :-----------: | :-------------------------: | :-------------: |
|
|
| **Ensure Package State (`ensure_packages`)** | ✅ | ❌ | ✅ |
|
|
| **Ensure from `requirements.txt`** | ✅ | ❌ | ✅ |
|
|
| Install / Upgrade Packages | ✅ | ✅ | ✅ |
|
|
| Uninstall Packages | ✅ | ✅ | ✅ |
|
|
| Check for Vulnerabilities (`pip-audit`) | ✅ | N/A | ✅ |
|
|
| Check Installed Status (`is_installed`) | ✅ | N/A | (Sync) |
|
|
| Create Virtual Environments | N/A | ✅ | N/A |
|
|
| Run Ephemeral Tools (`uvx`) | N/A | ✅ | N/A |
|
|
| Dry Run Mode | ✅ | ❌ | ✅ |
|
|
|
|
## Installation
|
|
|
|
`pipmaster` requires Python 3.8 or higher.
|
|
|
|
```bash
|
|
pip install pipmaster
|
|
```
|
|
|
|
### Optional Features
|
|
|
|
* **Vulnerability Auditing (`pip-audit`):**
|
|
```bash
|
|
pip install pipmaster[audit]
|
|
```
|
|
* **Development Environment (for contributors):**
|
|
```bash
|
|
git clone https://github.com/ParisNeo/pipmaster.git
|
|
cd pipmaster
|
|
pip install -e .[dev]
|
|
```
|
|
* **All Extras:**
|
|
```bash
|
|
pip install pipmaster[all]
|
|
```
|
|
|
|
## The Core Concept: Declarative & Idempotent Management
|
|
|
|
The `ensure_*` methods are the heart of `pipmaster`. They are **idempotent**, meaning you can run them a thousand times, and they will only perform an action if the environment is out of sync with your declarations.
|
|
|
|
They are also **efficient**. `pipmaster` checks all requirements first, then triggers a *single, batch installation command* only for the packages that are missing or outdated. This is far superior to running multiple `pip install` commands in a loop.
|
|
|
|
### `ensure_packages`: Define Dependencies Directly in Code
|
|
|
|
This is the most powerful feature for creating self-contained applications. Define dependencies as a simple string, a list, or a dictionary.
|
|
|
|
```python
|
|
import pipmaster as pm
|
|
|
|
# 1. Simple: Ensure a single package is present
|
|
pm.ensure_packages("rich")
|
|
|
|
# 2. List: Ensure multiple packages, with version specifiers
|
|
pm.ensure_packages(["pandas", "numpy>=1.20"], verbose=True)
|
|
|
|
# 3. Dictionary: A clean way to manage a set of requirements
|
|
requirements = {
|
|
"requests": ">=2.25.0",
|
|
"tqdm": None # Any version is acceptable
|
|
}
|
|
pm.ensure_packages(requirements, verbose=True)
|
|
```
|
|
|
|
### `ensure_requirements`: Automate Your `requirements.txt` Workflow
|
|
|
|
Use your existing `requirements.txt` files and let `pipmaster` handle the rest. It's the perfect one-line replacement for manual installation commands.
|
|
|
|
```python
|
|
import pipmaster as pm
|
|
|
|
# Create a demo file
|
|
with open("requirements-demo.txt", "w") as f:
|
|
f.write("rich\n")
|
|
f.write("packaging>=21.0\n")
|
|
|
|
# Ensure the environment matches the file
|
|
if pm.ensure_requirements("requirements-demo.txt", verbose=True):
|
|
print("\nEnvironment is in sync with requirements file!")
|
|
```
|
|
|
|
## Advanced Usage & Recipes
|
|
|
|
### Recipe 1: Conditional Installation from Git
|
|
|
|
Imagine you need cutting-edge features from a Git branch, but only if the user has an older version installed. `ensure_packages` handles this advanced logic with a special dictionary format.
|
|
|
|
```python
|
|
import pipmaster as pm
|
|
|
|
# This rule says: "We need diffusers version 0.25.0 or newer.
|
|
# If the installed version doesn't meet this, install from the main branch on GitHub."
|
|
conditional_requirement = {
|
|
"name": "diffusers",
|
|
"vcs": "git+https://github.com/huggingface/diffusers.git",
|
|
"condition": ">=0.25.0"
|
|
}
|
|
|
|
# First, let's install an old version to see it trigger
|
|
pm.install("diffusers==0.24.0", verbose=True)
|
|
|
|
print("\n--- Running ensure_packages with a conditional Git requirement ---")
|
|
pm.ensure_packages([conditional_requirement], verbose=True)
|
|
print(f"Post-check diffusers version: {pm.get_installed_version('diffusers')}")
|
|
|
|
print("\n--- Running it again (should do nothing) ---")
|
|
# Now that a newer version is installed, the condition is met, and pipmaster takes no action.
|
|
pm.ensure_packages([conditional_requirement], verbose=True)
|
|
|
|
```
|
|
|
|
### Recipe 2: Synchronous vs. Asynchronous API
|
|
|
|
Every core function has an `async` equivalent. Just prefix with `async_` and `await` the call.
|
|
|
|
```python
|
|
import pipmaster as pm
|
|
import asyncio
|
|
|
|
# Synchronous call
|
|
pm.install("httpx")
|
|
|
|
# Asynchronous equivalent
|
|
async def main():
|
|
await pm.async_install("httpx")
|
|
await pm.async_ensure_requirements("requirements.txt")
|
|
|
|
# asyncio.run(main()) # Uncomment to run
|
|
```
|
|
|
|
### Recipe 3: Using the `uv` Backend
|
|
|
|
Take advantage of `uv`'s incredible speed for creating environments and installing packages. This requires `uv` to be installed on your system's PATH.
|
|
|
|
```python
|
|
from pipmaster import get_uv_manager
|
|
import os
|
|
import shutil
|
|
|
|
temp_env_path = "./my_uv_test_env"
|
|
|
|
try:
|
|
# Get a manager that is NOT tied to the current environment
|
|
uv_manager = get_uv_manager()
|
|
|
|
# Create a new, empty venv
|
|
if uv_manager.create_env(path=temp_env_path):
|
|
print("uv environment created successfully.")
|
|
|
|
# The manager now targets the new environment for all subsequent calls
|
|
uv_manager.install_multiple(["numpy", "pandas"], verbose=True)
|
|
print("Packages installed in the new environment.")
|
|
|
|
# Use uvx to run a tool in an ephemeral environment
|
|
print("\n--- Running black --version with uv's tool runner ---")
|
|
uv_manager.run_with_uvx(["black", "--version"], verbose=True)
|
|
|
|
except FileNotFoundError:
|
|
print("Skipping uv examples: 'uv' executable not found in PATH.")
|
|
finally:
|
|
if os.path.exists(temp_env_path):
|
|
shutil.rmtree(temp_env_path)
|
|
```
|
|
|
|
### Recipe 4: Environment Inspection and Safety
|
|
|
|
Check packages without changing anything, and audit for security vulnerabilities.
|
|
|
|
```python
|
|
import pipmaster as pm
|
|
|
|
# --- Inspection (Fast, synchronous calls) ---
|
|
if pm.is_installed("requests", version_specifier=">=2.20"):
|
|
print(f"Requests version {pm.get_installed_version('requests')} is compatible.")
|
|
|
|
# --- Safety: Dry Run ---
|
|
print("\n--- Previewing changes with Dry Run ---")
|
|
pm.ensure_packages({"numpy": "<1.20"}, dry_run=True, verbose=True)
|
|
|
|
# --- Safety: Vulnerability Audit ---
|
|
print("\n--- Checking for Vulnerabilities ---")
|
|
try:
|
|
vulnerabilities_found, report = pm.check_vulnerabilities()
|
|
if vulnerabilities_found:
|
|
print("WARNING: Vulnerabilities found!")
|
|
else:
|
|
print("No known vulnerabilities found in the environment.")
|
|
except FileNotFoundError:
|
|
print("Skipping check: pip-audit not found. Install with 'pip install pipmaster[audit]'")
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! If you find a bug, have a feature request, or want to contribute code, please check the GitHub Issues page before opening a new issue or submitting a pull request.
|
|
|
|
## License
|
|
|
|
This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.
|