django-upgrade-report 0.2.0__tar.gz

django_upgrade_report-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.coverage

django_upgrade_report-0.2.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-27
+
+First release on PyPI.
+
+### Added
+
+- `--target auto`, the new default: the newest LTS above your Django, or the newest release when no LTS is above it.
+- `--from` sets the Django version you run when your requirements only give a range.
+- The project's Python is read from `.python-version`, `uv.lock`, `pyproject.toml` or `Pipfile.lock`. The report warns when the target Django needs a newer Python.
+- Packages from git, local paths, URLs or a private index are listed as "Not from PyPI, not checked" and their names are never sent to PyPI. `--check-private-on-pypi` looks them up anyway, for an index that mirrors PyPI. A project-wide index counts too: `--index-url` or `--no-index` in requirement files, `[tool.uv]` and PDM index settings, and the pip and uv index environment variables.
+- Warnings when the target skips an LTS, when your Django requirement excludes the target, and when Django is not pinned.
+- Notes when a release needs a newer patch of your current Django, or a newer version of another package you pin. Upgrades that depend on one going with Django go with Django, too.
+- Packages marked `Development Status :: 7 - Inactive` are flagged. Packages built only on Wagtail or django CMS are included, with a note.
+- `schema_version` and documented fields in the JSON report.
+- Action inputs `from` and `check-private-on-pypi`, and outputs `blocked`, `upgrade`, `check` and `ready`. The action caches PyPI responses and runs on Windows runners.
+- A release workflow that publishes to PyPI with trusted publishing and moves the `v0` tag, so `uvx django-upgrade-report` and `uses: derblub/django-upgrade-report@v0` work.
+- Exit status 2 for every error, so it cannot be mistaken for `--fail-on`'s status 1.
+
+### Changed
+
+- The default target was `lts`, which gave a downgrade report for projects on Django 6.0 or 6.1. `lts` now shows a health check of your version when your Django is newer.
+- An upper bound such as `Django<6.0` only counts as support when the release came out after the target. For a target that is not released yet, only classifiers count.
+- Unknown targets (`5.3`, `52`) and targets below your Django are an error instead of an empty report.
+- Unpinned requirements are judged by the newest release they allow, not the newest release overall.
+- Environment markers are evaluated for your project's Python on Linux, not for the machine running the tool, and all Django requirement lines that apply are combined.
+
+### Fixed
+
+- Exact pins such as `Django==5.2.17` were read as excluding the version they pin.
+- A package was "Blocked" when only its newest release excluded the target, even though yours or an older one allowed it. It is now "Check manually".
+- Only the newest 40 releases were searched, so the suggested release was often not the smallest one.
+- Major-only classifiers such as `Framework :: Django :: 5` were ignored.
+- uv's forked resolutions, and duplicate entries in `poetry.lock` and `pdm.lock`, used the last entry instead of the one for your Python.
+- Pins from `-c` constraint files and `-r` includes were overwritten by later unpinned lines, and constraint-only packages were reported as dependencies. Later `pyproject.toml` tables overwrote earlier pins, and Poetry dependencies with several constraints were dropped.
+- Requirement files with a UTF-8 BOM lost their first line, and UTF-16 files crashed. Lockfiles and TOML are read as UTF-8 whatever the locale.
+- An empty lockfile gave an all-clear report instead of an error.
+- `--python` reported a shadowed copy of a package installed twice, and failed on Python 3.7 and older environments.
+- Tracebacks for unreadable files, `--python` failures, a bad `--index-url` (which printed its credentials) or `-o` into a missing directory. Missing directories are now created.
+- Reports are written as UTF-8, so `-o` and redirected output no longer crash on Windows.
+- Timeouts, connection resets, HTTP 429 and truncated answers from the index are retried.
+- Ready packages hid their notes, such as "version not pinned", in text and Markdown output.
+- An installed version missing from the index was shown as ready, without a note.
+- The Markdown report left out packages not on the index, and `*` in version specifiers turned into emphasis.
+- The progress counter never reached its total.
+- The action failed on Windows runners, and a second use in one job overwrote the first JSON report.
+- The action and CI used Node 20 actions, which GitHub runners no longer run.
+- `--fail-on` passed when every Django-related package came from another index, as soon as one unrelated package came from PyPI.
+
+## [0.1.0]
+
+Preview, not published on PyPI.
+
+### Added
+
+- Reads dependencies from `uv.lock`, `poetry.lock`, `pdm.lock`, `Pipfile.lock`, `requirements*.txt`, `requirements/*.txt`, `pyproject.toml` (PEP 621, dependency groups and Poetry) or an installed environment (`--python`).
+- Sorts every Django-related package into blocked, upgrade first, upgrade together with Django, check manually and ready, and names the smallest release that declares support for the target.
+- Targets: `lts` (default), `latest` or an explicit version such as `5.2`.
+- Text, Markdown, JSON and self-contained HTML output.
+- `--fail-on blocked|upgrade|check` for CI.
+- GitHub Action that writes the report to the job summary.
+- 24 hour cache for PyPI responses.
+
+[Unreleased]: https://github.com/derblub/django-upgrade-report/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/derblub/django-upgrade-report/releases/tag/v0.2.0
+[0.1.0]: https://github.com/derblub/django-upgrade-report/commit/35e1e97

