Metadata-Version: 2.4
Name: py-trkpac
Version: 0.4.0
Summary: Global Python package manager with SQLite tracking
Author: Aryan Duntley
License-Expression: MIT
Project-URL: Homepage, https://github.com/aryanduntley/py-trkpac
Project-URL: Repository, https://github.com/aryanduntley/py-trkpac
Project-URL: Issues, https://github.com/aryanduntley/py-trkpac/issues
Keywords: pip,package-manager,global,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# py-trkpac

A global Python package manager for linux that wraps pip with SQLite tracking. Install packages into a single shared directory, accessible from any terminal without activating a venv.

## Why

Python's default tooling pushes you toward virtual environments for everything. That's fine for project-specific dependencies, but for packages you use everywhere (pytest, requests, httpx, etc.), you end up with dozens of venvs all containing the same libraries.

py-trkpac gives you a single managed directory for globally available Python packages. It:

- Installs packages via pip into one target directory
- Tracks every package and its dependencies in SQLite
- Enforces one version per package (no silent duplicates)
- Detects dependency conflicts before they happen
- Manages your shell config (PATH/PYTHONPATH) automatically
- Works on Ubuntu without fighting PEP 668 (`externally-managed-environment`)

You still use venvs for project-specific needs. py-trkpac handles the rest.

## Install

Requires Python 3.13+. No external dependencies — uses only Python stdlib.

### From PyPI

```bash
pip install py-trkpac
py-trkpac init
```

### From PyPI (venv bootstrap)

On systems with PEP 668 (`externally-managed-environment`), use a temporary venv to bootstrap py-trkpac into its own managed directory:

```bash
# Create a temporary venv and install py-trkpac
python3 -m venv /tmp/trkpac-bootstrap
/tmp/trkpac-bootstrap/bin/pip install py-trkpac

# Initialize (sets up target directory, DB, and shell config)
/tmp/trkpac-bootstrap/bin/py-trkpac init

# Install py-trkpac into its own managed directory
/tmp/trkpac-bootstrap/bin/py-trkpac install py-trkpac

# Open a new terminal — py-trkpac is now on your PATH via the managed directory
# You can safely remove the bootstrap venv
rm -rf /tmp/trkpac-bootstrap
```

### From source (development)

```bash
git clone https://github.com/aryanduntley/py-trkpac.git
ln -s /path/to/py-trkpac/py-trkpac ~/.local/bin/py-trkpac
py-trkpac init
```

## Usage

### Initialize

```bash
py-trkpac init
py-trkpac init --target ~/my-python-libs
py-trkpac init --shell-config ~/.zshrc
```

Sets the target directory where packages will be installed. Creates the SQLite database and adds PATH/PYTHONPATH entries to your shell config using managed marker comments.

### Install packages

```bash
py-trkpac install requests httpx pytest
```

- Checks the database for existing packages before installing
- Warns if a package is already installed in system Python (`/usr/lib/python3/dist-packages/`) and asks before shadowing it
- Prompts on version conflicts or when a package is already installed as a dependency
- Runs pip with `--target` and `--upgrade`
- Records all installed packages and auto-detected dependencies in the database
- Only updates the database after pip reports success

### Install local projects

```bash
py-trkpac install /path/to/downloaded-project
py-trkpac install ~/Desktop/Projects/my-mcp-server
```

- Detects local directories with `pyproject.toml` or `setup.py`
- Installs via pip into the same target directory as PyPI packages
- Parses `pyproject.toml` to identify the package name and track it in the database
- Tracks the source path so you know where each local package came from
- Shows as "local" type in `py-trkpac list`
- To update after source changes, just re-run the install command

### Remove packages

```bash
py-trkpac remove selenium
```

- Warns if other packages depend on the one being removed
- Cleans up files using pip's RECORD manifest
- Prompts to remove orphaned dependencies that nothing else needs, recursively through the full dependency tree

### List packages

```bash
py-trkpac list
```

```
Package          Version      Type        Installed
---------------  -----------  ----------  ----------
aifp             0.1.0        local       2026-02-07
click            8.3.1        explicit    2026-02-07
cryptography     46.0.4       explicit    2026-02-07
certifi          2026.1.4     dependency  2026-02-07
cffi             2.0.0        dependency  2026-02-07
...

63 package(s): 17 explicit, 1 local, 45 dependencies
```

### List dependencies

```bash
py-trkpac list-deps pytest
```

