Move dangling methods into class methods

ewjoachim · Mar 17, 2021 · cf6c6bb · cf6c6bb
1 parent 27b8428
commit cf6c6bb
Show file tree

Hide file tree

Showing 5 changed files with 188 additions and 129 deletions.
diff --git a/docs/howto.rst b/docs/howto.rst
@@ -2,7 +2,9 @@
 How to...
 =========
 
-This how-to section is divided into two parts:
+This how-to section is divided into two parts: user and integrator doc.
+User is for people who want to interact with their own tokens.
+Integrator is for people interested into interacting this library in Warehouse.
 
 "User" documentation: you're a PyPI user
 ========================================
@@ -74,6 +76,29 @@ if you're a PyPI admin, you can find the key which is stored in the PyPI Databas
 Practically, PyPI admins don't go around looking at the token secrets keys. Your
 Macaroon keys are safe where they are, and it's best for everyone this way.
 
+Introspect a token's restrictions
+---------------------------------
+
+`Token.restrictions` will give you a list of restriction objects. These objects
+are dataclass instances that you can compare and introspect easily.
+
+There might also be cases where you want to interact with caveat values directly,
+without a token. In this case, you can use the methods on the `Restriction` class::
+
+    import pypitoken
+    restriction = pypitoken.Restriction.load_json(
+        '{"version": 1, "permissions": "user"}'
+    )
+    # or
+    restriction = pypitoken.Restriction.load(
+        {"version": 1, "permissions": "user"}
+    )
+    # NoopRestriction()
+
+    print(restriction.dump())  # outputs a dict
+    print(restriction.dump_json())  # outputs a json-encoded string
+
+
 "Integrator" documentation: you code for PyPI itself
 ====================================================
 

diff --git a/docs/reference.rst b/docs/reference.rst
@@ -16,7 +16,7 @@ should not have to call the methods directly. Use `Token.restrict` and
 `Token.restrictions` instead.
 
 .. autoclass:: pypitoken.token.Restriction
-    :members: load_value, dump, dump_value, get_schema, extract_kwargs, check
+    :members: load, load_json, dump_json, dump, check
 
 .. autoclass:: pypitoken.NoopRestriction
     :show-inheritance:

diff --git a/pypitoken/__init__.py b/pypitoken/__init__.py
@@ -1,10 +1,14 @@
 from .exceptions import LoaderError, PyPITokenException, ValidationError
-from .token import NoopRestriction, ProjectsRestriction, Token
+from .token import NoopRestriction, ProjectsRestriction, Restriction, Token
 
 __all__ = [
+    # Main classes
     "Token",
+    "Restriction",
+    # Restriction subclasses
     "NoopRestriction",
     "ProjectsRestriction",
+    # Exceptions
     "PyPITokenException",
     "LoaderError",
     "ValidationError",