Looking for gaps and disagreements...

[ElliotGarbus]

I've been working on a mobile build tool for python. I have discovered a gap.
There is currently no standard way to integrate native mobile content (Java, swift...)
into a python wheel - but there is a need. This spec is my attempt at closing this gap.

It's a draft, nothing is implemented, and it's deliberately not one tool's
feature — a convention only one tool reads isn't worth defining.

Reading order

Don't start with the spec — it's ~17k words.
README first, then
one example:
pystripe
to see both halves of one integration,
Appendix D
is a one-line description of every key if you'd rather scan the surface.

What I'd genuinely like torn apart

1. Is the declaration set right — what's missing, what's unnecessary?

2. Does the "app keeps authority" split land in the right place?

A package may request a permission or register a component, but only the app
may mark a feature required or a component exported, and the app can suppress
any contributed permission. A package can never write an entitlement, and never
writes an iOS purpose string — that text is App Store reviewed and the app
answers for it.

3. If you maintain a build tool: is this something you'd plausibly read?

There are 26 numbered obligations on a consuming tool in §8. If one of them is
unimplementable in your architecture, that's the most valuable thing you could
tell me.

[freakboy3742]

Repeating the enthusiasm for this as an effort that I expressed in the Briefcase forum - +1 to the general idea this is proposing; I need to find some time to dig into the specifics. I hope to be able to do that next week; my colleague @mhsmith is on leave at the moment, but should be able to provide more substantial Android feedback when he returns in early September.

[freakboy3742]

