Skip to content

Quick Start

This guide will help you get started with Zaojun quickly. You'll learn the basic commands and common usage patterns.

Basic Usage

Check Dependencies

The simplest way to use Zaojun is to run it in your project directory:

zaojun

This will check all dependencies in your pyproject.toml file against the latest versions on PyPI.

Example Output

Checking dependencies in /home/user/project/pyproject.toml
✅️ httpx~=0.28.1 is up to date
⚠️ packaging: ~=23.0 → Latest: 24.0
❌ typer: ~=0.9.0 → Latest: 1.0.0

Understanding the Output

  • ✅ Green checkmark: The dependency is up to date
  • ⚠️ Yellow warning: A newer compatible version is available
  • ❌ Red cross: A newer incompatible version is available

Common Commands

Check Dependency Groups

If your project uses dependency groups (like dev, test, docs), check them all:

zaojun --groups

Example output: 

Checking dependencies in /home/user/project/pyproject.toml
✅️ httpx~=0.28.1 is up to date

Checking dependency group [dev]
✅️ ruff~=0.15.1 is up to date
⚠️ pytest: ~=7.0.0 → Latest: 8.0.0

Checking dependency group [test]
✅️ pytest-cov~=4.0.0 is up to date

Minimal Output

For CI/CD pipelines or scripts, use minimal output:

zaojun --short

This shows only dependencies that need updates: 

⚠️ packaging: ~=23.0 → Latest: 24.0
❌ typer: ~=0.9.0 → Latest: 1.0.0

Treat Compatible Updates as OK

If you want compatible updates to not cause an error exit code:

zaojun --compat-ok

With this flag: - Compatible updates (⚠️) won't cause exit code 1 - Only incompatible updates (❌) will cause exit code 1

Specify a Different pyproject.toml

Check dependencies in a different file:

zaojun /path/to/other/pyproject.toml

Or combine with other options:

zaojun /path/to/other/pyproject.toml --groups --short

Real-World Examples

Basic Project Check

# Navigate to your project
cd ~/projects/my-python-app

# Check dependencies
zaojun

CI/CD Pipeline Integration

GitHub Actions Example:

name: Check Dependencies
on: [push, pull_request]

jobs:
  check-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install zaojun
      - run: zaojun --short

Woodpecker CI Example:

when:
  event: [release, pull_request]

steps:
  check-deps:
    image: ghcr.io/astral-sh/uv:debian
    pull: true
    commands:
      - uv --version
      - uv sync --all-groups
      - uv run nox --version
      - uv run nox -s dependency_versions

Nox Integration Example:

Add Zaojun to your noxfile.py for automated dependency checking:

from nox import session

@session
def check_dependencies(session):
    """Check for outdated dependencies using Zaojun."""
    session.install("zaojun")
    session.run("zaojun", "--groups", "--compat-ok")

Then run it with: 

uv run nox -s check_dependencies

Pre-commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: https://codeberg.org/marvin8/zaojun
    rev: 1.0.0
    hooks:
      - id: zaojun
        args:
          - "--groups"
          - "--compat-ok"  # Don't fail on compatible updates

Docker Container

Create a Dockerfile for dependency checking:

FROM python:3.11-slim

RUN pip install zaojun

WORKDIR /app
COPY pyproject.toml .

CMD ["zaojun", "--groups"]

Exit Codes

Zaojun uses exit codes to indicate results:

  • 0: All dependencies are up to date (or only compatible updates with --compat-ok)
  • 1: Updates are needed (incompatible or compatible without --compat-ok)

This makes it easy to use in scripts:

#!/bin/bash

zaojun --short
if [ $? -eq 1 ]; then
    echo "Dependencies need updating!"
    # Add your update logic here
fi

Common Workflows

Daily Development Check

Add to your shell profile or use as an alias:

# Add to ~/.bashrc or ~/.zshrc
alias checkdeps='zaojun --groups --compat-ok'

Then run: 

checkdeps

Before Releases

Check all dependencies before a release:

zaojun --groups

If updates are needed, update your pyproject.toml and run: 

# Update dependencies using uv
uv sync -U --all-groups

# Or using pip
pip install -U -r requirements.txt

Monitoring Multiple Projects

Create a script to check multiple projects:

#!/bin/bash

PROJECTS=(
    "/path/to/project1"
    "/path/to/project2"
    "/path/to/project3"
)

for project in "${PROJECTS[@]}"; do
    echo "Checking $project"
    cd "$project" && zaojun --short
    echo ""
done

Using Zaojun with Nox for Development

When developing Python projects, you can integrate Zaojun into your Nox sessions for automated dependency checking:

# In your noxfile.py
from nox import session

@session
def dependency_check(session):
    """Check project dependencies for updates."""
    session.install("zaojun")
    # Check main dependencies
    session.run("zaojun", "--compat-ok")
    # Check all dependency groups including dev dependencies
    session.run("zaojun", "--groups", "--compat-ok")

@session
def ci_checks(session):
    """Run all CI checks including dependency validation."""
    session.install("zaojun", "pytest", "ruff")
    # Format and lint code
    session.run("ruff", "format", ".")
    session.run("ruff", "check", ".")
    # Check dependencies
    session.run("zaojun", "--short")
    # Run tests
    session.run("pytest", "tests/")

Run these sessions with: 

# Check dependencies only
uv run nox -s dependency_check

# Run all CI checks
uv run nox -s ci_checks

Woodpecker CI with Nox Integration

For a complete Woodpecker CI pipeline that includes Zaojun:

when:
  event: [push, pull_request]

steps:
  lint-and-test:
    image: ghcr.io/astral-sh/uv:debian
    pull: true
    commands:
      - uv --version
      - uv sync --all-groups
      # Run all nox sessions including dependency checking
      - uv run nox
      # Additional dependency check with short output
      - uv run zaojun --short

  dependency-audit:
    image: ghcr.io/astral-sh/uv:debian
    pull: true
    commands:
      - uv sync --all-groups
      # Weekly comprehensive dependency audit
      - uv run zaojun --groups
      - uv run nox -s pysentry

Tips and Best Practices

  1. Regular Checks: Run Zaojun regularly to stay updated
  2. CI Integration: Add to your CI pipeline to catch outdated dependencies
  3. Pre-commit: Use as a pre-commit hook to prevent committing with outdated deps
  4. --compat-ok in Development: Use during development to avoid breaking CI
  5. --short for Scripts: Use minimal output in automated scripts

Next Steps

Now that you know the basics: