CLI Tool Reference¶
The deprecator CLI provides commands for initializing and inspecting deprecations in your projects.
Installation¶
Command Reference¶
deprecator¶
Deprecator CLI - Manage deprecation warnings in Python packages.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--version |
boolean | Show the version and exit. | False |
--help |
boolean | Show this message and exit. | False |
init¶
Initialize deprecator for the current project.
This creates a _deprecations.py file in your package with a basic setup and configures the necessary entry points in pyproject.toml.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
list-packages¶
List all packages that define deprecator or registry entrypoints.
This helps you discover which packages in your environment are using deprecator for managing their deprecations.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
show-package¶
Show all deprecators defined by a specific package.
This displays all deprecator instances that PACKAGE_NAME has defined through entry points, allowing you to see what deprecations a package contributes to various frameworks.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
show-registry¶
Show deprecations from the default registry.
If PACKAGE_NAME is provided, shows deprecations for that specific package. Otherwise, shows all deprecations from all packages in the default registry.
Examples: deprecator show-registry # Show all deprecations deprecator show-registry mypackage # Show deprecations for mypackage
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
validate-package¶
Validate all entrypoints defined by a specific package.
This checks that: - All deprecator entry points are correctly configured - All registry entry points are correctly configured - The referenced objects can be imported
Exit code 1 if validation fails, 0 if successful.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Usage Examples¶
Initialize Deprecator¶
Initialize deprecator in your current project:
This creates a _deprecations.py file in your package with a basic setup.
Show Registry Deprecations¶
Display deprecations from the default registry:
# Show all deprecations from all packages
deprecator show-registry
# Show deprecations for a specific package
deprecator show-registry mypackage
Example output:
Package | Message | Warn In | Gone In | Status
------------|--------------------------|---------|---------|--------
mypackage | old_api deprecated | 2.0.0 | 3.0.0 | Active
Show Package Deprecators¶
Display all deprecators defined by a specific package:
This shows all deprecator instances that a package has defined through entry points.
Validate Package¶
Check if a package's deprecation setup is valid:
This validates: - All deprecator entry points are correctly configured - All registry entry points are correctly configured - The referenced objects can be imported
List Packages¶
List all packages that have deprecator or registry entry points:
pytest Integration¶
The deprecator pytest plugin provides GitHub annotations and strict mode:
# Add annotations to GitHub PRs (recommended for CI)
pytest --deprecator-github-annotations
# Strict mode - treat deprecations as errors (use sparingly)
pytest --deprecator-error
Exit Codes¶
The CLI uses the following exit codes:
| Code | Meaning |
|---|---|
| 0 | Success, no issues found |
| 1 | Validation failures or expired deprecations found |
| 2 | Configuration or usage errors |
Common Issues¶
| Issue | Solution |
|---|---|
| "Package not found" | Make sure the package is installed in your environment |
| "No entry point configured" | Run deprecator init to set up your package |
| "Import error" | Check that your deprecator module is correctly structured |
Environment Variables¶
You can control deprecation warnings using standard Python environment variables:
# Show all warnings
PYTHONWARNINGS=always deprecator show-registry
# Treat warnings as errors
PYTHONWARNINGS=error::DeprecationWarning deprecator show-registry
For Framework Authors¶
If you're creating a framework that needs a registry, see the Registry Management documentation for details on creating and managing framework-specific registries.