Publish as mavsdk-grpc, hand the mavsdk name to the native binding#826
Open
julianoes wants to merge 5 commits into
Open
Publish as mavsdk-grpc, hand the mavsdk name to the native binding#826julianoes wants to merge 5 commits into
julianoes wants to merge 5 commits into
Conversation
The `mavsdk` name on PyPI is being handed over to the native binding that lives in the main MAVSDK repository, which has a different API and no gRPC dependency. This builds the same sources as two distributions, selected by MAVSDK_DIST_NAME: mavsdk-grpc (default) imports as mavsdk_grpc mavsdk (legacy) imports as mavsdk, warns on import The two deliberately install under different import names. Sharing the `mavsdk` import name would let them silently overwrite each other's files whenever both end up in one environment -- easy to reach through transitive dependencies, and something pip has no way to express a conflict about. Nothing inside the package imports absolutely, so remapping through package_dir is enough and no source file needs to know about it. The import-time warning is a FutureWarning rather than a DeprecationWarning: the latter is filtered out by default unless it is raised from __main__, which would hide it from exactly the people who need to see it.
The gRPC wrapper now installs under the mavsdk_grpc import name, so that it cannot collide with the native binding that takes over the mavsdk name.
Adds a banner to every page of the sphinx docs, rather than a note on the index alone: search engines drop people directly on deep pages such as plugins/telemetry.html, which an index-only note would never reach. The banner overrides the `document` block rather than `body`. Sphinx's own page.html also overrides `body` and, being the more derived template, would win -- a banner placed there would never render. Framing is "this documents the gRPC wrapper, the native binding is over there" rather than a deprecation notice, since mavsdk-grpc continues to be released, including for MAVSDK v4.
Each job now builds the wheel twice, once per distribution name, rather than gaining a matrix dimension -- the existing rename and repair steps already glob over the whole dist/ directory, so they handle both wheels unchanged. Also adds --skip-existing to the uploads. A version number that has been published to PyPI can never be reused, so a release that fails partway through four independent upload jobs would otherwise be unrecoverable without bumping the version. Note that the token in TWINE_PASSWORD must be account-scoped for the release that first creates mavsdk-grpc: a project-scoped token cannot create a new project.
julianoes
commented
Jul 22, 2026
Comment on lines
+27
to
+39
| warnings.warn( | ||
| "The 'mavsdk' package has been renamed to 'mavsdk-grpc'. This is the " | ||
| "last release of the gRPC wrapper under the 'mavsdk' name: that name " | ||
| "now refers to the native MAVSDK binding, which has a different API.\n" | ||
| " To carry on with this API, install 'mavsdk-grpc' and use " | ||
| "'import mavsdk_grpc as mavsdk'. The code is identical, development " | ||
| "continues there (including releases for MAVSDK v4), and it installs " | ||
| "under a separate import name so it cannot collide with the native " | ||
| "binding.\n" | ||
| " To freeze instead, pin 'mavsdk<4' (no further updates).\n" | ||
| " To migrate, see https://mavsdk.mavlink.io/main/en/python/", | ||
| FutureWarning, | ||
| stacklevel=2, |
Collaborator
Author
There was a problem hiding this comment.
@JonasVautherin this is the important warning.
The notices previously linked to the Python docs index, which documents the gRPC API and is therefore the wrong place to land someone who has just been told their API is changing. Point them at the dedicated migration page instead (added in mavlink/MAVSDK).
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
1 participant
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.
Prepares this repo for the
mavsdkPyPI name going to the native binding in the main MAVSDK repo. No runtime changes, and nothing publishes until a tag is pushed.A tagged build publishes the same sources twice, selected by
MAVSDK_DIST_NAME:mavsdk-grpc(default)mavsdk_grpcmavsdk(legacy)mavsdkFutureWarningmavsdk-grpckeeps being developed, including for MAVSDK v4.mavsdkships once more carrying a notice.Different import names on purpose — the bit worth sanity-checking. Sharing
mavsdkwould let the two silently overwrite each other whenever both land in one environment (easily reached via transitive deps; pip has noConflicts). Cost: migrating users edit an import, not just a requirements line — acceptable sincepin mavsdk<4already covers anyone wanting zero changes. No source file changed; the package imports relatively, sopackage_dirremapping was enough.Two non-obvious details:
FutureWarningrather thanDeprecationWarning, which is filtered by default outside__main__; and the docs banner overrides sphinx'sdocumentblock, becausepage.htmloverridesbodyand would win.Verified locally: both wheels build with the expected
top_level.txt; imports behave as tabled; docs banner renders on all 45 pages; ruff and codespell pass.Also adds
twine upload --skip-existing, since a published version number can never be reused and this doubles the number of uploads that could fail partway.Note:
TWINE_PASSWORDmust be account-scoped for the release that first createsmavsdk-grpc(a project-scoped token cannot create a project). Worth a TestPyPI dry run before tagging.