Metadata-Version: 2.4
Name: reqsync
Version: 0.1.5
Summary: Synchronize requirements files to installed versions safely and atomically.
Project-URL: Homepage, https://github.com/ImYourBoyRoy/reqsync
Project-URL: Repository, https://github.com/ImYourBoyRoy/reqsync
Project-URL: Bug Tracker, https://github.com/ImYourBoyRoy/reqsync/issues
Author-email: Roy Dawson IV <Roy.Dawson.IV@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,ai-tool,automation,cli-tool,dependencies,dependency-management,mcp,packaging,pip,requirements,venv
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: packaging>=24.1
Requires-Dist: portalocker<3,>=2.7
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Requires-Dist: typing-extensions>=4.7; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == 'dev'
Requires-Dist: mcp>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: pretty
Requires-Dist: rich>=13.7; extra == 'pretty'
Description-Content-Type: text/markdown

# reqsync

Keep your `requirements.txt` (and included requirement files) synced to what is actually installed — fast, safe, and low-effort.

> Built for the "I just want my requirements file updated" workflow.

[![PyPI Version](https://img.shields.io/pypi/v/reqsync.svg)](https://pypi.org/project/reqsync/)
[![Python Versions](https://img.shields.io/pypi/pyversions/reqsync.svg)](https://pypi.org/project/reqsync/)
[![CI Status](https://github.com/ImYourBoyRoy/reqsync/actions/workflows/ci.yml/badge.svg)](https://github.com/ImYourBoyRoy/reqsync/actions/workflows/ci.yml)
[![License](https://img.shields.io/pypi/l/reqsync.svg)](https://opensource.org/licenses/MIT)

---

## What reqsync is

`reqsync` reads your active environment and rewrites requirement specifiers so files reflect what you're currently running.

- Preserves comments, extras, markers, and line endings.
- Follows `-r` includes.
- Skips `-c` constraints unless you opt in.
- Uses backups + atomic writes.

### What reqsync is not

- Not a lockfile manager.
- Not a dependency solver replacement.
- Not a hash-regenerator for `--hash` pinned lines.

---

## Install

```bash
pip install reqsync
```

Optional extras:

```bash
pip install "reqsync[mcp]"      # built-in MCP server support
pip install "reqsync[pretty]"   # optional pretty ecosystem deps
```

---

## Quick start

```bash
# 1) Preview only (no writes)
reqsync run --no-upgrade --dry-run --show-diff

# 2) Apply updates
reqsync run --show-diff

# 3) CI drift gate (fails if changes needed)
reqsync run --check --no-upgrade
```

### Before / after example

```txt
# before
requests>=2.30.0
pydantic>=2.5.0

# after (installed env has requests 2.32.3, pydantic 2.7.0)
requests>=2.32.3
pydantic>=2.7.0
```

---

## Terminal demos

### Quick sync preview (`--dry-run --show-diff`)

<p>
  <img src="docs/assets/reqsync-quick-sync.svg" alt="Quick sync preview demo" width="100%">
</p>

### CI check mode (`--check --no-upgrade`)

<p>
  <img src="docs/assets/reqsync-check-mode.svg" alt="Check mode demo" width="100%">
</p>

---

## Integration Guide

### Standalone usage

```bash
reqsync run --path requirements.txt
reqsync run --path requirements/base.txt --follow-includes
```

### Agentic / MCP usage

```bash
# MCP server (stdio)
reqsync mcp

# or dedicated entrypoint
reqsync-mcp
```

### Python API (tool-friendly)

```python
from reqsync.api import run_sync_payload

result = run_sync_payload(
    {
        "path": "requirements.txt",
        "dry_run": True,
        "no_upgrade": True,
        "show_diff": True,
        "policy": "lower-bound",
    }
)
print(result["changed"])
print(result["changes"])
```

---

## Core commands

```bash
reqsync run [OPTIONS]
reqsync help [all|run|version|mcp]
reqsync --version
reqsync version
reqsync mcp [--transport stdio|sse|streamable-http]
```

Most-used options:

- `--path`
- `--no-upgrade`
- `--dry-run`
- `--check`
- `--show-diff`
- `--output human|json|both`
- `--json-report <file>`
- `--backup-keep-last <n>` (default `5`)
- `--policy lower-bound|floor-only|floor-and-cap|update-in-place`

Help discoverability:

```bash
reqsync help all
reqsync run --help
reqsync mcp --help
```

---

## Common workflows

```bash
# quick local refresh
reqsync run --show-diff

# no network / no pip upgrade
reqsync run --no-upgrade --dry-run --show-diff

# machine output for tools/models
reqsync run --no-upgrade --dry-run --output json

# update constraints too
reqsync run --path requirements/base.txt --update-constraints
```

---

## Output shape (for models/tools)

`--output json` or Python API returns structured keys:

- `changed`
- `files` (with `role`, `changed`, `change_count`)
- `changes` (`file`, `package`, `installed_version`, `old_line`, `new_line`)
- `backup_paths`
- `diff`

---

## Safety model

- Blocks outside virtualenv unless `--system-ok`.
- Blocks hash-pinned files unless `--allow-hashes`.
- Optional dirty-repo guard via `--allow-dirty`.
- Lock + backup + atomic write for safer file operations.
- Timestamped backups are auto-pruned (keep latest 5 per file by default).

---

## Docs

- [Usage](docs/USAGE.md)
- [Configuration](docs/CONFIG.md)
- [Integration](docs/INTEGRATION.md)
- [Changelog](CHANGELOG.md)

---

## Author & Links

**Created by**: Roy Dawson IV  
**GitHub**: <https://github.com/imyourboyroy>  
**PyPi**: <https://pypi.org/user/ImYourBoyRoy/>

Project repo: <https://github.com/ImYourBoyRoy/reqsync>

---

## License

MIT — see [LICENSE](LICENSE).
