From 56a50e636db0ddd85e28402193f2acd4afe68e08 Mon Sep 17 00:00:00 2001
From: Nicholas Pipitone <npip99@gmail.com>
Date: Wed, 27 May 2026 19:30:45 +0000
Subject: [PATCH] docs: improve signer/serializer orientation and fix broken
 import

- docs/index.rst: swap signer and serializer in toctree so signer comes first
- README.md: add framing paragraph before the URLSafeSerializer example explaining the Signer/Serializer layering
- docs/serializer.rst: fix missing URLSafeSerializer import in 'Responding to Failure' code block; also fix import path to use itsdangerous.url_safe; add prose note explaining why URLSafeSerializer is used there
- docs/timed.rst: add orientation paragraph before the code example distinguishing TimestampSigner (bytes + expiry) from TimedSerializer (objects + expiry)
---
 README.md           | 2 ++
 docs/index.rst      | 2 +-
 docs/serializer.rst | 4 +++-
 docs/timed.rst      | 2 ++
 4 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 528236d7..a32cc381 100644
--- a/README.md
+++ b/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")
diff --git a/docs/index.rst b/docs/index.rst
index 95b14d4b..82fa033a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -53,8 +53,8 @@ Table of Contents
 .. toctree::
 
     concepts
-    serializer
     signer
+    serializer
     exceptions
     timed
     url_safe
diff --git a/docs/serializer.rst b/docs/serializer.rst
index af5e6f12..4ebcee96 100644
--- a/docs/serializer.rst
+++ b/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")
diff --git a/docs/timed.rst b/docs/timed.rst
index 9890f6be..97687cdf 100644
--- a/docs/timed.rst
+++ b/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