PyPIToken: Manipulate PyPI API tokens#
PyPIToken is an open-source Python 3.7+ library for generating and manipulating PyPI tokens.
PyPI tokens are very powerful, as that they are based on Macaroons. They allow the bearer to add additional restrictions to an existing token. For example, given a PyPI token that can upload releases for any project of its owner, you can generate a token that will only allow some projects, or even a single one.
Here’s an example:
$ pip install pypitoken
import pypitoken token = pypitoken.Token.load("pypi-foobartoken") print(token.restrictions) # [ProjectIDsRestriction(project_ids=["00000000-0000-0000-0000-000000000000"])] token.restrict(project_names=["requests"]) print(token.restrictions) # [ # ProjectIDsRestriction(project_ids=["00000000-0000-0000-0000-000000000000"]), # ProjectNamesRestriction(project_names=["requests"]), # ] token.dump() # pypi-newfoobartoken
This token we’ve created above will be restricted to uploading releases of
Of course, your PyPI user will still need to have upload permissions on
for this to happen.
The aim of this library is to provide a simple toolbelt for manipulating PyPI tokens. Ideally, someday, PyPI (Warehouse) itself may generate their tokens using this library too. This should make it easier to iterate on new kinds of restrictions for PyPI tokens, such as those discussed in the original implementation issue.
A discussion for integrating this library to the Warehouse environment is ongoing:
In the Python Packaging discussions for putting the project under the PyPA umbrella
In the Warehouse tracker for replacing the current macaroon implementation with this lib
This documentation is mainly split into four parts:
A tutorial guide, for a complete hands-on approach to restricting existing tokens
How-to recipes, if you need something specific done
Discussions, if you want to understand how it works beneath the surface
Reference guide, to ease integration into your own code
- How to…
- What is a macaroon, how does it work, how is it secure?
- How are macaroons implemented in this library?
- How are macaroons implemented in PyPI?
- Do we really need an abstraction layer over PyMacaroons?
- Can we add new restrictions?
- Is this library a part of PyPI?
- Why is there a noop restriction?
- What does “normalized name” mean?
- What would be good practice regarding token restrictions and traceability
- All this talking about Macaroons, I’m hungry now!
- Nice logo! Where did you get it?
- API Reference