Metadata-Version: 2.4
Name: pip_json
Version: 0.1.1
Summary: Manage Python dependencies via a requirements.json file — npm-style, powered by pip.
Home-page: https://github.com/akbarhasanov/pip-json
Author: Akbar Hasanov
Author-email: hasanvakbar@gmail.com
License: MIT
Project-URL: Source, https://github.com/akbarhasanov/pip-json
Project-URL: Bug Tracker, https://github.com/akbarhasanov/pip-json/issues
Project-URL: Changelog, https://github.com/akbarhasanov/pip-json/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: packaging
Provides-Extra: testing
Requires-Dist: pytest; extra == "testing"
Dynamic: license-file

# pip-json

A lightweight dependency management layer on top of pip, inspired by npm's `package.json`.

`pip-json` introduces `requirements.json` as the project-level dependency manifest. It does not replace pip — it delegates all installs to pip while keeping your dependency intent and resolved state in JSON.

---

## Installation

```bash
pip install pip-json
```

For development:

```bash
pip install -e ".[testing]"
```

---

## Usage

### Install packages

```bash
pip-json install requests
pip-json install "requests>=2.0" flask
```

Installs via pip and writes the constraint to `requirements.json`. The resolved exact version is written to `requirements.lock.json`.

### Install from a project

```bash
pip-json install           # uses requirements.json in or above cwd
pip-json install .         # uses requirements.json in current directory
pip-json install ../other  # uses requirements.json in another directory
```

### Freeze the current environment

```bash
pip-json freeze
```

Captures all installed packages with exact versions into `requirements.lock.json`. Does not touch `requirements.json`.

### Sync the environment to your manifest

```bash
pip-json sync
```

Installs all packages listed in `requirements.json` (using their constraints) and updates `requirements.lock.json` with resolved versions.

---

## File Format

**`requirements.json`** — your project's dependency intent:

```json
{
  "dependencies": {
    "requests": ">=2.0",
    "flask": "*"
  }
}
```

**`requirements.lock.json`** — exact resolved versions, always co-located with `requirements.json`:

```json
{
  "dependencies": {
    "requests": "2.32.5",
    "flask": "3.1.0"
  }
}
```

Commit both files. `requirements.json` expresses what you want; `requirements.lock.json` records what pip resolved.

---

## File Discovery

`pip-json` treats dependency files as **project-scoped**, not environment-scoped.

Starting from the current directory, it walks up the directory tree until `requirements.json` is found. If none is found, it creates one in the current directory. This means:

- You can run `pip-json` from any subdirectory of your project.
- Monorepos with nested projects work as expected.

---

## Design

| Concern | Responsibility |
|---|---|
| Installing packages | pip (environment-level) |
| Recording dependency intent | `requirements.json` (project-level) |
| Recording resolved versions | `requirements.lock.json` (project-level) |

`pip-json` sits between your project and pip — a thin, predictable layer with no magic.

### Why JSON?

- Structured and machine-readable
- Easy to extend (dev deps, metadata, etc.)
- Familiar to developers coming from npm / yarn

### Why not modify pip?

pip has no plugin system and its internal APIs are unstable. A subprocess wrapper is more stable and simpler to reason about.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

---

## License

MIT — see [LICENSE](LICENSE).
