Metadata-Version: 2.4
Name: pyupcheck
Version: 0.2.1
Summary: Check if upgrading a Python dependency will break your code
Author: AgbaDev
License-Expression: MIT
Project-URL: Homepage, https://github.com/AgbaDev/pyupcheck
Project-URL: Issues, https://github.com/AgbaDev/pyupcheck/issues
Keywords: cli,dependency,upgrade,migration,breaking-changes
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: rich>=13.0.0
Requires-Dist: click>=8.0.0
Dynamic: license-file

# pyupcheck

Check if upgrading a Python dependency will break your code.

```
$ pyupcheck check-all

Found 12 dependencies to check

flask 2.3.3 -> 3.1.3  OK (15 usages safe)
requests 2.28.0 -> 2.34.2  2 BREAKING
  x src/api.py:23  resp = requests.get(url, verify=False)
    Removed: `verify` parameter no longer accepted
django 4.2.0 -> 5.0.6  1 deprecated
  ! core/models.py:8  from django.utils import timezone
    Deprecated: use datetime.timezone instead

2 breaking | 1 deprecated across 12 packages
```

## Install

```bash
pip install pyupcheck
```

## Commands

### `check` - check one package

```bash
pyupcheck check flask 3.0.0        # against specific version
pyupcheck check flask              # against latest
```

### `check-all` - check every dependency

Reads `requirements.txt` and `pyproject.toml` (PEP 621 and Poetry), checks every dependency against its latest version.

```bash
pyupcheck check-all
pyupcheck check-all --format html -o report.html
```

### `outdated` - list stale dependencies

```bash
pyupcheck outdated
```

Flags major version bumps separately since they carry the most risk.

### `diff` - changelog diff between versions

See breaking/deprecated changes between any two versions without scanning code:

```bash
pyupcheck diff django 4.2.0 5.0.0
```

### `scan` - list your usages of a package

```bash
pyupcheck scan requests
```

### `versions` and `cache-clear`

```bash
pyupcheck versions flask
pyupcheck cache-clear
```

## Output formats

```bash
pyupcheck check flask -f json          # machine-readable
pyupcheck check flask -f md -o r.md   # markdown report
pyupcheck check flask -f html -o r.html # styled HTML report
```

## CI integration

Exit code is 1 when the `--fail-on` condition is met:

```bash
pyupcheck check-all --fail-on breaking     # default
pyupcheck check-all --fail-on deprecated   # stricter
pyupcheck check-all --fail-on any          # strictest
pyupcheck check-all --fail-on never        # report only
```

GitHub Actions example:

```yaml
- name: Check dependency upgrades
  run: |
    pip install pyupcheck
    pyupcheck check-all --fail-on breaking --quiet
```

Pre-commit hook (`.pre-commit-config.yaml`):

```yaml
- repo: local
  hooks:
    - id: pyupcheck
      name: pyupcheck
      entry: pyupcheck check-all --quiet
      language: system
      pass_filenames: false
```

## Configuration

`pyproject.toml`:

```toml
[tool.pyupcheck]
exclude = ["migrations", "legacy"]
ignore = ["internal-package"]
fail_on = "breaking"
min_severity = "deprecated"
cache = true
```

Or `.pyupcheckignore`:

```
migrations/          # trailing slash = directory
legacy/
internal-package     # no slash = package to skip
```

## Features

- AST-based scanning: imports, from-imports, aliases, attribute chains, calls
- Jupyter notebook (`.ipynb`) scanning, magics stripped automatically
- Changelog sources: GitHub releases, raw changelog files, PyPI descriptions
- 24h response cache (`--no-cache` to bypass, `cache-clear` to wipe)
- Severity filtering with `--min-severity`
- Quiet mode (`-q`) for hooks and scripts

## Limitations

- Changelog parsing relies on maintainers writing structured changelogs
- Dynamic attribute access (`getattr(pkg, name)`) is not detected
- GitHub API is rate limited to 60 req/hr unauthenticated; pass `--github-token` or set `GITHUB_TOKEN` for higher limits

## Contributing

Contributions are welcome. Here is how to get started:

```bash
git clone https://github.com/AgbaDev/pyupcheck.git
cd pyupcheck
pip install -e ".[dev]"
```

Things that would genuinely improve the tool:

- Better changelog parsing for packages that use unconventional formats (e.g. Sphinx-based changelogs, HISTORY files)
- Support for `setup.cfg` and `setup.py` dependency parsing
- Detection of dynamic attribute access patterns (`getattr`, `__import__`)
- `pip-tools` and `conda` lockfile support
- A `--watch` mode that monitors your lockfile for changes and alerts on risky upgrades
- Test coverage

To contribute, open an issue describing what you want to work on, then submit a pull request. Please include a short test or example showing the bug or feature.

If you find a package whose changelog pyupcheck fails to parse correctly, open an issue with the package name and version range. That is the most common and most impactful thing to fix.

## License

MIT
