Metadata-Version: 2.4
Name: pypins
Version: 1.0.0
Summary: Professional runtime package manager for Python — install, manage and query packages directly from code
Author: PyHPDev
License: MIT
Project-URL: Homepage, https://github.com/PyHPDev/pypirun
Project-URL: Repository, https://github.com/PyHPDev/pypirun
Project-URL: Issues, https://github.com/PyHPDev/pypirun/issues
Keywords: pip,package,install,dependency,runtime,pypins
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Software Distribution
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

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

```python
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

```bash
pip install pypins
```

## Quick Examples

### Basic Usage

```python
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

```python
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

```python
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

```python
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.
