AI spam

README.md

@@ -18,6 +18,8 @@ loading a token.
 Here's how you could generate a token for transmitting a user's id and
 name between web requests.
 
+itsdangerous has two main layers: a **Signer** that HMAC-signs raw bytes to detect tampering, and a **Serializer** that wraps a Signer to let you sign arbitrary Python objects (dicts, lists, etc.) by serializing them first. Most users want the Serializer (or one of its subclasses like `URLSafeSerializer`); reach for the Signer directly only when you're already working with bytes.
+
 ```python
 from itsdangerous import URLSafeSerializer
 auth_s = URLSafeSerializer("secret key", "auth")

docs/index.rst

@@ -53,8 +53,8 @@ Table of Contents
 .. toctree::
 
     concepts
-    serializer
     signer
+    serializer
     exceptions
     timed
     url_safe

docs/serializer.rst

@@ -41,9 +41,11 @@ payload if the signature check failed. This has to be done with extra
 care because at that point you know that someone tampered with your data
 but it might be useful for debugging purposes.
 
+This example uses :class:`~itsdangerous.url_safe.URLSafeSerializer` so the token is safe to pass in a URL or cookie, but the error handling pattern is the same for any serializer class.
+
 .. code-block:: python
 
-    from itsdangerous.serializer import Serializer
+    from itsdangerous.url_safe import URLSafeSerializer
     from itsdangerous.exc import BadSignature, BadData
 
     s = URLSafeSerializer("secret-key")

docs/timed.rst

@@ -8,6 +8,8 @@ If you want to expire signatures you can use the
 signs it. On unsigning you can validate that the timestamp is not older
 than a given age.
 
+:class:`TimestampSigner` signs raw bytes and embeds a timestamp — use it when you're already working with bytes and need expiry. :class:`TimedSerializer` wraps :class:`TimestampSigner` to handle arbitrary Python objects such as dicts and lists — use it when you want to sign structured data with an expiry. In general, if you're not already working with raw bytes, reach for :class:`TimedSerializer`.
+
 .. code-block:: python
 
     from itsdangerous import TimestampSigner