pypins 1.0.0

Professional runtime package manager for Python — install, manage and query packages directly from code

pypins

Professional Runtime Package Manager for Python

pypins provides a clean, secure, and powerful interface to manage Python packages directly from your code.
It eliminates the need for fragile subprocess calls while offering a simple and elegant API.

import pypins as pip

# Install packages programmatically
pip.install("requests>=2.31")

# Smart installation (only if missing)
pip.ensure_installed(["pandas", "numpy"])

# Check for outdated packages
outdated = pip.outdated()
for pkg in outdated[:3]:
    print(f"{pkg['name']}: {pkg['current_version']} → {pkg['latest_version']}")

# Full control with custom indexes
pip.install("torch", index_url="https://download.pytorch.org/whl/cpu")

pypins is designed for developers who need reliable, auditable, and maintainable dependency management inside applications, scripts, notebooks, and deployment tools.

Key Features

• Simple and Intuitive API — Perform complex pip operations with minimal code.
• Security First — Executes pip through the official python -m pip interface. No shell execution.
• Robust Input Validation — Prevents invalid or malicious package specifiers.
• Advanced Capabilities — Support for custom indexes, constraints, editable installs, and requirements files.
• High Performance — Leverages importlib.metadata for fast read operations.
• Rich Feedback — Detailed PipResult objects and a complete exception hierarchy.
• Special Utilities — outdated(), ensure_installed(), install_requirements(), and more.
• Zero External Dependencies — Lightweight and reliable in any environment.
• Production Ready — Fully typed, well-documented, and suitable for critical systems.

Installation

pip install pypins

Quick Examples

Basic Usage

from pypins import pip

# Install
pip.install("requests")

# Install with version constraint
pip.install("django>=4.2,<5.0")

# Install multiple
pip.install(["fastapi", "uvicorn[standard]"])

# Upgrade
pip.install("requests", upgrade=True)

# Quiet mode
pip.install("black", quiet=True)

Working with Custom Mirrors

pip.install(
    "torch",
    index_url="https://download.pytorch.org/whl/cpu"
)

# Multiple extra indexes
pip.install(
    "some-private-package",
    extra_index_urls=[
        "https://pypi.company.com/simple",
        "https://another-mirror.com/simple"
    ]
)

Checking Installed Packages

from pypins import pip

print(pip.is_installed("requests"))        # True / False
print(pip.get_version("requests"))         # "2.32.3"

for pkg in pip.list_installed():
    print(f"{pkg.name}=={pkg.version}")

print(pip.freeze())   # requirements.txt style string

Error Handling

from pypins import pip, PipError, PackageNotFoundError

try:
    pip.install("nonexistent-package-xyz")
except PipError as e:
    print("Installation failed:", e)
    print("stderr:", e.stderr)

API Reference

Function	Description	Returns
install()	Install package(s)	PipResult
uninstall()	Uninstall package(s)	PipResult
is_installed()	Check if package exists	bool
get_version()	Get installed version	str
list_installed()	List all installed packages	list[PackageInfo]
freeze()	Get pip freeze output	str

Security

• Never uses shell=True
• All package names are validated
• Uses the current Python interpreter (sys.executable -m pip)
• No arbitrary command execution

Roadmap (planned)

• Async support (async def install(...))
• Progress callbacks / rich live output
• requirements.txt support (pip.install_requirements("requirements.txt"))
• Virtual environment management helpers
• Better error messages with suggestions

License

MIT License

---

pypins — Because running pip from code should be simple and safe.