django_upgrade_report-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [daniel@pushingpixels.at](mailto:daniel@pushingpixels.at). All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

django_upgrade_report-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+Thanks for taking the time. Bug reports with a real `requirements.txt` or lockfile are the most useful contribution there is: most wrong verdicts come from packaging metadata nobody anticipated.
+
+## Reporting a wrong verdict
+
+Open an [issue](https://github.com/derblub/django-upgrade-report/issues/new/choose) with:
+
+- the command you ran and `django-upgrade-report --version`,
+- the package, the version you use and the target Django version,
+- what the tool said and what you expected, ideally with a link to the package's changelog or PyPI page.
+
+`--format json` output helps, since it includes the reason for every verdict.
+
+## Development setup
+
+You need [uv](https://docs.astral.sh/uv/).
+
+```console
+$ git clone https://github.com/derblub/django-upgrade-report
+$ cd django-upgrade-report
+$ uv run --group dev pytest
+$ uv run python -m django_upgrade_report path/to/a/project
+```
+
+Before you open a pull request:
+
+```console
+$ uv run --group dev pytest
+$ uvx ruff check .
+$ uvx ruff format .
+```
+
+The tests never touch the network. Please keep it that way. There are two package indexes in `tests/conftest.py`:
+
+- a small in-memory index for the rules: add the releases you need to it instead of calling PyPI,
+- real PyPI metadata recorded in `tests/fixtures/pypi/`, for the golden tests in `tests/test_analysis.py`. To add a package, add it to `CASES` in `tests/fixtures/record.py` and run `PYTHONPATH=src python3 tests/fixtures/record.py`. Re-recording changes the facts the golden tests assert, so check them against the new data.
+
+CI also measures coverage: `uv run --group dev pytest --cov=django_upgrade_report`.
+
+## Where things live
+
+| File | What it does |
+| --- | --- |
+| `src/django_upgrade_report/sources.py` | Reads lockfiles, requirement files, `pyproject.toml` and environments into `Dependency` objects, and finds the project's Python |
+| `src/django_upgrade_report/pypi.py` | Cached client for the PyPI JSON API, with retries |
+| `src/django_upgrade_report/analysis.py` | The target (`resolve_target()`), the verdict rules (`supports()`) and the per-package status and phase |
+| `src/django_upgrade_report/render/` | Text, Markdown, JSON and HTML output. `render/json.py` documents the JSON fields and `schema_version` |
+| `src/django_upgrade_report/cli.py` | Command line interface |
+| `action.yml` | The GitHub Action |
+
+A change to the verdict rules in `supports()` needs a test case in `tests/test_analysis.py` and an update to "How it decides" in the README.
+
+## Pull requests
+
+- One topic per pull request, with a test that fails without the change.
+- Describe the user-visible change in `CHANGELOG.md` under "Unreleased".
+- By contributing you agree that your contribution is licensed under the [MIT License](LICENSE).
+
+Everyone taking part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).

django_upgrade_report-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Kurdoghlian, Pushing Pixels (https://pushingpixels.at)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_upgrade_report-0.2.0/PKG-INFO

@@ -0,0 +1,351 @@
+Metadata-Version: 2.4
+Name: django-upgrade-report
+Version: 0.2.0
+Summary: Which of your dependencies block a Django upgrade, and in which order to upgrade them.
+Project-URL: Homepage, https://github.com/derblub/django-upgrade-report
+Project-URL: Documentation, https://github.com/derblub/django-upgrade-report#readme
+Project-URL: Repository, https://github.com/derblub/django-upgrade-report
+Project-URL: Changelog, https://github.com/derblub/django-upgrade-report/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/derblub/django-upgrade-report/issues
+Project-URL: Pushing Pixels, https://pushingpixels.at
+Project-URL: Django upgrade audit, https://pushingpixels.at/creates/django-upgrades
+Author-email: Daniel Kurdoghlian <daniel@pushingpixels.at>
+Maintainer-email: Daniel Kurdoghlian <daniel@pushingpixels.at>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ci,compatibility,dependencies,django,lockfile,lts,migration,requirements,upgrade
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+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 :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: packaging>=23
+Requires-Dist: tomli>=2; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<a href="https://pushingpixels.at">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/derblub/django-upgrade-report/main/docs/assets/logo-dark.svg">
+    <img src="https://raw.githubusercontent.com/derblub/django-upgrade-report/main/docs/assets/logo-light.svg" alt="Pushing Pixels" width="96">
+  </picture>
+</a>
+
+<h1>django-upgrade-report</h1>
+
+<p><strong>Which of your dependencies block a Django upgrade, and in which order to upgrade them.</strong></p>
+
+<p>
+  <a href="https://github.com/derblub/django-upgrade-report/actions/workflows/ci.yml"><img src="https://github.com/derblub/django-upgrade-report/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/derblub/django-upgrade-report/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-94%25-brightgreen" alt="Coverage 94%"></a>
+  <a href="https://pypi.org/project/django-upgrade-report/"><img src="https://img.shields.io/pypi/v/django-upgrade-report" alt="PyPI"></a>
+  <a href="https://pypi.org/project/django-upgrade-report/"><img src="https://img.shields.io/pypi/pyversions/django-upgrade-report" alt="Python versions"></a>
+  <a href="https://pypi.org/project/django-upgrade-report/"><img src="https://img.shields.io/pypi/frameworkversions/django/django-upgrade-report" alt="Django versions"></a>
+  <a href="https://github.com/derblub/django-upgrade-report/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
+  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
+</p>
+
+<p>
+  <a href="https://github.com/derblub/django-upgrade-report#quick-start">Quick start</a> ·
+  <a href="https://github.com/derblub/django-upgrade-report#what-the-statuses-mean">Statuses</a> ·
+  <a href="https://github.com/derblub/django-upgrade-report#usage">Usage</a> ·
+  <a href="https://github.com/derblub/django-upgrade-report#in-ci">CI</a> ·
+  <a href="https://github.com/derblub/django-upgrade-report#how-it-decides">How it decides</a> ·
+  <a href="https://github.com/derblub/django-upgrade-report#faq">FAQ</a> ·
+  <a href="https://github.com/derblub/django-upgrade-report/blob/main/CHANGELOG.md">Changelog</a>
+</p>
+
+</div>
+
+---
+
+Before you touch Django, you need to know whether the 20 to 200 packages your project depends on are ready for the new version, which of them you can upgrade today, and which have to move together with Django. Finding that out by hand means reading every changelog.
+
+**django-upgrade-report** reads your lockfile, asks PyPI what every Django-related package declares, and gives you the upgrade plan: blockers first, then the smallest safe step for each package, in the right order.
+
+```console
+uvx django-upgrade-report
+```
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/derblub/django-upgrade-report/main/docs/assets/report-dark.png">
+    <img src="https://raw.githubusercontent.com/derblub/django-upgrade-report/main/docs/assets/report-light.png" alt="HTML report for an upgrade from Django 4.2.7 to 5.2: 15 packages to upgrade before Django, 3 to check manually" width="820">
+  </picture>
+</p>
+
+## Highlights
+
+- **Knows the order.** Separates upgrades you can ship today, on your current Django, from the ones that have to land in the same change as the Django bump. It also tells you when a release first needs a newer patch of your Django, or a newer version of another package.
+- **Smallest step, not latest.** For every package it names the oldest release that declares support for the target, so each change stays small and reviewable.
+- **Reads what you already have.** `uv.lock`, `poetry.lock`, `pdm.lock`, `Pipfile.lock`, `requirements*.txt`, `pyproject.toml` or an installed environment, transitive dependencies included.
+- **Honest about uncertainty.** A missing classifier means "check manually", not "blocked". An upper bound written before the target was released is not taken as a promise. Packages without a release in two years, or marked inactive, are flagged.
+- **Knows your Python.** Finds your project's Python version, warns when the target Django needs a newer one, and evaluates environment markers for your project, not for the machine running the tool.
+- **Made for pipelines and for people.** Markdown for pull request summaries, versioned JSON for scripts, a self-contained HTML report to attach to a ticket, and `--fail-on` to break the build.
+- **Your code stays put.** Only names and versions of packages that come from PyPI are sent to PyPI. Git, path and private-index packages are listed, never looked up. No account, no configuration.
+
+## Quick start
+
+Run it in your project directory. You need Python 3.10 or newer, but not Django and not your project's virtualenv.
+
+```console
+uvx django-upgrade-report                      # with uv
+pipx run django-upgrade-report                 # with pipx
+pip install django-upgrade-report              # or install it
+```
+
+By default it picks the next sensible step for your project: the newest LTS above the Django you run, or the newest release when no LTS is above it. A project on Django 4.2 gets a report for 5.2, a project on 5.2 one for 6.1. Pick another target with `--target`:
+
+```console
+django-upgrade-report --target 6.1
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/derblub/django-upgrade-report/main/docs/assets/terminal.png" alt="Terminal output for an upgrade from Django 5.2.7 to 6.1: django-celery-beat is blocked, four packages can be upgraded first, four need a manual check, one is ready" width="820">
+</p>
+
+## What the statuses mean
+
+| Status | Meaning | What to do |
+| --- | --- | --- |
+| **Blocked** | Your release and every newer one exclude the target, for example with `Django<6.1`. | Wait for a release, find a fork or replace the package. |
+| **Upgrade first** | A newer release declares the target and still runs on your current Django. | Upgrade these one at a time, before you touch Django. |
+| **Upgrade together with Django** | The release that declares the target has dropped your current Django, or needs another package that has. | Bump it in the same change as Django. |
+| **Check manually** | Nothing excludes the target, but nothing declares it either. | Read the changelog or run your test suite. Usually a classifier nobody updated. |
+| **Ready** | The version you use already declares support. | Nothing. |
+
+The notes on a row tell you more, for example "update Django 4.2 first" when a release needs a newer patch of your current Django, "upgrade django-crispy-forms first" when it needs a newer version of another package you pin, or "newer releases exclude Django 6.1".
+
+## Usage
+
+```console
+django-upgrade-report [PROJECT] [options]
+```
+
+| Option | Description |
+| --- | --- |
+| `PROJECT` | Project directory, or a single lockfile, requirements file or `pyproject.toml`. Defaults to the current directory. |
+| `-t`, `--target` | `auto` (default), `lts` (the newest x.2 release), `latest`, or a version such as `5.2`. See [Choosing the target](#choosing-the-target). |
+| `--from VERSION` | The Django version you run today, e.g. `4.2` or `4.2.16`, when your requirements only give a range. `4.2` means the newest 4.2 release. |
+| `--python PATH` | Read the exact installed versions from this interpreter, e.g. `.venv/bin/python`. |
+| `-f`, `--format` | `text` (default), `markdown`, `json` or `html`. |
+| `-o`, `--output` | Write the report to a file instead of stdout. Missing directories are created. |
+| `--fail-on` | Exit with status 1 when a package is `blocked`, needs an `upgrade` (or is blocked), or needs a `check` (or anything worse). |
+| `-v`, `--verbose` | Text output only: list every ready package with its reason. The other formats always do. |
+| `--index-url` | Base URL of an index that implements PyPI's JSON API. Default: `https://pypi.org/pypi`. |
+| `--check-private-on-pypi` | Look up packages your project installs from another index on PyPI, too. For an index that mirrors PyPI (Artifactory, Nexus, devpi). Their names are sent to PyPI. |
+| `--no-cache` | Do not cache PyPI responses. |
+| `--version` | Show the version and exit. |
+
+Responses are cached in `~/.cache/django-upgrade-report` (or `$XDG_CACHE_HOME/django-upgrade-report`): a project's release list for 24 hours, the metadata of a single release for good, since it never changes.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The report was written, and no package matched `--fail-on`. |
+| `1` | A package matched `--fail-on`. |
+| `2` | An error: no dependencies found, an unreadable file, an unknown target, the index could not be reached. Also with `--fail-on` when no dependency could be checked because they all come from another index. |
+
+So CI can tell "packages need attention" from "the tool could not run".
+
+### Choosing the target
+
+| `--target` | Checks against |
+| --- | --- |
+| `auto` | The newest LTS above your Django, or the newest release when no LTS is above it. When you already run the newest release, a health check of it. When your Django version is unknown, the newest LTS. |
+| `lts` | The newest x.2 release. When your Django is newer, a health check of your version instead. |
+| `latest` | The newest release. |
+| `5.2`, `6.1`, ... | That feature version. The next, unreleased one (6.2 today) is accepted for planning, see [How it decides](#how-it-decides). Unknown versions and versions below yours are an error. |
+
+The report warns when the target skips an LTS (upgrading one LTS at a time is easier), when your own Django requirement excludes the target, and when the target needs a newer Python than your project uses.
+
+### Where versions come from
+
+The most precise source wins:
+
+| Priority | Source | Versions | Transitive dependencies |
+| --- | --- | --- | --- |
+| 1 | `--python PATH` | exact, as installed | yes |
+| 2 | `uv.lock`, `poetry.lock`, `pdm.lock`, `Pipfile.lock` | exact | yes |
+| 3 | `requirements*.txt`, `requirements/*.txt`, `pyproject.toml` | exact when pinned with `==` | no |
+
+Requirement files follow `-r` includes and `-c` constraint files; constraints only pin packages that are listed elsewhere. `pyproject.toml` is read as PEP 621, dependency groups and Poetry. When a lockfile holds several versions of one package for different Pythons, as uv's forked resolutions do, the one for your project's Python is used.
+
+Unpinned requirements are judged by the newest release they allow and marked as such. Use a lockfile for exact results. When Django itself is only given as a range with an upper bound, such as `Django>=4.2,<5.0`, the newest release it allows is assumed and a warning says so. Without an upper bound the report cannot tell what can be upgraded first. In both cases, `--from` sets the version you run.
+
+### Which Python
+
+Environment markers such as `python_version < "3.12"` decide which requirements apply, so the tool needs your project's Python. It takes the first of:
+
+1. the interpreter passed with `--python`,
+2. `.python-version`,
+3. `requires-python` in `uv.lock`,
+4. `requires-python` in `pyproject.toml`,
+5. the `python` dependency in Poetry's `pyproject.toml`,
+6. `python_version` in `Pipfile.lock`.
+
+A range counts as its lower bound. The report shows the Python it found and warns when the target Django needs a newer one, for example `Django 6.1 needs Python >=3.12, your project uses 3.11 (from .python-version)`.
+
+Markers are evaluated for CPython on Linux, where Django apps are deployed, never for the machine running the tool. Against the target, a package is judged on the newer of your project's Python and the oldest Python the target Django supports. Against your current Django, on your project's Python, or the oldest Python your current Django supports when none was found.
+
+### Packages not from PyPI
+
+Packages from git, a local path, a URL or a private index are listed as "Not from PyPI, not checked", with where they come from, and their names are never sent to PyPI. This covers `git+https://...`, `-e` and local path lines in requirement files, `name @ url` requirements, git, path and URL sources in lockfiles, `--index-url` and `--no-index` in requirement files, a private default index or `no-index` in uv, Poetry, PDM or Pipenv, and the `PIP_INDEX_URL`, `UV_INDEX_URL`, `UV_DEFAULT_INDEX`, `PIP_NO_INDEX` and `UV_NO_INDEX` environment variables (lockfiles keep the index they record). Credentials in those URLs are removed before anything is shown.
+
+To check packages from a private index, point `--index-url` at its PyPI JSON API. If the index only mirrors PyPI, pass `--check-private-on-pypi` instead. Packages the index does not know at all are listed as "Not on the package index".
+
+## In CI
+
+### GitHub Actions
+
+The action writes the Markdown report to the job summary, exposes the counts as outputs, and can fail the job:
+
+```yaml
+- uses: actions/checkout@v7
+- uses: derblub/django-upgrade-report@v0
+  id: django
+  with:
+    fail-on: blocked   # optional: blocked, upgrade or check
+- run: echo "${{ steps.django.outputs.blocked }} blocked, ${{ steps.django.outputs.upgrade }} to upgrade"
+```
+
+| Input | Default | Description |
+| --- | --- | --- |
+| `path` | `.` | Project directory with a lockfile, `requirements*.txt` or `pyproject.toml`. |
+| `target` | `auto` | `auto`, `lts`, `latest` or a version such as `6.1`. |
+| `from` | | The Django version you run today, when your requirements only give a range. Empty reads it from the project. |
+| `fail-on` | | `blocked`, `upgrade` or `check`. Empty never fails the step because of a package. |
+| `check-private-on-pypi` | `false` | `true` looks up packages from another index on PyPI, too. |
+
+| Output | Description |
+| --- | --- |
+| `report` | Path to the JSON report, unique per use of the action. |
+| `blocked`, `upgrade`, `check`, `ready` | Number of packages with that status. |
+
+The action brings its own Python, runs on Linux and Windows runners, and caches PyPI responses between runs. The summary and the outputs are written before `fail-on` fails the step.
+
+### GitLab CI
+
+```yaml
+django-upgrade-report:
+  image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+  script:
+    - uvx django-upgrade-report --format html --output upgrade-report.html
+    - uvx django-upgrade-report --fail-on blocked
+  artifacts:
+    when: always
+    paths: [upgrade-report.html]
+```
+
+### Anywhere else
+
+```console
+django-upgrade-report --format markdown >> "$GITHUB_STEP_SUMMARY"
+django-upgrade-report --format json --output upgrade-report.json
+```
+
+The JSON report carries a `schema_version`: adding a field keeps it, renaming, removing or retyping one bumps it. The fields are documented in [`render/json.py`](https://github.com/derblub/django-upgrade-report/blob/main/src/django_upgrade_report/render/json.py).
+
+## How it decides
+
+For every release the tool looks at two pieces of metadata that maintainers publish on PyPI: the `Framework :: Django :: X.Y` classifiers and the `Django` requirement. For a target version, in this order:
+
+1. A requirement that excludes every release of the target means **no**. Each patch release counts, so `Django==5.2.17` or `Django>=5.2.3,<5.2.8` allow 5.2. Requirements that only apply to an optional extra are ignored. Lines with environment markers count when they apply to your Python ([see above](#which-python)), and all lines that apply are combined.
+2. A `Framework :: Django :: 5.2` classifier means **yes**.
+3. An upper bound that allows the target, such as `Django>=4.2,<6.0` or an exact pin, means **yes**, but only when the release was uploaded on or after the day the target came out. A bound written before that is a guess, not a promise: Wagtail 6.3 allows `Django<6.0` but came out before Django 5.2, and only Wagtail 6.3.4 added 5.2 support.
+4. Everything else means **not declared**: classifiers that stop at an older version or start at a newer one, a major-only classifier such as `Framework :: Django :: 5`, a lower bound without an upper one, or no information at all. That is a question, not a blocker: classifiers often lag behind releases.
+
+For a target that is not released yet, such as 6.2 today, only classifiers count, and the report says so. An upper bound like `<7.0` says nothing about a version nobody could test.
+
+From these verdicts, per package:
+
+- **Ready** when the version you use says yes.
+- **Upgrade** when a newer release says yes. The report names the oldest one. It goes **first** when that release still runs on your current Django. A release that needs `Django>=4.2.16` while you run 4.2.7 still goes first, with a note to update Django 4.2 first. It goes **together with Django** when the release excludes your whole Django series, declares only newer Django versions, or needs a newer version of another package you pin that has itself dropped your Django.
+- **Check manually** when no release says yes, but yours or a newer one is not excluded.
+- **Blocked** when your release and every newer one exclude the target.
+
+A package counts as Django-related when it depends on Django or has a `Framework :: Django` classifier. Packages that only depend on Wagtail or django CMS are included too, with a note to check them against that framework. Everything else is skipped.
+
+> [!NOTE]
+> The report shows what maintainers declare, not whether your tests pass. Use it to plan the upgrade, then run [django-upgrade](https://github.com/adamchainz/django-upgrade) on your code and your test suite with `python -W error::DeprecationWarning`.
+
+## FAQ
+
+<details>
+<summary><strong>Does it send my code anywhere?</strong></summary>
+
+No. It reads your lockfile or requirement files locally and sends only names and versions of packages that come from PyPI to the package index, PyPI by default. Packages from git, local paths or a private index are never looked up unless you ask for it. It does not import your project and does not need Django installed.
+</details>
+
+<details>
+<summary><strong>Why are so many packages "check manually"?</strong></summary>
+
+Many maintainers forget to add the classifier for a new Django version, or only add it with the next release. The tool refuses to guess. Packages that are really incompatible almost always say so with an upper bound, and those show up as blocked.
+</details>
+
+<details>
+<summary><strong>What about private packages?</strong></summary>
+
+Packages your project installs from git, a path or a private index are listed as "Not from PyPI, not checked" and otherwise ignored. If your private index implements PyPI's JSON API, point `--index-url` at it. If it mirrors PyPI, pass `--check-private-on-pypi`. See [Packages not from PyPI](#packages-not-from-pypi).
+</details>
+
+<details>
+<summary><strong>How is this different from Dependabot or Renovate?</strong></summary>
+
+They bump versions one package at a time. They do not know which release is the first one to support the Django version you are heading for, or which upgrades have to wait for Django. Use this tool to plan, and let them open the pull requests.
+</details>
+
+<details>
+<summary><strong>How is this different from django-upgrade?</strong></summary>
+
+[django-upgrade](https://github.com/adamchainz/django-upgrade) rewrites *your* code for a new Django version. django-upgrade-report looks at your *dependencies*. You want both.
+</details>
+
+## Related projects
+
+| Project | What it does |
+| --- | --- |
+| [django-upgrade](https://github.com/adamchainz/django-upgrade) | Rewrites your code for new Django versions. |
+| [Django Packages readiness](https://djangopackages.org/readiness/) | Shows compatibility per package on the web. |
+| [Django's upgrade guide](https://docs.djangoproject.com/en/stable/howto/upgrade-version/) | The official checklist for an upgrade. |
+
+## Contributing
+
+Bug reports with a real lockfile are the most useful contribution. See [CONTRIBUTING.md](https://github.com/derblub/django-upgrade-report/blob/main/CONTRIBUTING.md) for the development setup, and the [Code of Conduct](https://github.com/derblub/django-upgrade-report/blob/main/CODE_OF_CONDUCT.md). Security issues go through [SECURITY.md](https://github.com/derblub/django-upgrade-report/blob/main/SECURITY.md).
+
+## License
+
+[MIT](https://github.com/derblub/django-upgrade-report/blob/main/LICENSE) © Daniel Kurdoghlian, Pushing Pixels
+
+---
+
+<div align="center">
+  <a href="https://pushingpixels.at">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/derblub/django-upgrade-report/main/docs/assets/pushing-pixels-dark.svg">
+      <img src="https://raw.githubusercontent.com/derblub/django-upgrade-report/main/docs/assets/pushing-pixels-light.svg" alt="Pushing Pixels" width="320">
+    </picture>
+  </a>
+  <p>Built and maintained by <a href="https://pushingpixels.at">Daniel Kurdoghlian</a> at <a href="https://pushingpixels.at">Pushing Pixels</a> in Vienna.<br>
+  Planning a larger upgrade? I do <a href="https://pushingpixels.at/creates/django-upgrades">fixed-price Django upgrade audits</a>.</p>
+</div>