```
pytest==9.0.2 depends on:
  packaging==26.0
  iniconfig==2.3.0
  pluggy==1.6.0

Required by:
  pytest-cov==7.0.0
```

### Update packages

```bash
py-trkpac update           # update all explicit packages
py-trkpac update requests  # update a specific package
```

### Rebuild after a Python upgrade

```bash
py-trkpac rebuild
```

Reinstalls every tracked package — explicit **and** local — for the Python
interpreter you are running now. Use this after an OS upgrade bumps your
system Python to a new minor version (e.g. 3.13 → 3.14). It prunes the
stale, ABI-incompatible compiled extensions, reinstalls explicit packages
(pip re-resolves their dependencies), and reinstalls local packages from
their tracked source paths.

### View/change config

```bash
py-trkpac config
py-trkpac config set target_path /new/path
```

## Surviving Python upgrades

A Python **minor**-version upgrade (3.13 → 3.14) is the one event that can
break a global package directory. Compiled (C-extension) packages — numpy,
cryptography, pydantic-core, lxml, etc. — ship `.so` files locked to the
exact CPython minor version they were built for. When your OS replaces the
interpreter, every one of them stops importing. This is fundamental to
CPython and affects pip, venv, pipx, and conda equally; the only real fix
is to reinstall them for the new interpreter.

py-trkpac is built to make this a known, one-command recovery rather than a
cryptic failure:

- **It tells you.** py-trkpac records the Python version your packages were
  installed under. If you run any command under a different interpreter, it
  prints a prominent warning naming the old and new versions and pointing
  you at the fix. (Databases created before this feature are detected
  automatically by inspecting installed binaries.)
- **It fixes it in one command.** `py-trkpac rebuild` reinstalls everything
  for the current Python and prunes the dead binaries.
- **The tool itself never breaks.** py-trkpac is pure standard library, so
  it has no compiled parts to invalidate. `py-trkpac init` installs a
  launcher that delegates to whatever `python3` is current (rather than
  pip's version-pinned `console_scripts` stub). Combined with
  self-installing py-trkpac into its own managed directory
  (`py-trkpac install py-trkpac`), the CLI keeps working across upgrades
  with zero intervention — only the *managed packages* need a `rebuild`.

> Tip: install py-trkpac into its own managed directory so it benefits from
> the resilient launcher. The PyPI bootstrap recipe above already does this.

## How it works

### Architecture

py-trkpac is a **policy layer** on top of pip. pip does all the real work (dependency resolution, downloading, building, installing). py-trkpac decides:

- Whether to install (conflict detection)
- Where to install (target directory)
- What to record (database tracking)
- When to prompt (user-facing decisions)

### Database

SQLite database stored at `<target_path>/.py-trkpac.db` with three tables:

- **config** — key/value settings (target path, shell config path)
- **packages** — every installed package (name, version, explicit vs dependency, dates)
- **package_dependencies** — many-to-many join table tracking which packages depend on which

Dependencies are packages too. numpy as a dependency of torch is a row in `packages` with `is_explicit=0`, linked via `package_dependencies`.

### Shell config management

py-trkpac manages a block in your shell config using marker comments:

```bash
# >>> py-trkpac managed >>>
export PATH="$HOME/python-libraries/bin:$PATH"
export PYTHONPATH="$HOME/python-libraries${PYTHONPATH:+:$PYTHONPATH}"
# <<< py-trkpac managed <<<
```

This block is added, updated, or removed idempotently. A backup of your shell config is created before the first modification.

### Package removal

Since `pip uninstall` doesn't work with `--target` installs, py-trkpac handles removal directly by parsing the RECORD file in each package's `.dist-info` directory and deleting the listed files.

## Project structure

```
py-trkpac/
├── py-trkpac                 # shell script entry point
├── src/
│   └── py_trkpac/
│       ├── __init__.py       # version
│       ├── __main__.py       # python -m py_trkpac
│       ├── cli.py            # argparse, command dispatch
│       ├── db.py             # SQLite schema and operations
│       ├── installer.py      # pip wrapper, metadata parsing, rebuild
│       ├── shell.py          # .bashrc management + resilient launcher
│       ├── health.py         # Python-version tracking, upgrade warning
│       └── utils.py          # name normalization, prompts
├── shell_configs/            # future OS support stubs
│   ├── bashrc.py
│   ├── zshrc.py
│   └── fish.py
├── pyproject.toml
└── .gitignore
```

## License

MIT
