Basic Usage¶

This document covers the fundamental usage patterns for Zaojun, from simple checks to more advanced scenarios including caching for improved performance.

Command Structure¶

The basic Zaojun command follows this pattern:

zaojun [PYPROJECT_TOML] [OPTIONS]

Where: - [PYPROJECT_TOML]: Optional path to a pyproject.toml file (defaults to ./pyproject.toml) - [OPTIONS]: Various command-line options to control behavior

Default Behavior¶

When run without any arguments, Zaojun:

Looks for pyproject.toml in the current directory
Checks all dependencies in the [project.dependencies] section
Shows detailed output with emoji indicators
Returns exit code 1 if any updates are needed

# Basic usage - check current directory
zaojun

Specifying a pyproject.toml File¶

You can check dependencies in any pyproject.toml file:

# Check a specific file
zaojun /path/to/project/pyproject.toml

# Check a file in a parent directory
zaojun ../pyproject.toml

# Check a file with a different name
zaojun my-dependencies.toml

Caching for Performance¶

Zaojun includes a caching system to improve performance for repeated dependency checks. By default, caching is disabled to maintain backward compatibility.

Enabling Caching¶

# Enable caching for faster repeated checks
zaojun --cache

# Enable caching and show statistics
zaojun --cache --cache-stats

# Clear existing cache and enable caching
zaojun --clear-cache --cache

Cache Benefits¶

First run with --cache: Fetches data from PyPI and caches it
Subsequent runs: Uses cached data (10-100x faster)
Offline capability: Partial functionality when PyPI is unavailable
Rate limiting: Reduces load on PyPI infrastructure

Cache Management¶

# Show cache statistics
zaojun --cache-stats

# Clear all cache entries
zaojun --clear-cache

# Disable caching (default behavior)
zaojun --no-cache

Cache Location¶

Cache files are stored in: - Linux/Unix: ~/.cache/zaojun/pypi_cache/ - macOS: ~/Library/Caches/zaojun/pypi_cache/ - Windows: %LOCALAPPDATA%\zaojun\pypi_cache\

Cache entries expire after 24 hours and are automatically cleaned up.

Understanding Version Constraints¶

Zaojun understands various Python version constraint formats:

Exact Versions¶

dependencies = [
    "package==1.2.3",      # Exactly version 1.2.3
]

Version Ranges¶

dependencies = [
    "package>=1.0.0",      # Version 1.0.0 or higher
    "package<2.0.0",       # Version less than 2.0.0
    "package>=1.0.0,<2.0.0", # Between 1.0.0 and 2.0.0
]

Compatible Releases¶

dependencies = [
    "package~=1.2.3",      # >=1.2.3, ==1.2.*
    "package~=1.2",        # >=1.2, ==1.*
]

Multiple Constraints¶

dependencies = [
    "package>=1.0.0,!=1.2.3,<2.0.0",  # Multiple conditions
]

Output Interpretation¶

Status Indicators¶

Zaojun uses three types of indicators:

✅ Up to date
```
✅️ package==1.2.3 is up to date
```
The latest version on PyPI matches your constraint.
⚠️ Compatible update available
```
⚠️ package: ~=1.2.3 → Latest: 1.2.5
```
A newer version exists that satisfies your version constraints.
❌ Incompatible update available
```
❌ package: ==1.2.3 → Latest: 2.0.0
```
A newer version exists that does NOT satisfy your version constraints.

Example Scenarios¶

Scenario 1: Everything up to date

$ zaojun
Checking dependencies in /home/user/project/pyproject.toml
✅️ httpx~=0.28.1 is up to date
✅️ packaging~=26.0 is up to date
✅️ cyclopts>=2.0.0 is up to date

Scenario 2: Mixed status

$ zaojun
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

Common Patterns¶

Regular Project Maintenance¶

# Check your project regularly with caching for speed
zaojun --cache

# If updates are needed, update your constraints
# Then update your dependencies
uv sync -U --all-groups

# Clear cache periodically for fresh data
zaojun --clear-cache --cache

Development Workflow with Caching¶

# Daily development checks (fast with caching)
zaojun --cache --cache-stats --groups

# Before committing code
zaojun --short --cache

# Force fresh data when needed
zaojun --clear-cache --cache-stats

Checking Before Commits¶

# Run before committing to ensure dependencies are current
zaojun --short --cache

# If you see output, consider updating

Integration with Other Tools¶

# Combine with grep to extract package names needing updates
zaojun --short --cache | grep -E "^[⚠❌]" | cut -d' ' -f2

# Count how many packages need updates
zaojun --short --cache | grep -c -E "^[⚠❌]"

# Check cache effectiveness
zaojun --cache --cache-stats | grep "Hits:"

Working with Different File Structures¶

Monorepo Structure¶

# Check each project in a monorepo
zaojun packages/app/pyproject.toml
zaojun packages/lib/pyproject.toml
zaojun tools/scripts/pyproject.toml

Nested Projects¶

# Check a nested project
zaojun src/backend/pyproject.toml

# Check multiple levels
zaojun ../../shared-lib/pyproject.toml

Temporary Files¶

# Check a generated pyproject.toml
zaojun /tmp/test-deps.toml --cache

# Check from stdin (advanced usage)
cat deps.toml | python -c "
import sys, tempfile, subprocess
with tempfile.NamedTemporaryFile(mode='w', suffix='.toml') as f:
    f.write(sys.stdin.read())
    f.flush()
    subprocess.run(['zaojun', f.name, '--cache'])
"

Error Handling¶

File Not Found¶

$ zaojun non-existent.toml
Error: File 'non-existent.toml' not found

Invalid TOML¶

$ zaojun invalid.toml
Error: Invalid TOML in 'invalid.toml'

Network Issues¶

$ zaojun
Checking dependencies in /home/user/project/pyproject.toml
❌ Network error for httpx: HTTPStatusError('404 Not Found')

Invalid Dependency Format¶

$ zaojun
Checking dependencies in /home/user/project/pyproject.toml
❌ Error checking 'invalid-package-@-1.0': ValueError("Invalid dependency format 'invalid-package-@-1.0'")

Best Practices¶

Run Regularly: Check dependencies at least weekly
Use Caching: Enable --cache for faster repeated checks during development
Use in CI: Add to your continuous integration pipeline (consider --no-cache for consistency)
Review Before Updating: Understand what changes in new versions
Test After Updates: Always test your application after dependency updates
Use Version Pinning: Consider pinning exact versions in production
Monitor Cache: Use --cache-stats periodically to ensure cache effectiveness
Clear Cache: Use --clear-cache when you suspect stale data or after major dependency changes

Next Steps¶

Learn about Command Reference for all available options
See Examples for real-world use cases