Metadata-Version: 2.3
Name: zaojun
Version: 1.5.3
Summary: Checks project dependencies for newer versions.
Author: Marvin8
Author-email: Marvin8 <marvin8@tuta.io>
License: AGPL-3.0-or-later
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Dist: cyclopts~=4.15.0
Requires-Dist: httpx[http2,zstd]~=0.28.1
Requires-Dist: packaging~=26.2
Requires-Python: >=3.11, <3.15
Project-URL: Issues, https://codeberg.org/marvin8/zaojun/issues
Project-URL: Source, https://codeberg.org/marvin8/zaojun
Project-URL: Changelog, https://codeberg.org/marvin8/zaojun/src/branch/main/CHANGELOG.md
Description-Content-Type: text/markdown

# zaojun

[![Repo](https://img.shields.io/badge/repo-Codeberg.org-blue)](https://codeberg.org/marvin8/zaojun)
[![Docs](https://img.shields.io/badge/docs-Codeberg.page-blue)](https://marvin8.codeberg.page/zaojun/)
[![CI](https://ci.codeberg.org/api/badges/13971/status.svg)](https://ci.codeberg.org/repos/13971)
[![Downloads](https://img.shields.io/pepy/dt/zaojun)](https://pepy.tech/project/zaojun)

[![PySentry](https://img.shields.io/badge/PySentry-Checked-green)](https://pysentry.com)
[![CodeLimit](https://img.shields.io/badge/CodeLimit-checked-green.svg)](https://github.com/getcodelimit/codelimit)

[![Codestyle](https://img.shields.io/badge/Codestyle-Ruff-green)](https://docs.astral.sh/ruff/)
[![Version](https://img.shields.io/pypi/pyversions/zaojun)](https://pypi.org/project/zaojun/)
[![Wheel](https://img.shields.io/pypi/wheel/zaojun)](https://pypi.org/project/zaojun/)

[![AGPL](https://img.shields.io/pypi/l/zaojun)](https://codeberg.org/marvin8/zaojun/src/branch/main/LICENSE.md)

`zaojun` is a command-line (CLI) tool to check versions of your dependencies as defined in `pyproject.toml` against the latest versions published on [PyPI](https://pypi.org). Full documentation is available at [marvin8.codeberg.page/zaojun](https://marvin8.codeberg.page/zaojun/).

**New in v1.5.0**: CVE/vulnerability scanning — zaojun surfaces known security advisories from the PyPI vulnerability feed (zero extra HTTP requests; data comes from the same response already fetched per package). Packages with open advisories show 🔒 inline and a `Vulnerabilities` detail block at the end of the report. Use `vuln-ignore` in `[tool.zaojun]` to suppress specific CVEs, GHSAs, or entire packages by name or version range. Also: `--flag-major` (default on) — flags compatible major-version bumps with 💥 so they don't get lost among minor updates. `--major-ok` opts out of exit code 1 for major bumps, mirroring `--compat-ok`. Also: `--index-url URL` to point zaojun at Artifactory, devpi, or any PyPI JSON API-compatible index. Cache files are now leaner — the unused package metadata blob has been dropped, reducing per-entry disk use.

**New in v1.4.0**: JSON output via `--format json` — machine-readable dependency status for scripts and CI pipelines. Also: persistent defaults via `[tool.zaojun]` in `pyproject.toml` — set `cache`, `groups`, `min-age`, `library`, `format`, and more without repeating CLI flags. CLI flags always override config.

**New in v1.3.0**: Library mode via `--library` — checks that version constraints are consumer-friendly (no exact pins, no tight upper bounds) and only flags updates that fall outside the allowed range. Compatible updates are silent when the latest version already satisfies the spec.

**New in v1.2.0**: Supply-chain quarantine via `--min-age N` — ignore updates younger than N days, giving the ecosystem time to react to compromised releases. Updates that are too new show ⏳ and don't trigger exit code 1.

**New in v1.0.0**: PyPI API response caching for faster repeated checks! Enable with `--cache` for 10-100x performance improvements on subsequent runs.

## Install and run from [Source](https://codeberg.org/marvin8/zaojun)

Alternatively, you can run `zaojun` from source by cloning the repository:

```bash
git clone https://codeberg.org/marvin8/zaojun.git
```

`zaojun` uses [`uv`](https://docs.astral.sh/uv/) for dependency control; please install `uv` before proceeding.

Install all required Python modules:

```bash
uv sync
```

Run `zaojun` with:

```bash
uv run zaojun
```

Try the new caching feature for faster repeated checks:

```bash
uv run zaojun --cache --cache-stats
```

## As a [`pre-commit`](https://pre-commit.com) hook

Add the following snippet to your `.pre-commit-config.yaml`:

```yaml

- repo: https://codeberg.org/marvin8/zaojun
  rev: 1.2.0
  hooks:

- id: zaojun
      args:
        "--groups"
        "--cache"  # Enable caching for faster runs
```

## Significance of the name *zaojun*

Zao Jun is the Chinese god who acts as a household guardian, overseeing domestic harmony and reporting family conduct to the heavens—reinforcing moral behavior within the kin unit.
This tool tries to keep your project and its dependencies in harmony. It doesn’t report to any third parties, though :)

I know it’s a bit far-fetched, but I like it—so there!

If you’d like to learn more about Zao Jun, the Chinese Kitchen God:

- [Wikipedia](https://en.wikipedia.org/wiki/Kitchen_God)
- [Columbia University](https://afe.easia.columbia.edu/cosmos/prb/earthly.htm)



## Licensing

`zaojun` is licensed under the [GNU Affero General Public License v3.0](http://www.gnu.org/licenses/agpl-3.0.html).

## Supporting zaojun

You can support `zaojun` in several ways:

- Create an issue for problems or ideas you have.
- Create a pull request if you prefer a hands-on approach.
- [Buy me a coffee](https://www.buymeacoffee.com/marvin8).
- Send small change in Monero to the address below:

### Monero donation address

`88xtj3hqQEpXrb5KLCigRF1azxDh8r9XvYZPuXwaGaX5fWtgub1gQsn8sZCmEGhReZMww6RRaq5HZ48HjrNqmeccUHcwABg`


[uv]: https://docs.astral.sh/uv/
[pre-commit]: https://pre-commit.com
[PyPI]: https://pypi.org

[AGPL]: https://img.shields.io/pypi/l/zaojun "Licensed: AGPL 3.0 or later"
[Repo]: https://img.shields.io/badge/repo-Codeberg.org-blue "Repo at Codeberg.org"
[Docs]: https://img.shields.io/badge/docs-Codeberg.page-blue "Documentation"
[PySentry]: https://img.shields.io/badge/PySentry-Checked-green "Checked with PySentry"
[CI]: https://ci.codeberg.org/api/badges/13971/status.svg "CI / Woodpecker"
[CodeLimit]: https://img.shields.io/badge/CodeLimit-checked-green.svg
[Downloads]: https://img.shields.io/pepy/dt/zaojun "Pepy Total Downloads"
[Codestyle]: https://img.shields.io/badge/Codestyle-Ruff-green "Code formatted with ruff"
[Version]: https://img.shields.io/pypi/pyversions/zaojun "PyPI - Python Version"
[Wheel]: https://img.shields.io/pypi/wheel/zaojun "PyPI - Wheel"