(Dropping in to say that I haven't forgotten about this - my week got away from me. Next week maybe...🤞)

[ElliotGarbus]

No worries. I've been working to improve the readability. I'll let you know when that work is finished. Have a great weekend.

[ElliotGarbus]

@freakboy3742
Just sharing... As I was adding capabilities to the native-integration spec things started to get increasingly complex. I'm now modifying my approach.

Instead of: The sidecar contains everything necessary for a build tool to correctly integrate the package.

The updated target is: The sidecar automates the portable, repeatable parts of integration and tells the application author exactly what remains to be done. Effectively it is a way to put TODOs into the app's pyproject.toml.

The sidecar simplifies to:

1. Native material the package author provides
   source
   Maven dependencies
   Swift packages
   fixed manifest/plist contributions

2. Constraints the package requires
   SDK/deployment floors
   application-supplied values/files

3. Things the app author must do
   structured if native-integration understands them
   otherwise a manual application action

My expectation is this will make the spec easier to understand and maintain. I was jumping through too many hoops to add things the app author was better positioned to do. This will reduce the complexity of authoring a sidecar.

I'll let you know when the spec is ready for review. Thanks for your patience.

[ElliotGarbus]

@freakboy3742 The spec is now ready for review. The readme and spec have both been updated. I look forward to your feedback.

[mhsmith]

Thanks for looking into this. The specification definitely addresses some important use cases, but I think it's a bit over-ambitious with its scope, and overlaps several things which are better dealt with in other ways:

• Most importantly, the entire area of how Python code can declare dependencies on non-Python packages, from sources such as Gradle or Swift, has already been extensively discussed under PEP 725. Although this hasn't been approved yet, I think it addresses all the use cases mentioned in your spec, and is complete enough that app build tools could already start providing partial implementations of it.

• I don't think we should encourage Python packages to include Java, Kotlin or Swift source code. The whole point of the wheel format was to get away from a Python package installer having to compile non-Python code from source, because then it has to worry about all the complexity of build-time tools, configuration and dependencies.

  Instead, packages that require code in these languages should release it as a pre-built artifact through the same mechanism as an external library, as discussed in the previous paragraph. Such an artifact would also provide a place for any language or platform-specific metadata such as PrivacyInfo.xcprivacy or Android resource files.

• I'm not clear why the spec uses the entry-point mechanism. Wouldn't it be much simpler to put the native.toml in a fixed location under each package's dist-info directory?

• The requires items seem mostly unhelpful:

  • min_sdk and deployment_target are already covered by the Android and iOS wheel tags.
  • compile_sdk doesn't need to be configurable, because as far as I know there's no downside to setting it as high as possible.
  • target_sdk can't be handled as a simple floor, because it triggers backward-incompatible changes, and code could depend on either the old or the new behavior. A more complex dependency mechanism involving both floors and ceilings could be devised, but I'd need to see some realistic use cases before I was convinced this is worth the effort.

So the main thing that leaves is app-level configuration items in various files. As Russell mentioned here, there are a large number of these and they're frequently changing, so maintaining a mapping of them to TOML format would be a significant maintenance burden.

Instead, the approach we've taken with Briefcase is to provide extension points in the relevant parts of each file, where arbitrary string content can be inserted in its original format. We use this most extensively on Android: see the "extra_content" settings. The set of extension points is likely to change much more slowly than the set of things that can be inserted there, so I think it would make sense for us to try and standardize that across multiple app build tools.

[ElliotGarbus]

Thanks for the thoughtful feedback. I'm not familiar with PEP 725 so I'll give that some careful consideration.

The wheel-format argument is that an installer shouldn't have to compile. Here it doesn't. The consumer is a build tool that has already provisioned the JDK, Android SDK and Gradle, or Xcode and swiftc, and is about to invoke them. Adding a .java file to a Gradle source set introduces no new build-time tool, configuration or dependency — the toolchain complexity that motivated wheels is already present by definition.

The case I actually care about is narrow: a short @objc shim, or a BroadcastReceiver subclass whose only job is to bridge to the Python half and whose correctness is coupled to it. Requiring a Maven or SPM publish for that means two release processes and a version pair to keep in lockstep, for a change that is one file. On a single-maintainer community package that's a real tax. The spec already recommends a published dependency for anything larger than a few glue classes. What do you think?

Is there a backend-agnostic way to put a file into .dist-info? I didn't find one. The entry point is a workaround for that absence, not a design preference. If I've missed a mechanism, say so and I'll switch; it's strictly simpler than what I wrote.

I'll review the requires floors section. It was an oversight - I was not considering how the tags carry that information. I may be able to drop both floors entirely - that is a win! Thank you!

On maintenance burden, I experienced this problem with my first draft of the spec. I resolved this with two tables: values and actions. These are designed to avoid the mapping problem rather than take it on.

A value is a string the application must supply where the package author knows the platform key it goes to. The package author writes kind = "manifest_meta_data", key = "io.sentry.dsn". The build tool scaffolds a placeholder into the application's config, the app author fills in their DSN, the build tool writes it to that key.

The spec enumerates kind — a small closed set of delivery sites — and never enumerates keys. The package author spells the key, because the package author knows it. So there's no table of platform keys to maintain.

An action describes the work only the application author can do. WeChat needs a WXEntryActivity in <applicationId>.wxapi implementing IWXAPIEventHandler — a class in the application's own namespace. The package author declares the outcome and acceptance criteria, the build tool scaffolds it commented out, the application author does the work and uncomments an acknowledgement.

Both action and value carry identity (distribution, platform, id), so an unfilled placeholder is detectable and every requirement is reportable against the distribution that raised it.

On "extra_content" — I'll look properly, though my first reaction is that those settings are all app-level, so they let the app author express anything but don't let a package contribute anything, which is the inversion I started from.

As I said I'll take a closer look at PEP 725.

Thanks again for the feedback.

[mhsmith]

The spec already recommends a published dependency for anything larger than a few glue classes. What do you think?

I think that if you provide a mechanism that only works for trivial use cases, people will immediately start asking for it to be made more complex once they move beyond the trivial. In fact, this process has already started in the current version of the spec, as you've added the accessed_api_types table to go along with the Swift code.

It makes far more sense for code in other languages to always be delivered in the native package format of that language, so that the full capabilities of that format are available. If that makes the publishing process more complex, well that's just the price of using multiple languages in a project.

Is there a backend-agnostic way to put a file into .dist-info? I didn't find one.

Maybe not. But since entry points are intended to be used for executing code at runtime, I don't think they're an appropriate way to work around this.

Like PEP 725, it would be reasonable for this proposal to include changes to the format of pyproject.toml, dist-info or the METADATA file. The data structures in the spec are too complex to be put into the METADATA file directly, but you could define a new dist-info file, say that its content is taken from a corresponding section of pyproject.toml, and leave it up to the backend to implement that.

[ElliotGarbus]

@mhsmith
I spent some time looking at PEP 725, though, and I don’t think it covers the same problem.

So I currently see the roles as:

• PEP 725: external dependencies and tools required to build a Python distribution.
• Native Integration: how a Python package participates in the construction of the containing Android or iOS application.

There is some conceptual overlaps around declaring non-Python dependencies, but I don’t yet see a PEP 725 mechanism that replaces the application’s integration metadata or materially simplifies it.

PEP 725 provides standardized metadata for a Python project’s external build and runtime dependencies. Its build/host distinction in is describes what must be present to build a Python distribution, including the cross-compilation case.

Native Integration describes a different relationship: what a Python package contributes to, requires from, or asks of the native application that contains it.

For example, KivMob needs the Google Mobile Ads Maven dependency, but that is only one part of its native integration. It also includes the Python code that exposes that native functionality, contributes Java source and Android permissions, requires the application to supply an AdMob application ID at a particular manifest location, and may require actions from the application author. Those things collectively form the package's integration contract with the application.

There is clearly some overlap at the edges — a Maven or SwiftPM dependency is both an external dependency and a native application contribution. But I don't yet see how PEP 725 addresses the broader Native Integration use cases such as permissions, contributed native source, manifest/plist contributions, application-supplied values, ownership/collision handling, or application actions.

If you have specific ideas of how PEP 725 can be used to represent those cases, I'd be interested in understanding it. That might help identify whether there is useful overlap I'm missing.

[mhsmith]

I wasn't suggesting that PEP 725 solves all of those cases, only that it solves the Gradle and Swift dependency case, so that should be removed from the scope of your proposal.

[mhsmith]

Another area which I think is out of scope is anything to do with resolving dependencies, e.g. such paragraphs as:

• "Determine the candidate set: the resolved dependency closure of the application for the target platform. Every environment marker and extra MUST be evaluated for the target — its platform and its Python version — and never for the build host."
• "For each producer, a consumer MUST be able to state how it entered the dependency closure. Where several dependency paths exist, the consumer MUST report at least the producer's immediate dependents, and any path it reports MUST be deterministic across runs."

These are trespassing into the behavior of package installation tools such as pip, which seems unnecessary in this context.

[mhsmith]

As you can see, most of my comments have been aimed at reducing the scope and complexity of your proposal. As it stands, these are already at about the same level as PEP 725/804, which have proven to be about the limit of what the community can handle.

The excessive LLM-generated verbosity is also going to be unpopular. You'll need to get that under control if you want much more engagement from me or anyone else.

[ElliotGarbus]

@mhsmith

Looking at extra_content, I see it gives an application author a way to add content to the generated native project. That's useful, but it still requires the application author to know and reproduce the integration requirements of each Python package.

The goal of Native Integration is for those requirements to travel with the Python package itself, so a consumer such as Briefcase or another application builder can discover them and compose them into the application. The application author should only need to deal with the parts that actually require application-specific decisions or values.

A Native Integration action could certainly be completed by an application author using extra_content to insert the required content into the app. In that sense, extra_content can be one way to carry out an integration action, but it doesn't replace the package-supplied metadata that describes what needs to be done.

[mhsmith]

I was suggesting that many of the current use cases of the spec could be achieved by the package providing extra content, which the app build tool would insert into the app's files.

For example, on Android, instead of the multi-page mapping between the XML manifest language and TOML which the spec currently contains, it would instead specify keys for a number of insertion points in the manifest, and the package metadata would map those keys to strings containing XML content to be inserted at those points. That way, the spec doesn't need to give a list of all the XML attributes it accepts, and it can immediately accept new attributes as Android adds them in the future.

The spec may also need to provide rules for how content from multiple packages should be merged, and conflicts detected, but this should still be simpler overall than what you currently have.

[ElliotGarbus]

@mhsmith
Looking at your comments on the requires more closely. The spec covers the "sidecar" — this is information inside a python package. The python package itself may not contain any binary content, so no meaningful wheel tag. It could, for example, contain a Gradle coordinate and a python wrapper.

The floors exist in the sidecar because of what a build tool does with them, not because of anything pip needs. Once a compliant built tool resolves the dependency closure, it configures one Gradle build for every native SDK the closure pulled in — reading min_sdk, compile_sdk, target_sdk, and deployment_target off each sidecar and comparing them against what the app author configured. If the app is set too low, it fails and names the specific package that needed more, before Gradle or Xcode fails two layers down with an error that names no package at all.

That's why min_sdk/deployment_target aren't redundant with a wheel tag: a wheel tag describes the package's own compiled code, if it has any; these floors describe what its native dependency needs, resolved later by Gradle or SwiftPM, in a process pip never sees.

Your feedback had me review these elements - but I'm left with them staying in place. Do let me know if I have misunderstood something.

EDIT: I'm removing target_sdk. it represents application-wide behavior policy rather than a composable package requirement. If there was a package that did have this requirement it could be expressed as an action. Thanks again for your feedback!

[mhsmith]

Current versions of pip and uv install all packages via wheels. Even when installing from source, they first build a wheel and then install it. So it's safe to assume there is always a wheel tag available in dist-info.

And if a package is only useful on Android or iOS, it would be correct for that tag to be android or ios. Multiple tags can be included on one wheel to show that it supports multiple architectures, or even multiple operating systems.

In packages that don't contain any binary content, the tag can be customized using build backend settings such as setuptools' plat-name (e.g. beeware/toga#3648), or altered after the fact with the wheel CLI.

[ElliotGarbus]

@mhsmith

Thank you for your patience and tenacity.

TL;DR: I agree with the direction, and I'll update the proposal to integrate your input. It will take me a few weeks, and I'll let you know when it's ready. Below is a short summary of each point and why I came around.

• PEP 725. When I first read this, I was thinking of it in the context of an app, not a wheel. I was too quick to dismiss it. It applies to the package as well, and adopting it removes a significant part of the spec.. Agreed and adopted.

• No source in the package. This isn't a hill I'm willing to die on. Your point about scope creep is a good one, and dropping source simplifies the spec. Without source there is also no need for compile_sdk.

• No entry points. You're right. I was enamored with a clever hack that needed no backend changes. That's fine for a prototype, but not for a spec. For early adopters I'll provide a small reference PEP 517 wrapper backend that writes the file, which can also serve as a model for backends.

• Extra content and insertion points. I first read this in the context of an app, not a package. At a high level this fits the Python ethos of "consenting adults" and removes layers of abstraction. For packages that ship an AAR, the AAR carries its own manifest and Gradle merges it, so I'm dropping the contribution tables for that case. The app keeps the final say through the manifest merger's overrides. I'll need to review some of the briefcase approach and the use cases for xml insertion, but I agree with the spirit of your direction. I can imagine that much of this will fit in the application_value/application_action model that is currently in the spec, but I have more work to do.

• Wheel tags. I was hung up on "purity": there is no binary code in the package. I've broadened my definition. A coordinate, or any other platform-specific declaration, makes the package platform-specific. A wheel tag is the standard way to express that. The floors go away because the artifacts declare their own (the AAR and Package.swift).

Given all of this, the config a package author writes goes into the package's pyproject.toml, and the sidecar disappears. The content is generated into dist-info, adopting the fixed location you first suggested.

The key element that remains is application_value and application_action. They let a package make requests of the application, and let the application provide a build-time response.

Thanks again.

[freakboy3742]

Firstly - sincere apologies for the delay in responding to this.

Responding to the three specific questions you've raised in the original post:

1. Is the declaration set right? Honestly, it's a little difficult to tell, because the scope is so broad. As a spec, this feels like it's trying to solve everything at once; to me, that's a bit of a red flag - if only because iOS and Android change their minds so often that it's difficult to predict what they're going to need next year.

It may be better to look at this with PEP 621 as an analog - an initial spec that describes the basic shape of the metadata (e.g., where it's defined, and the expectation for how it will be consumed), and some basic metadata that everyone can agree on - maybe something as simple as permissions in the first instance - but also including a "safe" namspace for tools to experiment further, and an understanding of how shared improvements can be added over time.

2. Does the "app keeps authority" split land in the right place? I'm not sure - and that's part of the overall "scope" issue.

In terms of what seems right - it makes sense for me for a library to have concrete requirements that an app must satisfy, such as the library needing the app to declare a permission or an intent for Android purposes. However, there's limits to what a library can contribute to that conversation. A library can't provide a meaningful "reason" for a permission; it can only declare that the permission requirement exists. The requirements for things like an intent declaration are both platform specific, and likely version specific within that platform.

I'm less certain about the flow of information the other way. True, an advertising library can't specify an AdMob API key. However that sort of data could be provided by a Python package (the package for "the app"); in the context of an "Android/iOS project that incorporates some Python code", it could be a "meta" package that publishes that data into a "package-like" format as part of the packaging process.

It's also unclear to me if the S2.4 "obligations on the consumer's bootstrap" are appropriate in this context - or, at least, that they point at a much more fundamental issue that needs to be addressed.

As a practical manifestation of this - Kivy-focussed libraries use PyJNIus for Android integration and PyObjUs for iOS; BeeWare library tend to use Chaquopy and Rubicon ObjC for the same platforms respectively. Having hard specifications for how code and interfaces "will" be used when it's not possible to import Kivy and Chaquopy using libraies into the same namespace seems premature. There's a separate piece of work here as well around ensuring we have platform compatibility; without that piece, making hard declarations about how an app will or won't integrate with app lifecycle seems premature.

3. Is this something I'd plausibly read? Well, yes, because I think these are important issues where standardization is important... but as @mhsmith has already said - the LLM "flavour" of this is more than a little distracting. LLM's are way too verbose and florid, in a way that impedes clear understanding. A good example of this: "Why the boundary matters" in the README concludes with "in one sentence...". To me, this doesn't aid readability - it either indicates the multi-paragraph version is too long, or the single sentence version is redundant. When combined with the ambitious scope, PEP history suggests this is a spec that could easily stall out due to the amount of consensus that it asks of the ecosystem.

Outside of those specific questions, I also share some of the concerns @mhsmith's has already raised aroud the use of entry points, including source, and PEP 725 compatibility. Based on your most recent comment, it sounds like you agree as well; so I guess I'll wait for your next revision.

The tl;dr of all this - I applaud the ambition, but I think it's a little too ambitious to succeed (at least in its current form, anyway). I feel that, as a standardization effort, it would benefit from picking a much smaller target with specific immediate goals and a path for future expansion (and a clear convention for experimentation) - and possibly being broken up in to a series of smaller specs, rather than one huge spec.

[ElliotGarbus]

Thanks for the feedback. I’ll be making a major revision and significantly reducing the scope of the spec. Much of the current spec will disappear following the recommendations from @mhsmith, and I’ll be sure to let you know when the revision is ready.

I agree with much of your feedback. The idea of taking a PEP 621-like approach is compelling. I hadn’t been thinking about the problem that way at all, so I’m going to give that careful consideration.

The key concepts I had been planning to retain are application_value and application_action. The basic idea is that a library can make build-time requests of the application, which ultimately become TODOs in the application's pyproject.toml for the application developer to resolve. application_value is really a special case of application_action.

I’ll give this more thought as I revise the spec. It may be that the application_action abstraction, together with a very small standardized vocabulary, is sufficient for version 1.

Just to set expectations, it will probably be a few weeks before I have a chance to start on the next revision.

Thanks again!

[ElliotGarbus]

@mhsmith @freakboy3742 Before I put more effort into the full proposal, I'd like to know whether this direction looks right to you.

Objective

Let a Python package that wraps an Android or iOS SDK tell the tool building the application which native dependencies it needs and what the application author must do.

Updated Proposal

A package that wraps an Android or iOS SDK declares two things in the
[tool.native-integration] table of its own pyproject.toml, which a small wrapper
backend copies into .dist-info (until this is a PEP):

• Native dependencies, Gradle Maven coordinates, Swift package URLs, and any Maven repository an SDK needs.
• Application actions: a todo list of what only the application author can do.

# pyadmob's pyproject.toml
[tool.native-integration.android.gradle]
dependencies = ["com.google.android.gms:play-services-ads:24.0.0"]

[[tool.native-integration.android.application_action]]
id = "admob-app-id"
description = """\
Set the manifest meta-data com.google.android.gms.ads.APPLICATION_ID to your \
AdMob app ID."""
reason = 'Without this tag the app crashes with "Missing application ID".'
acceptance = ["The app starts without that crash."]

[tool.native-integration.ios.swift_packages]
GoogleMobileAds = { url = "https://github.com/googleads/swift-package-manager-google-mobile-ads", requirement = { from = "12.0.0" }, products = ["GoogleMobileAds"] }

[[tool.native-integration.ios.application_action]]
id = "admob-app-id"
description = "Set GADApplicationIdentifier in Info.plist to your AdMob app ID."
reason = "Google's iOS setup requires this key, and only you have the ID."
acceptance = ["Info.plist has GADApplicationIdentifier set to your iOS app ID."]

A build tool (Briefcase, kivyforge) reads this from each installed package and passes the dependencies to Gradle or SwiftPM, much as an installer handles Requires-Dist. How it does that is its choice, including whether it records them in pyproject.toml or a lock file.

The build tool also appends each new action to the application's pyproject.toml, with an
empty response. The author answers it:

# Added by kivyforge. Requested by pyadmob.
# Set the manifest meta-data com.google.android.gms.ads.APPLICATION_ID to your AdMob app ID.
# Why: Without this tag the app crashes with "Missing application ID".
# Acceptance: The app starts without that crash.
[tool.native-integration.ack.pyadmob.android.admob-app-id]
response = "Set in the AndroidManifest template."

The response is an acknowledgement, not a claim that the action was taken. "Not using the scanner, so no camera access is needed" is a valid answer. The tool reports every empty response on every build. Whether an empty response fails the build (or warns)
is the tool's choice.

Every action is manual in v1. No tool writes on an application_action to the manifest or Info.plist. The author will use what the build tool already provides, such as Briefcase's android_manifest_extra_content.

Permissions are not in this metadata. If a package needs one its SDK doesn't declare, it uses an application_action to ask the author to
declare it. Similarly, on iOS an application_action asks the author to write a purpose string.

This proposal follows Russell's PEP 621 suggestion: it defines where the data lives and how it is read, and keeps the initial metadata small.

A change on PEP 725

Previously, I wrote "Agreed and adopted" about PEP 725. I'm walking that back. I tried converting the 18 example packages, 15 of them hypothetical wrappers around real SDKs, and it is better to leave these mobile dependencies in their native format.

DepURLs are meant to be portable across packaging ecosystems, and virtual packages let each ecosystem choose a provider. That fits system dependencies. Here each platform has one resolver, and a Gradle coordinate or Swift URL names exactly one artifact. A tool would only convert the DepURL back again.

All 17 Gradle dependencies convert, but gain nothing. A Swift dependency has no complete DepURL: SwiftPM links products, and PURL's swift type does not define a way to name them. All 15 Swift packages in the examples name products, and in 13 none is named after the
repository.

I take PEP 725's flow from pyproject.toml into the wheel, like PEP 725, this puts no obligations on installers. A package can use both: PEP 725 for building a wheel, and this proposal for what the application links.

Where I'd like your view

1. Are dependencies plus a todo list the right scope for v1?
2. Malcolm, you asked me to leave these dependencies to PEP 725. Is there value in
   [external] here that I'm missing?
3. Russell, you suggested permissions as possible first metadata. Would you recommend
   adding metadata for permissions?

And of course any other feedback is welcomed. None of this has been built.

[freakboy3742]

Where I'd like your view

1. Are dependencies plus a todo list the right scope for v1?

This seems like an achievable scope. The only thing I'd flag is that in reducing the scope, it's also necessary to (a) flag that the scope is intentionally tight, and (b) indicate where future expansions would "fit" in the proposed specification.

2. Malcolm, you asked me to leave these dependencies to PEP 725. Is there value in
   [external] here that I'm missing?

I can't speak for Malcolm, but from my perspective, I can see two advantages:

1. It's one less thing we need to standardise as part of this specification
2. Conflict resolution. The "pass through requirements raw" approach doesn't provide any scheme for resolving conflicting or overlapping dependencies. If my Android application has 2 Python package dependencies, and they both declare a dependency on different versions of the Foobar maven package - how is that resolved when all I have is the "raw" Maven declaration?

It might be useful to reference PEP 725, with some examples of how a Gradle or Swift dependency would be rendered in PEP 725 syntax - if not in the "proto-PEP", then at least in the discussion around it.

3. Russell, you suggested permissions as possible first metadata. Would you recommend
   adding metadata for permissions?

I think it might be worth it. Permissions are a very clear and present use case; but also, having an example of a "fully worked application action" provides proof that the spec would be able to expand in future to encompass other needs.

If this is combined with going "all in" on PEP 725, then this specification essentially reduces to a mechanism for asking the build environment for certain pre-conditions - one of which is permissions, which we've provided a specification for; but more generally, any other requirement which can be declared in an ad-hoc fashion (in a similar way to how PEP 518 declares the existence of the [project] table with known keys, but allows any other tool to define a [tool.XXX] table).

And of course any other feedback is welcomed. None of this has been built.

I'm not sure I fully understand the workflow you're suggesting around how an application that uses a package (or a build tool compiling that information) will use the metadata that has been declared.

An open ended "tag with details" definitely makes sense as an approach, and the id and description fields make sense for an ad-hoc tag declaration. However, I'm not sure I understand how reason or acceptance would be used; and it's not clear to me why the build tool would append anything to the app's pyproject.toml, or why declaring compliance in this case would be anything more than a boolean or inclusion on a list. I'm guessing the intention is to provide enough metadata for a build tool to describe how a requirement is satisfied, but I'm not sure how a build tool would determine that compliance has been met; and assuming it has been that the compliance is current - that is, if I declare that "yes, I have specified permissions", and then I upgrade the package, which has updated requirements... how does the build tool establish that the previous declaration is inaccurate?

It also doesn't address the underlying configuration issue that seems like part of this problem. If you take something like an AdMob ID, that's application-provided metadata that the library needs to be able to access. It seems to me like part of this specification should be an importlib-metadata extension/analog whereby a package can request details - so as a package, I'd declare that I need to know the deployment's AdMob ID, and it's the deployment's responsibility to provide that detail.

[ElliotGarbus]

@freakboy3742 Thanks for your continued engagement and inputs.

The only thing I'd flag is that in reducing the scope, it's also necessary to (a) flag that the scope is intentionally tight, and (b) indicate where future expansions would "fit" in the proposed specification.

I'll keep this in mind as this progresses from "scope" to a fleshed out proposal.

It's one less thing we need to standardise as part of this specification

Agreed. There is value in the layout of the metadata in .dist-info. There is however limited value in the PURL concept for this use. Part of my concern is converting a coordinate into a different format that it's native format only to have to convert it back to its native format to be used by the app build tool.

I'll render a maven and swift "coordinates" in a follow up message. Perhaps an update to 725 that better supports mobile and addresses the issue with swift is a better path.

Conflict resolution. The "pass through requirements raw" approach doesn't provide any scheme for resolving conflicting or overlapping dependencies. If my Android application has 2 Python package dependencies, and they both declare a dependency on different versions of the Foobar maven package - how is that resolved when all I have is the "raw" Maven declaration?

Conflict resolution is not covered in PEP 725. Gradle and Xcode each have a way of dealing with conflicts.

The app build tool (Briefcase, kivyforge, etc.) can choose to detect conflicts before handing off, or leave them to Gradle/Xcode. I’d suggest the spec recommend the former, because the app build tool knows which Python distribution declared each dependency and can name it, where a Gradle or Xcode error can’t.

To be clear, the dependencies aren’t passed through as raw build-file text. Each is a structured native coordinate (Maven group/artifact/version; Swift package URL, version requirement and product), so the app build tool can recognize when two distributions declare the same artifact, merge them into a single declaration, and report the conflict against the distributions that caused it. Resolving the versions themselves is still left to Gradle and SwiftPM.

...this specification essentially reduces to a mechanism for asking the build environment for certain pre-conditions - one of which is permissions, which we've provided a specification for; but more generally, any other requirement which can be declared in an ad-hoc fashion (in a similar way to how PEP 518 declares the existence of the [project] table with known keys, but allows any other tool to define a [tool.XXX] table).

I like this framing a lot. It turns "dependencies plus a TODO list" into a container with a clear path to grow. As I understand it:

1. Base requirement: id, platform, description. Every compliant tool can at least report it to the app author. The applicaiton_action is an example.
2. Standardized kinds: known keys defined by the spec. Permissions would be the first. A tool that understands a kind can apply it or verify it automatically.
3. Tool-namespaced kinds: e.g. briefcase.*, analogous to [tool.XXX], for things not yet standardized. This seems out of scope for this spec, as it applies to the app build tool. Do I have this right?

Does that match what you had in mind? If so, I'll restructure the proposal around it, with permissions as the worked example.

However, I'm not sure I understand how reason or acceptance would be used; and it's not clear to me why the build tool would append anything to the app's pyproject.toml, or why declaring compliance in this case would be anything more than a boolean or inclusion on a list. I'm guessing the intention is to provide enough metadata for a build tool to describe how a requirement is satisfied, but I'm not sure how a build tool would determine that compliance has been met; and assuming it has been that the compliance is current - that is, if I declare that "yes, I have specified permissions", and then I upgrade the package, which has updated requirements... how does the build tool establish that the previous declaration is inaccurate?

reason explains why this application_action is being requested. I was thinking about this in the context of the plyer library https://github.com/kivy/plyer. plyer is an abstraction layer that covers a broad set of capabilities (camera, bluetooth, vibrator...) rather than just request all of the supported capabilities, each would have an associated reason. This is a text field that explains why a library is requesting a capability from the app author.

acceptance The concept here was to provide a coding agent the acceptance criteria to support an automated test. The acceptance lists what can be checked to ensure the request was satisfied when examining the built artifact or runtime behavior. This is an optional field.

response This is for any requirement the tool cannot verify on its own. This is effectively a Boolean with documentation. An empty entry causes the build tool to react to the entry as an unsatisfied request. The text describes how the app author decided to satisfy the request and provide that as documentation.

I understand your pushback on having the build tool modifying the pyproject.toml, I'll change that. The idea was the response to the request needs to be there - but how it gets there does not need to be in the spec, and it is better to have the author remain the editor.

I've run out of time this morning...
I'll follow up here later today with a few examples pulling these ideas together across different use cases. I'll also provide the PURL renderings for gradle and swift coordinates, and we can discuss how to take these forward into pep 725 or a different course of action. I'll also respond to your feedback on how to manage package upgrades.

Thanks again!

[freakboy3742]

Agreed. There is value in the layout of the metadata in .dist-info. There is however limited value in the PURL concept for this use. Part of my concern is converting a coordinate into a different format that it's native format only to have to convert it back to its native format to be used by the app build tool.

Agreed that converting between formats needs to be considered carefully.

I'll render a maven and swift "coordinates" in a follow up message. Perhaps an update to 725 that better supports mobile and addresses the issue with swift is a better path.

That definitely sounds like a good way forward - completely independent of this specification, it is something that could be useful for building third party wheels that have library dependencies.

Conflict resolution is not covered in PEP 725.

True - but that's because for the purposes of building, there are no conflicts to resolve. When building package X, there's no potential for a second package with a conflicting requirement.

However, the specification supports both version number ranges and PEP 508 environment metadata, which is all Python dependency resolution requires to implement a conflict resolution scheme.

To be clear, the dependencies aren’t passed through as raw build-file text. Each is a structured native coordinate (Maven group/artifact/version; Swift package URL, version requirement and product), so the app build tool can recognize when two distributions declare the same artifact, merge them into a single declaration, and report the conflict against the distributions that caused it. Resolving the versions themselves is still left to Gradle and SwiftPM.

I think I can see how this can work; my concern is that the merge process seems like 50% of a dependency resolution system, and we'll end up with a situation where half the resolution process is done by Python, and half by Gradle/SwiftPM - and the latter will be potentially inconsistent between projects.

...this specification essentially reduces to a mechanism for asking the build environment for certain pre-conditions - one of which is permissions, which we've provided a specification for; but more generally, any other requirement which can be declared in an ad-hoc fashion (in a similar way to how PEP 518 declares the existence of the [project] table with known keys, but allows any other tool to define a [tool.XXX] table).

I like this framing a lot. It turns "dependencies plus a TODO list" into a container with a clear path to grow. As I understand it:

1. Base requirement: id, platform, description. Every compliant tool can at least report it to the app author. The applicaiton_action is an example.
2. Standardized kinds: known keys defined by the spec. Permissions would be the first. A tool that understands a kind can apply it or verify it automatically.
3. Tool-namespaced kinds: e.g. briefcase.*, analogous to [tool.XXX], for things not yet standardized. This seems out of scope for this spec, as it applies to the app build tool. Do I have this right?

Does that match what you had in mind? If so, I'll restructure the proposal around it, with permissions as the worked example.

I agree that actually specifying the briefcase.* parts is out of scope - but carving out the portion of the namespace where tool-specific configurations would live should be in scope. Otherwise, I think this looks like a good starting point.

reason explains why this application_action is being requested. I was thinking about this in the context of the plyer library https://github.com/kivy/plyer. plyer is an abstraction layer that covers a broad set of capabilities (camera, bluetooth, vibrator...) rather than just request all of the supported capabilities, each would have an associated reason. This is a text field that explains why a library is requesting a capability from the app author.

Does this actually provide any value though? What is the reason that Plyer is asking for camera permission? So it can use the camera. Why does it need bluetooth access? So it can use Bluetooth. I'm not sure I see what additional information a library would be attempting to convey here.

An app definitely needs reasons - but those essentially need to be application specific to be useful: I need access to the camera so that I can take photos of objects to be identified by my "What is it?" app. I need bluetooth access so my Home Assistant remote can contact IoT devices in your house. But I'm not sure I see what value library level reasons adds.

I think the plyer example opens another problem - If I import Plyer, but I only want to use the camera - I don't need to declare Bluetooth and vibrator configurations. So - there's a "negotation" needed here:

• a package declares the "features" it exposes, and what the app must provide/specify to use that feature
• an app declares what features it wants from which package

acceptance The concept here was to provide a coding agent the acceptance criteria to support an automated test. The acceptance lists what can be checked to ensure the request was satisfied when examining the built artifact or runtime behavior. This is an optional field.

I'm a little wary of doing something specifically for a coding agent - if something is useful to a coding agent, it should be useful for a human as well. Fundamentally, I'm not sure I see how a 1 line "acceptance criteria" statement in english will be able to capture enough meaningful context to be actionable.

response This is for any requirement the tool cannot verify on its own. This is effectively a Boolean with documentation. An empty entry causes the build tool to react to the entry as a unsatisfied request. The text describes how the app author decided to satisfy the request and provide that as documentation.

Ok - but who is consuming that information? The build tool won't be able to do anything meaningful with free-text; is the intention that it's not much different to:

enabled = True  # "Set in the AndroidManifest template."

?

[ElliotGarbus]

@freakboy3742 Thanks, this is sharpening things considerably.

Conflict resolution is not covered in PEP 725.

True - but that's because for the purposes of building, there are no conflicts to resolve. [...] the specification supports both version number ranges and PEP 508 environment metadata, which is all Python dependency resolution requires to implement a conflict resolution scheme.

Understood, For native dependencies, though, I don't think resolution can happen on the Python side even with ranges and markers. Maven and SwiftPM dependencies have their own transitive dependencies, which only Gradle and SwiftPM see. A Python-side resolver would be working from an incomplete graph.

my concern is that the merge process seems like 50% of a dependency resolution system, and we'll end up with a situation where half the resolution process is done by Python, and half by Gradle/SwiftPM

Agreed: merging is resolution, and the spec shouldn't ask build tools to do it. The position I'd take is aggregation, not resolution:

• The app build tool collects each distribution's coordinates unchanged and hands them to Gradle or SwiftPM, which do all the resolution.
• One clean way to do this is a wrapper module per Python distribution (a local Swift package or a Gradle library module) that declares only that distribution's dependencies. Nothing is merged in Python, and SwiftPM's duplicate-declaration problem goes away.
• The spec requires attribution: conflicts must be reportable against the distribution that declared them. If the wrappers are named after their distributions, native errors carry the Python name. A tool that wants earlier errors can run the native resolver before the full build and map the result back, rather than implementing its own conflict rules.

That keeps the result consistent across tools, since every tool hands the same declarations to the same engine.

One consequence matters here. A Python binding is written against a specific native API, so the Python version effectively pins a compatible native range. Gradle's default "highest wins" can silently hand a package a native version its binding wasn't written for, which breaks at runtime with no build error. So package authors should declare the native range their binding actually supports, and the app build tool should pass it to Gradle as a strict constraint, so an incompatible combination fails the build instead.

There's a known limitation. When native constraints conflict, the fix is usually a different version of a Python package, but pip and uv choose versions without seeing native constraints. Today the app author has to backtrack by hand. If native constraints live in .dist-info in structured form, a future Python resolver could take direct native conflicts into account. I'd keep that out of v1, but it's another argument for structured metadata over opaque text.

carving out the portion of the namespace where tool-specific configurations would live should be in scope.

Agreed. I'll reserve a prefix for tool-defined kinds (something like tool.<name>.*) without specifying what goes in it.

Does this actually provide any value though? [...] I'm not sure I see what value library level reasons adds.

You're right. Library-level reasons are mostly "so it can use the camera," and the reasons that matter (iOS purpose strings in particular) have to come from the app. I'll drop reason.

So - there's a "negotiation" needed here

This is the most useful point, and it replaces the optional flag I was considering:

• A package declares named features, each a group of requirements. Requirements outside any feature always apply.
• The app selects the features it uses, and only those requirements apply.

Plyer is the motivating case: select camera, and Bluetooth and vibrator never come up. It looks like extras (plyer[camera]), but extras can't carry it, because installed metadata records which extras a package provides, not which were requested. So feature selection has to live in the app's configuration.

I'm a little wary of doing something specifically for a coding agent [...]

Fair. I'll drop acceptance from v1. A well-written description should say what needs doing and how to tell it's done, for humans and agents alike.

is the intention that it's not much different to enabled = True # "Set in the AndroidManifest template."?

Yes, that's exactly it. The tool consumes a boolean; the comment is for whoever maintains the app later, and the spec doesn't need to define it. To handle staleness, each requirement carries a revision that the package author bumps when the requirement changes. Acknowledgements are keyed to distribution, id, platform and revision, so an upgrade that changes a requirement invalidates the old acknowledgement. With feature selection in place, acknowledgements are needed only for ad-hoc requirements in selected features.

Putting this together, the scope becomes:

1. Native dependencies (format pending the PEP 725 discussion), aggregated but not resolved by the app build tool.
2. Requirements: the generic application_action (id, platform, description, revision), which any tool can report; standardized kinds built on it (permissions first), which a tool can apply or verify; and a reserved namespace for tool-defined kinds.
3. Features: named groups of requirements, selected by the app.
4. Boolean acknowledgements for requirements the tool can't verify.

[ElliotGarbus]

PEP 725 Discussion

@freakboy3742 @mhsmith Here are the renderings I promised, using PEP 725 DepURLs.

Gradle coordinates fit, except BOMs (below). All 17 in the examples convert:

com.google.android.gms:play-services-ads:24.0.0
dep:maven/com.google.android.gms/play-services-ads@>=24.0.0?type=aar

I use >= because Gradle may select a higher version, and @24.0.0 would mean exactly that version. Android SDKs are usually AARs, and PURL's default type is jar, so the DepURL needs ?type=aar. The native coordinate doesn't.

Swift dependencies do not fit. The URL and version convert, but SwiftPM links products, and PURL's swift type defines no way to name them. All 15 Swift packages in the examples name products, and in 13 none is named after the repository. The subpath below is only my convention:

url = "https://github.com/firebase/firebase-ios-sdk", requirement = { from = "11.0.0" }, products = ["FirebaseMessaging"]
dep:swift/github.com/firebase/firebase-ios-sdk@>=11.0.0,<12#FirebaseMessaging

What would need to change

Through DepURL changes or a native expression in PEP 725:

• Swift products: a defined way to name them, one or several per package. purl-spec#400 is open on a related naming problem, with disagreement over subpaths.
• Swift embedding: a way to say a product must be embedded in the app.
• Maven versions: a way to write versions that aren't PEP 440. 116 of Guava's 162 versions fail, including 33.8.0-android.
• Maven BOMs: a way to import a BOM as a Gradle platform, so dependencies can omit their versions. A DepURL can name the BOM's file with ?type=pom, but can't say to import it.
• Maven repositories: a way to limit a repository to named groups. repository_url only says where one package is.
• Registry: tools may warn or error on names missing from the PEP 804 registry, which doesn't mention Maven or Swift.

I'd prefer a native expression. Authors can copy coordinates from the vendor's documentation and tools can pass them on unchanged, whereas converting by hand only adds chances for error.

PEP 725 lets later PEPs add fields to [external]. Malcolm, do you think its authors would accept a native table such as [external.mobile]? Until this is a PEP, it would stay in [tool.native-integration].

[freakboy3742]

What would need to change

Through DepURL changes or a native expression in PEP 725:

• Swift products: a defined way to name them, one or several per package. purl-spec#400 is open on a related naming problem, with disagreement over subpaths.

Agreed this is a complication - I imagine there would be pushback against adopting extensions to the PURL specification that haven't been accepted upstream (although I guess they're already partially outside the spec by using the dep: prefix)

• Maven versions: a way to write versions that aren't PEP 440. 116 of Guava's 162 versions fail, including 33.8.0-android.

Is that a problem? VERS seems to allow a wide range of version specification that aren't necessarily PEP 440 compliant - AFAICT that's only a problem for us because it complicates the process of merging like dependencies.

PEP 725 lets later PEPs add fields to [external]. Malcolm, do you think its authors would accept a native table such as [external.mobile]? Until this is a PEP, it would stay in [tool.native-integration].

I'm not sure I follow what you're suggesting needs to be added here. The issue faced for app-level integration is runtime dependencies. That isn't mobile specific - Linux GUI apps have the same problem today with runtime GTK requirements, for example.

[ElliotGarbus]

The idea was to have a table that allows the use of a swift or maven coordinate directly rather than using a depURL. The idea was to build off the PEP725 [external] table, with [external.mobile]; that name is just a place holder, could be [external.native] or [external.runtime]...

[external] - for using depURLs
[external.somthing_else] - for using native coordinates.

On version - I don't know about VERS, but the spec seems quite clear. This is a subset of the larger native coordinate issue.

[ElliotGarbus]

#Follow up on PEP 725 Versioning
@freakboy3742 You asked about VERS. PEP 725 doesn't use it, and that's where the limit comes from:

• Versioning: considers vers URIs and chooses a subset of PEP 440 instead, because vers isn't ergonomic. From the spec, "Since none of these options are very ergonomic, we chose instead for DepURLs to accept version range specifiers too with semantics that are a subset of PEP 440 semantics."
• DepURL: version MUST use that subset.
• Rejected ideas: rejects ecosystem-specific version comparison, and suggests a comment or qualifier for those cases.

Guava shows the effect. It specifies its flavor in the Maven version, so an Android app needs 33.8.0-android. I tested that with pyproject-external 0.1.17, the PEP's reference implementation:

dep:maven/com.google.guava/guava@33.8.0-android     UnsupportedSpecError: not PEP440 compatible
dep:maven/com.google.guava/guava@>=33.8.0-android   UnsupportedSpecError: not PEP440 compatible
dep:maven/com.google.guava/guava@>=33.8.0           accepted

The last one is accepted but no longer says Android, and Maven Central has no plain 33.8.0.

PURL isn't the limit: packageurl-python accepts pkg:maven/com.google.guava/guava@33.8.0-android.

So writing this dependency as a DepURL needs a change to PEP 725.

[ElliotGarbus]

Updated scope and worked example

@freakboy3742 @mhsmith Here is the updated scope from our discussion so far, and a worked example. None of this is built, except where I say I tested something.

Scope

v1 is intentionally small. It covers four things:

1. Native dependencies: the build tool collects them and hands them unchanged to Gradle or SwiftPM. The format is pending the PEP 725 discussion, so the examples use native coordinates.
2. Requirements: a base application_action that any tool can report, standard kinds that a tool can apply or verify (permissions first), and a reserved tool.<name>.* namespace for tool-defined kinds. The spec reserves the namespace and leaves what goes in it to each tool.
3. Features: named groups of requirements, selected by the app.
4. Acknowledgements: for requirements the tool can't check.

An action needs id, revision and description, and can add kind and feature. Its table gives the platform.

Worked example

An app uses plyer for GPS and pyadmob for ads, and builds for Android, then iOS.

Both packages are hypothetical here: plyer is real but has no such metadata, so this shows how it could adopt the spec, and pyadmob is a wrapper from my examples.

It shows how:

• an app selects a package's features, and a tool adds the permissions they need (section 1)
• a package declares native dependencies, and an app acknowledges what the tool can't check (section 2)
• an upgrade brings a changed requirement back to the author (section 3)
• a tool can define its own kind (section 4)
• a native version conflict is reported against the Python packages involved (section 5)
• iOS differs (section 6)

Assumed workflow

1. The package author declares everything in the package's pyproject.toml. A small wrapper backend copies it into the wheel's .dist-info, until this is a PEP.
2. The app developer adds the package to the app's dependencies, as usual.
3. The build tool installs the Python dependencies for the target platform and reads the metadata from each one.
4. The tool hands the native dependencies to Gradle or SwiftPM, applies what it can, and reports the rest on each build.
5. The developer acts on the report and records their answers in the app's pyproject.toml. The tool never edits that file.
6. Each later build repeats steps 3 and 4, so an upgrade that changes a requirement is reported again.

1. plyer: features and permissions

plyer calls platform APIs directly and ships no AAR, so nothing carries its permissions into the app. Its GPS and vibrator notes list what the app needs, so it could declare:

# pyproject.toml for a plyer that adopts the spec
[[tool.native-integration.android.application_action]]
id = "gps"
feature = "gps"
revision = 1
kind = "permission"
names = [
    "android.permission.ACCESS_FINE_LOCATION",
    "android.permission.ACCESS_COARSE_LOCATION",
]
description = "Declare these permissions in the manifest."

[[tool.native-integration.android.application_action]]
id = "vibrator"
feature = "vibrator"
revision = 1
kind = "permission"
names = ["android.permission.VIBRATE"]
description = "Declare this permission in the manifest."

The tool reads the feature names from the actions. Until the app has decided, the tool reports what each feature brings and a block to paste:

plyer: features not selected.
  gps: permissions ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION
  vibrator: permission VIBRATE
Add to your pyproject.toml, keeping the features you use:

[tool.native-integration.features]
plyer = ["gps", "vibrator"]

The author pastes the block and keeps what the app uses:

# The app's pyproject.toml
[tool.native-integration.features]
plyer = ["gps"]

The app didn't select vibrator, so the tool ignores that action: it doesn't add VIBRATE or ask about it.

plyer = [] means the app uses none of plyer's features. A missing entry means it hasn't decided, and only a missing entry is reported. Whether that fails the build is the tool's choice.

For the features the app selected, the tool adds the permissions and says so:

plyer (gps): added ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION

A tool that doesn't implement permission reports the description, and the author acknowledges it as in section 2. A library that uses plyer's GPS declares the permission itself, so the app author doesn't need to know how that library works.

2. pyadmob: dependencies, and what only the app can do

# pyadmob's pyproject.toml
[tool.native-integration.android.gradle]
dependencies = ["com.google.android.gms:play-services-ads:[24.0,25.0[!!24.0.0"]

[[tool.native-integration.android.application_action]]
id = "admob-app-id"
revision = 1
description = "Set the manifest meta-data com.google.android.gms.ads.APPLICATION_ID to your AdMob app ID."

The Gradle version is Gradle's own strict syntax: the range the binding supports, and the version it prefers. The tool passes it on unchanged.

pyadmob needs no permission action, because Google's AAR already declares the permissions it uses. This action has no feature, so it applies to any app using pyadmob. It has no kind, so the tool can't check it and reports it on each build until it's acknowledged:

pyadmob (admob-app-id): not acknowledged.
  Set the manifest meta-data com.google.android.gms.ads.APPLICATION_ID to your AdMob app ID.
Once that's done, add to your pyproject.toml:

[tool.native-integration.ack.pyadmob.android]
# The value is the revision of the action being acknowledged.
admob-app-id = 1

The author does the work with what the tool already provides, then pastes the block, and can add a comment:

# The app's pyproject.toml
[tool.native-integration.ack.pyadmob.android]
# The value is the revision of the action being acknowledged.
admob-app-id = 1  # Set in the AndroidManifest template.

The author's comment is for whoever maintains the app later.

3. Upgrades

If a new pyadmob changes what the action asks for, it sets revision = 2. The old acknowledgement no longer matches:

pyadmob (admob-app-id): acknowledged revision 1, now revision 2.
  <the new description>
Once that's done, update your pyproject.toml:

[tool.native-integration.ack.pyadmob.android]
# The value is the revision of the action being acknowledged.
admob-app-id = 2

The report stays until the author changes the value to 2.

4. Tool-defined kinds

A tool can define its own kinds under tool.<name>.*, so it can try something before it's standardized. For example, Briefcase could try Malcolm's insertion points with a hypothetical kind that uses its android_manifest_application_extra_content:

[[tool.native-integration.android.application_action]]
id = "sdk-flag"
revision = 1
kind = "tool.briefcase.manifest_application_content"
content = '<meta-data android:name="com.example.sdk.FLAG" android:value="true" />'
description = 'Add <meta-data android:name="com.example.sdk.FLAG" android:value="true" /> to the manifest application element.'

Briefcase could insert the content. Any other tool reports the description, and the author acknowledges it.

5. Two packages, one native dependency

The tool can give each Python distribution its own Gradle module, named after the distribution, holding only that distribution's coordinates. Gradle does all the resolving, and its errors name the distributions. I tested two modules with ranges that don't overlap:

// pkg-a/build.gradle
dependencies { api 'com.example:foobar:[1.0,2.0[!!1.4' }

// pkg-b/build.gradle
dependencies { api 'com.example:foobar:[2.0,3.0[!!2.5' }

> Could not resolve com.example:foobar:{strictly [1.0,2.0[; prefer 1.4}.
  > Cannot find a version of 'com.example:foobar' that satisfies the version constraints:
       Dependency path ':app:unspecified' --> 'app:pkg-a:unspecified' (apiElements) --> 'com.example:foobar:{strictly [1.0,2.0[; prefer 1.4}'
       Dependency path ':app:unspecified' --> 'app:pkg-b:unspecified' (apiElements) --> 'com.example:foobar:{strictly [2.0,3.0[; prefer 2.5}'

Here pkg-a and pkg-b are the Gradle modules, named after the Python packages. I wrote them by hand to stand in for what a tool would generate, and the output is shortened.

With pkg-b changed to an overlapping range, [1.2,3.0[!!1.4, the build succeeds and selects 1.4.

This was Gradle 8.11.1 with plain Java modules. I haven't tested it with the Android Gradle Plugin.

6. What's different on iOS

Actions, features, acknowledgements and revisions work the same way. A selection applies to both platforms, so plyer = ["gps"] needs no iOS entry. Two things differ.

Permissions: an iOS permission needs a purpose string, and only the app can write it. So the tool checks that the key is set rather than adding it:

# pyproject.toml for a plyer that adopts the spec
[[tool.native-integration.ios.application_action]]
id = "gps"
feature = "gps"
revision = 1
kind = "permission"
names = ["NSLocationWhenInUseUsageDescription"]
description = "Add this key to Info.plist, saying why your app uses location."

The tool prints a block for its own configuration, here kivyforge's:

plyer (gps): NSLocationWhenInUseUsageDescription is not set.
  Add this key to Info.plist, saying why your app uses location.
Add to your pyproject.toml, with your reason:

[tool.kivy.ios.info_plist]
NSLocationWhenInUseUsageDescription = "<your reason>"

Briefcase would print its permission.fine_location setting instead. Once the key is set, the tool finds it and the report clears, so there's nothing to acknowledge.

Dependencies: a Swift package names the products to link. Its from requirement already stops at the next major version, so it needs no strict syntax:

# pyadmob's pyproject.toml
[tool.native-integration.ios.swift_packages]
GoogleMobileAds = { url = "https://github.com/googleads/swift-package-manager-google-mobile-ads", requirement = { from = "12.0.0" }, products = ["GoogleMobileAds"] }

[[tool.native-integration.ios.application_action]]
id = "admob-app-id"
revision = 1
description = "Set GADApplicationIdentifier in Info.plist to your AdMob app ID."

The tool reports this action as it does on Android:

pyadmob (admob-app-id): not acknowledged.
  Set GADApplicationIdentifier in Info.plist to your AdMob app ID.
Once that's done, add to your pyproject.toml:

[tool.native-integration.ack.pyadmob.ios]
# The value is the revision of the action being acknowledged.
admob-app-id = 1

The author pastes the block once the work is done:

# The app's pyproject.toml
[tool.native-integration.ack.pyadmob.ios]
# The value is the revision of the action being acknowledged.
admob-app-id = 1  # Set in Info.plist.

Where this grows

Areas to explore during spec development:

• A kind for strings at a named key, like the AdMob ID
• Russell's importlib-metadata idea, so a package can read those values
• Malcolm's insertion points, for content a package knows completely
• Extras that select native dependencies, for a package wrapping several SDKs, as in PEP 725's [external.optional-dependencies]

Feedback

The example adds:

• The tool adds Android permissions, rather than only checking for them.
• An acknowledgement's value is the revision number.

Does this match what you had in mind, and what would you change?

[freakboy3742]

Does this match what you had in mind, and what would you change?

Thanks for that write up/example. A couple of comments and impressions on the current state:

The "Application action" bikeshed

I don't like starting with a bike shed, but I'm really not sure what the term application_action is trying to capture. It's not an intuitive representation of the problem to me at all. "Requirements" (which is how your own explanation introduced them) seems a much more intuitive naming, except for the potential confusion between "package requirements" and "integration requirements".

It's also notable that each of the "actions" that are being described are "integration features"; I can't help but thing that's a better way to categorise them.

"Acknowledgements"

Again - I'm not sure what problem this is trying to solve. The example given here - updating admob-app-id - seems like mostly pointless accounting, rather than something that would be useful in practice.

If I'm updating the version of a package that I'm using, then it's incumbent on me to be aware what that update involves. If I update from pyadmob 1.1 to 1.2, and get an error that I need to bump the admob-app-id acknowledgement, I'll do that. There won't be any confirmation that I've actually done the thing that needs to be acknowledged, so there's still going to be a need for error handling and reporting if the user hasn't done whatever the acknowledgement is trying to capture... or that I've done it correctly - so what is the extra administrative step of bumping an acknowledgement achieved, other than being a checkbox I need to fill in?

Platform Differences?

This writeup implies that iOS permissions are different - but I'm not sure they are (or need to be). The write up suggests to me that the intention with Android permissions is that the package declares a permission requirement, and the packaging tool ingests that definition and outputs it directly in Gradle form; whereas iOS will require additional handling because of the need for a description with the permission.

To me, that's more of an issue of coordination between the two halves. If an app declares it uses a package, and the package metadata declares it needs permissions, then the app packaging tool can check to see if there's a description provided in the app metadata that authorises/explains that permission, and raise a build-time error if there isn't.

There's also the question of how permission collisions are resolved. If one application declares it needs ACCESS_COARSE_LOCATION, and one declares it needs ACCESS_FINE_LOCATION - what happens? Does the app get both?

Symmetry and ergonomics in definitions

The "shape" of configuration doesn't seem quite right to me - some questions that emerged for me:

1. What is the intended difference between the id and the feature in an application_action?
2. application_action is being defined as a table; what would prevent multiple entries in the table having an id of gps?
3. How do I specify at time of usage that my Android app requires GPS, but my iOS one doesn't?
4. Is there any reason to differentiate between how permissions are handled, and how dependencies are handled? AFAICT, they should be fundamentally following the same rules - they're a (potentially feature bound) description of one or more "things" that must be true about the packaged version of an app, with variations necessary depending on the platform.

All these questions feel like they stem from the same root - there's a cardinality mismatch about what pieces are identifiers, what axes need to be selectable, what is shared between platforms, and so on. My impression is that some of that is from verbosity - fields in the spec that add heft, but not meaning. I don't have a complete counter-proposal ready to use here; but I strongly suspect there's a lot we can trim from the tables if we focus on exactly what is being declared, and why it is being declared.