Idea: allow callers to (slightly) customize twine's user-agent?

[woodruffw]

Is there an existing issue for this?

• I have searched the existing issues (open and closed), and could not find an existing issue

What keywords did you use to search existing issues?

user agent

Please describe the problem you are attempting to solve with this request

TL;DR: It would be nice to be able to augment twine's user-agent in a controlled, limited way so that PyPI and other indices can see adoption curves on things like gh-action-pypi-publish.

Python uploading clients like twine use linehaul to provide useful metadata to PyPI via their User-Agent headers. For example, twine already does this here:

twine/twine/utils.py

Lines 332 to 337 in 54b9f22

	s.headers["User-Agent"] = (
	user_agent.UserAgentBuilder("twine", twine.__version__)
	.include_implementation()
	.build()
	)
	return s

(as do other major uploading clients, e.g. poetry, uv, maturin, etc.)

Uploading tools (and especially twine) are generally wrapped/nested inside of other tools or frameworks. For example, the pypa/gh-action-pypi-publish action is widely used and wraps twine to perform uploads.

It would be nice, on the ecosystem level, to know about these integrations and their adoption curves, similarly to how the ecosystem has insight into the uploading tools themselves!

How do you think we should solve this?

My first thought for addressing this is to add a TWINE_USER_AGENT_QUALIFIER environment variable. This variable would be optional, and could be set by the user (integrator in this case).

The value could be limited in various reasonable ways, e.g. could be limited to UTF-8, fewer than 64 (or whatever) bytes, must be in the form component/version, etc.

When present, twine's user agent would go from:

twine/6.1.0 CPython/3.13.7

to (for example):

twine/6.1.0 CPython/3.13.7 (gh-action-pypi-publish/v1.13.0)

Anything else you'd like to mention?

An alternative to the above would be to move away from plain text user agent, and towards a JSON user agent encoding. For example, pip and uv both use a <TOOL> <JSON> convention that linehaul knows about, e.g. here:

https://github.com/pypi/linehaul-cloud-function/blob/8b8ed9db4ed946722d011c7d5ffe08a03ab5f942/linehaul/ua/parser.py#L39-L56

Separately, making this kind of change will probably require some degree of changes to linehaul and other consumers of Python packaging user agent metadata since the current linehaul parser for twine doesn't expect a trailing segment after the implementation segment:

https://github.com/pypi/linehaul-cloud-function/blob/8b8ed9db4ed946722d011c7d5ffe08a03ab5f942/linehaul/ua/parser.py#L189-L197

Finally, an alternative to all of the above would be to let users fully override twine's user-agent, e.g. with a TWINE_USER_AGENT variable. However, given that the goal of linehaul is to produce more structured information to help PyPI/Python packaging, I think this wouldn't be super helpful. But I could be underthinking that.

[sigmavirus24]

Environment variables are my least favorite way to do this. I know they're useful in some situations though,so I'm not saying "no".

If we had a way of doing a hidden CLI parameter would that be acceptable?

Separately, what if we did this through plugins? Would that barrier be too high for integrators like this? It could be as simple as having a string in the metadata for usage rather than real code we'd have to call or anything (or it could simply be a function we call to get the value).

Basically,I want to avoid folks calling twine themselves from being able to too easily break the value from line haul, etc.

[woodruffw]

Environment variables are my least favorite way to do this.

That's fair; they're low-complexity to add but I agree that they have significant drawbacks.

I think doing this through a hidden CLI flag or a plugin would work equally well! My first preference would be a hidden flag over a plugin because I suspect it would be easier to integrate, but I'd be happy to implement either approach.