feat: expose the parsed migration view - #48
Merged
mergify[bot] merged 1 commit intoAug 11, 2026
Conversation
Tooling built around the chain currently has to re-implement parsing and ordering, or reach into private helpers, to answer questions the library already answers internally: which migrations are dynamic, what order git puts them in, and what the generated artifact is called. Export the pieces that answer those questions without building a chain: MigrationFile, parse_versions_dir() and CHAIN_FILENAME (promoted from _CHAIN_FILENAME, whose only two references were internal). parse_versions_dir() returns raw git add order, which is deliberately not the order the built chain walks, since a hybrid is re-parented to sit after the revision it hardcodes. It also does not fall back to a chain file the way build_chain does: that file records only the mapping, not classification or ordering, so there would be nothing to reconstruct from. Both are documented, along with git_sequence being a position within one parse rather than a property of the file.
Contributor
Merge Protections🟢 All 6 merge protections satisfied — ready to merge. Show 6 satisfied protections🟢 🤖 Continuous Integration
🟢 👀 Review Requirements
🟢 Enforce conventional commitMake sure that we follow https://www.conventionalcommits.org/en/v1.0.0/
🟢 🔎 Reviews
🟢 📕 PR description
🟢 🚦 Auto-queueWhen all merge protections are satisfied, this pull request will be queued automatically. |
There was a problem hiding this comment.
Pull request overview
This PR exposes a “parsed migration view” as part of the public API, so external tooling can inspect migration classification and git add-order without building a revision chain.
Changes:
- Add
parse_versions_dir(versions_dir)returning orderedMigrationFileobjects (git add-order, not traversal order). - Export
MigrationFileand a publicCHAIN_FILENAMEconstant for consumers. - Add README API documentation and unit tests covering ordering, classification, and error behavior without git history.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
alembic_git_revisions/_chain.py |
Introduces parse_versions_dir, promotes CHAIN_FILENAME, and updates chain file usage to the public constant. |
alembic_git_revisions/__init__.py |
Re-exports parse_versions_dir, MigrationFile, and CHAIN_FILENAME from the package root. |
README.md |
Documents the new public API surface (parse_versions_dir, MigrationFile, CHAIN_FILENAME) and clarifies ordering semantics. |
tests/test_chain.py |
Adds tests validating classification, deterministic ordering (including uncommitted files), and erroring when git history is unavailable. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Contributor
Author
|
One open question, kept out of the description since that becomes the commit message on merge:
|
jd
approved these changes
Aug 11, 2026
Contributor
Merge Queue Status
This pull request spent 28 seconds in the queue, including 6 seconds running CI. Required conditions to merge
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Tooling built around this library has to re-implement parsing and ordering, or reach into private helpers, to answer questions the library already answers internally: which migrations are dynamic, what order git puts them in, and what the generated artifact is called.
This exports the pieces that answer those questions without building a chain:
parse_versions_dir(versions_dir)returns the migrations asMigrationFileobjects in git add order. A thin wrapper over the existing git-order and parse steps.MigrationFileis already a public class, it simply was not exported.CHAIN_FILENAMEso callers locating or cleaning up the generated file do not hardcode"revision_chain.json". The private_CHAIN_FILENAMEis removed rather than aliased: its only two references were internal to_chain.py, both updated here, and a leading-underscore name carries no compatibility guarantee.Concretely, this is what I needed to write the
--checkreporting in #47: it wants classification and git order, but not a chain. It is useful on its own for anything that inspects a versions directory, such as a CI lint or a migration linter.Notes for review
parse_versions_dirraisesRuntimeErrorwhen git history is unavailable, rather than returningNoneas the private helper does, because ordering cannot be recovered from the directory alone and a silent wrong order is worse than an error. Note this differs frombuild_chain, which first falls back to a chain file.__init__.py, the README API section and the end of the test file, so whichever lands second needs a trivial rebase.