A real guide, unedited

ItsDangerous: a beginner's guide

A Python library that packages data into tokens and lets you check whether anyone changed them.

Repository: github.com/pallets/itsdangerous · Commit: 672971d66a · Files analysed: 46 · Generated: 2026-10-15 14:33 UTC · Model: gpt-6-luna

Contents

1. Quick start
2. What this project does
3. Key concepts for beginners
4. Architecture & data flow
5. Module reference
6. Setup, tests, config & deploy
7. File reference
8. Glossary & FAQ
9. Caveats & omitted files

Quick start

Prerequisites

• Install Python 3.10 or newer.
• Install uv, which this repository supports for setting up the project and its development dependencies.

Set up and check the project

1. In a terminal, go to the project’s root directory—the folder containing pyproject.toml—and install the project and its configured dependencies:

   uv sync
   

2. Run the automated tests:

   uv run pytest
   

   Success means pytest finishes without reporting test failures. The project’s test configuration is in pyproject.toml.

Try the library

ItsDangerous is a Python library, not a standalone application. The following example uses the URLSafeSerializer class shown in README.md:

from itsdangerous import URLSafeSerializer

auth_s = URLSafeSerializer("secret key", "auth")
token = auth_s.dumps({"id": 5, "name": "itsdangerous"})
print(token)

data = auth_s.loads(token)
print(data["name"])

The first print outputs a signed token; its exact value can vary. The second prints:

itsdangerous

The example key is for trying the code only. Use a securely managed key for an application. A signature lets you detect changes to the data; it does not hide the data.

What this project does

ItsDangerous is a Python library for passing data through places that are not fully trusted, such as a browser, and checking the data when it comes back. It turns a value into a token with a cryptographic signature. When the token is loaded, ItsDangerous checks the signature to detect changes. A signature does not encrypt the data, so it does not hide the contents. The README shows a simple example of signing and loading a user's ID and name with URLSafeSerializer (README.md).

This is useful to Python developers who need to carry data between parts of an application, including through URLs, while being able to detect tampering. Applications can choose how data is serialized, and ItsDangerous can compress data when appropriate. It also offers timestamped tokens that can be checked for expiration.

Main parts

• Serializers turn values into signed tokens and load them after checking their signatures (src/itsdangerous/serializer.py).
• Signers provide lower-level signing and signature verification, with support for key rotation (src/itsdangerous/signer.py).
• Timed tokens add timestamps and allow expiration checks (src/itsdangerous/timed.py).
• URL-safe serializers provide tokens suitable for URLs and support compression when appropriate (src/itsdangerous/url_safe.py).
• Encoding and JSON helpers, along with the library's exceptions, support these operations (src/itsdangerous/encoding.py, src/itsdangerous/_json.py, src/itsdangerous/exc.py).
• Public imports are collected in the package's public API (src/itsdangerous/__init__.py).

How to read this guide

Start with the concepts to understand signing and tokens, then follow the topic that matches your needs: serialization, signing, timestamps, URL-safe tokens, encoding, or exceptions. The project's tests also show how different features are checked (docs/concepts.rst, docs/serializer.rst, docs/signer.rst, docs/timed.rst, docs/url_safe.rst, docs/encoding.rst, docs/exceptions.rst, tests/test_itsdangerous/test_serializer.py, tests/test_itsdangerous/test_signer.py, tests/test_itsdangerous/test_timed.py, tests/test_itsdangerous/test_url_safe.py, tests/test_itsdangerous/test_encoding.py).

Key concepts for beginners

Serialization: turning values into a portable form

Serialization means converting a Python value into a representation that can be stored or sent. For example, a dictionary can be represented as JSON text. ItsDangerous serializes data before signing it, then loads it after checking the token.

data = {"id": 5, "name": "Ada"}
token = serializer.dumps(data)
restored = serializer.loads(token)

The example shows the dumps and loads pattern used in the README. The serializer implementation is in src/itsdangerous/serializer.py; JSON support is in src/itsdangerous/_json.py.

Signatures and verification: detect changes, not hide data

A signature is a tag calculated from data and a signing key. When the token is loaded, ItsDangerous checks the signature. If the signed data has changed, the check fails. This does not encrypt the data: someone who can read the token may be able to read its contents too.

serializer = URLSafeSerializer("replace-with-your-own-key")
token = serializer.dumps({"id": 5})
data = serializer.loads(token)

The README demonstrates this flow with URLSafeSerializer. Signing and signature checks are implemented in src/itsdangerous/signer.py, and serialization ties those steps together in src/itsdangerous/serializer.py. Use a private, application-specific key in real code; the example key is only a placeholder.

Tokens: the packaged data you pass around

A token combines serialized data with its signature so an application can pass it somewhere and check it when it comes back. For instance, an application might pass a token between web requests.

token = auth_s.dumps({"id": 5, "name": "itsdangerous"})
data = auth_s.loads(token)

The README uses this pattern with a URL-safe serializer. URL-safe encoding makes the representation suitable for use in URLs; it does not make the contents secret. The URL-safe serializer behavior is in src/itsdangerous/url_safe.py.

Expiration: tokens that are valid for a limited time

A timestamped signature records when a token was created. Loading can check its age and reject it if it is older than the allowed period. This is useful for data such as a link that should stop working after a while.

TimestampSigner adds timestamp handling in src/itsdangerous/timed.py. Expiration behavior is also exercised in tests/test_itsdangerous/test_timed.py.

Key rotation: changing keys without immediately losing old tokens

Key rotation means moving to a new signing key while allowing configured older keys to verify tokens created before the change. This can help an application transition keys over time. The signer supports key-rotation behavior in src/itsdangerous/signer.py; the exact keys and options depend on how an application configures it.

Errors: handle tokens that cannot be accepted

Loading may fail when a token is invalid or its signature does not check out. ItsDangerous represents these failures with exception classes, which let Python code handle specific kinds of problems.

try:
    data = serializer.loads(token)
except BadSignature:
    data = None

BadSignature is defined alongside other token-related exceptions in src/itsdangerous/exc.py. In application code, catch only the failures you expect and decide what should happen when a token is rejected.

Architecture & data flow

flowchart TD
  n_app["Application using the library"]
  n_api["Public package API"]
  n_serializers["Serializers"]
  n_signers["Signers"]
  n_timed_url["Timed and URL-safe variants"]
  n_helpers["Encoding, JSON, and exceptions"]
  n_tests["Automated tests"]
  n_docs["User documentation"]
  n_automation["Build and release configuration"]
  n_app -->|"imports and calls"| n_api
  n_api -->|"exposes"| n_serializers
  n_serializers -->|"signs and verifies tokens"| n_signers
  n_serializers -->|"uses serialization and encodin"| n_helpers
  n_timed_url -->|"extends serializer behavior"| n_serializers
  n_timed_url -->|"uses timestamped signing"| n_signers
  n_tests -->|"checks public behavior"| n_api
  n_docs -->|"explains usage and APIs"| n_api
  n_automation -->|"configures test tasks"| n_tests
  n_automation -->|"configures documentation build"| n_docs

Main components

Applications start with the public imports in src/itsdangerous/__init__.py. For example, the README uses URLSafeSerializer directly from itsdangerous to turn a dictionary into a token and load it again (README.md).

The work is split into layers:

• Serializers in src/itsdangerous/serializer.py convert Python values to bytes and coordinate signing and loading. Keeping serialization separate from signing lets the library work with different data formats.
• Signers in src/itsdangerous/signer.py add a signature to bytes and check it when those bytes are returned. They also support key rotation: a serializer can use fallback signers to accept tokens made with older keys.
• URL-safe serializers in src/itsdangerous/url_safe.py encode payloads for use in URLs. They can compress a payload when that makes it smaller. src/itsdangerous/_json.py provides compact JSON defaults for these values.
• Timed variants in src/itsdangerous/timed.py add a timestamp and can reject a token that is too old.
• Supporting helpers and errors are in src/itsdangerous/encoding.py and src/itsdangerous/exc.py. Encoding helpers convert between bytes and URL-safe base64; exceptions such as BadData provide ways to report invalid input.

A signature detects changes; it does not conceal the payload. Treat the signing key as private, and do not put sensitive information in a token on the assumption that signing encrypts it.

Creating and loading a URL-safe token

Using URLSafeSerializer as in the README, the flow is:

1. Choose a public class and provide a key. The application imports URLSafeSerializer from itsdangerous and creates it with a signing key. The top-level module re-exports this class for convenient imports (src/itsdangerous/__init__.py).
2. Serialize the value. When the application calls dumps, the serializer turns the Python value into a payload. URL-safe variants use the mixin in src/itsdangerous/url_safe.py; compact JSON is the default format described in src/itsdangerous/_json.py.
3. Prepare the payload for a URL. The URL-safe mixin encodes the payload using URL-safe base64 and can compress it when compression reduces its size (src/itsdangerous/url_safe.py). The encoding helpers are in src/itsdangerous/encoding.py.
4. Sign the data. The serializer uses a signer to attach a signature to the serialized data. The signer is responsible for signing and verification, including support for trying older keys when configured (src/itsdangerous/signer.py).
5. Pass the token elsewhere. The application can send the resulting text through a URL or another untrusted place. The token is signed, not encrypted.
6. Verify before loading. When the application calls loads, the serializer checks the signature before treating the payload as data. The URL-safe mixin decodes the payload and decompresses it if needed, then normal deserialization recovers the value (src/itsdangerous/serializer.py, src/itsdangerous/url_safe.py).
7. Handle invalid or old tokens. If verification or loading fails, the library reports an exception rather than returning the token as trusted data (src/itsdangerous/exc.py). With timed variants, the timestamp signer also checks the token’s age (src/itsdangerous/timed.py).

Variations and project support

The same layered design supports other needs without changing the basic flow. Use Serializer for signed serialized values without the URL-specific format. Use URLSafeTimedSerializer when the token should also expire; its timestamp-aware behavior is implemented alongside the other timed signing tools in src/itsdangerous/timed.py and src/itsdangerous/url_safe.py.

The tests exercise serialization, signing, timestamps, encoding, and URL-safe behavior in tests/test_itsdangerous/test_serializer.py, tests/test_itsdangerous/test_signer.py, tests/test_itsdangerous/test_timed.py, tests/test_itsdangerous/test_encoding.py, and tests/test_itsdangerous/test_url_safe.py. This separation mirrors the code’s layers, making it easier to check each responsibility independently.

Module reference

src/itsdangerous/serializer.py — serialize values and verify tokens

This is the main starting point when an application needs to turn a Python value into a signed token and load it again. Serializer provides the main serializer interface, while its dumps and loads methods create and check tokens. The serializer signs serialized data using a signer, so loading checks the signature before returning the value. See src/itsdangerous/serializer.py · Serializer (lines 40–404), src/itsdangerous/serializer.py · Serializer.__init__ (lines 108–120), src/itsdangerous/serializer.py · _PDataSerializer.dumps (line 29), and src/itsdangerous/serializer.py · _PDataSerializer.loads (line 25).

For a simple example of using URLSafeSerializer from the public import surface, see README.md.

src/itsdangerous/signer.py — sign and verify bytes

The signer module contains the lower-level signing tools used by serializers. Its signing algorithms provide signatures and check them; the included algorithm classes include HMACAlgorithm and NoneAlgorithm. Signers also support key rotation, which lets an application accept tokens made with older keys while moving to a new key. See src/itsdangerous/signer.py · SigningAlgorithm (lines 15–28), src/itsdangerous/signer.py · SigningAlgorithm.get_signature (lines 20–22), src/itsdangerous/signer.py · SigningAlgorithm.verify_signature (lines 24–28), and src/itsdangerous/signer.py · HMACAlgorithm (lines 48–64).

src/itsdangerous/timed.py — add timestamps and expiration checks

This module builds timestamp support on top of signing. TimestampSigner adds a timestamp when signing and can check a token’s age when it is verified. This is useful when a token should stop being accepted after a chosen time. See src/itsdangerous/timed.py · TimestampSigner (lines 22–167), src/itsdangerous/timed.py · TimestampSigner.sign (lines 45–51), and src/itsdangerous/timed.py · TimestampSigner.unsign (lines 57–62).

src/itsdangerous/url_safe.py — tokens suited to URLs

URL-safe serializers use encodings suited to passing tokens through URLs. The module includes URLSafeSerializer and URLSafeTimedSerializer; the latter combines URL-safe serialization with timestamp support. The shared mixin handles payload encoding and decoding, and supports compression when appropriate. See src/itsdangerous/url_safe.py · URLSafeSerializerMixin (lines 15–69), src/itsdangerous/url_safe.py · URLSafeSerializerMixin.dump_payload (lines 55–69), src/itsdangerous/url_safe.py · URLSafeSerializerMixin.load_payload (lines 23–53), src/itsdangerous/url_safe.py · URLSafeSerializer (lines 72–76), and src/itsdangerous/url_safe.py · URLSafeTimedSerializer (lines 79–83).

src/itsdangerous/exc.py — errors for invalid tokens

The exception classes describe problems that can occur while checking or loading tokens. BadData is a base class for data-related failures; BadSignature represents an invalid signature, and BadTimeSignature and SignatureExpired cover timestamp-related failures. These exceptions connect the lower-level signing and timed-token checks to the errors an application can handle. See src/itsdangerous/exc.py · BadData (lines 7–19), src/itsdangerous/exc.py · BadSignature (lines 22–33), src/itsdangerous/exc.py · BadTimeSignature (lines 36–57), and src/itsdangerous/exc.py · SignatureExpired (lines 60–63).

src/itsdangerous/encoding.py and src/itsdangerous/_json.py — payload helpers

These modules support serialization and signing. encoding.py provides helpers for converting values to bytes, encoding and decoding base64, and converting integers to and from bytes. _json.py provides compact JSON serialization and loading. URL-safe serializers use these helpers as part of handling payloads. See src/itsdangerous/encoding.py · want_bytes (lines 11–17), src/itsdangerous/encoding.py · base64_encode (lines 20–25), src/itsdangerous/encoding.py · base64_decode (lines 28–38), and src/itsdangerous/_json.py · _CompactJSON (lines 7–18).

src/itsdangerous/__init__.py — public imports

This package file re-exports commonly used classes, helpers, and exceptions. That lets applications import supported APIs directly from itsdangerous, as shown by the example in README.md. The package also includes src/itsdangerous/py.typed, a marker file for type-checking tools.

tests/test_itsdangerous/ — automated checks

The test modules exercise the main package features: encoding, signing, serialization, timed signatures, and URL-safe serializers. For example, tests/test_itsdangerous/test_serializer.py · TestSerializer (lines 35–183) checks serializer behavior, while tests/test_itsdangerous/test_timed.py · TestTimestampSigner (lines 29–93) covers timestamp signer cases. URL-safe tests also cover the URL-safe serializer classes. See tests/test_itsdangerous/test_encoding.py, tests/test_itsdangerous/test_signer.py, and tests/test_itsdangerous/test_url_safe.py.

docs/ — user and API documentation

The Sphinx documentation explains concepts and documents the serializers, signers, timestamps, URL-safe behavior, encoding helpers, and exceptions. docs/Makefile and docs/make.bat provide documentation build commands. See docs/concepts.rst, docs/serializer.rst, docs/signer.rst, and docs/conf.py.

.github/ and .devcontainer/ — contribution and development support

GitHub templates help contributors file issues and submit pull requests. Workflow files automate checks and release publishing; for example, .github/workflows/tests.yaml runs project checks and .github/workflows/publish.yaml handles publishing. The development container setup script prepares dependencies and pre-commit hooks. See .github/pull_request_template.md, .github/ISSUE_TEMPLATE/bug-report.md, and .devcontainer/on-create-command.sh.

Project configuration and history

pyproject.toml holds project and development-tool configuration. CHANGES.rst records project changes, and LICENSE.txt contains the project license.

Setup, tests, config & deploy

Install the development environment

You need Python 3.10 or newer. The project uses uv to install the package and its development dependencies.

uv sync

The default dependency groups include tools for tests, typing checks, and pre-commit hooks. Documentation dependencies are in a separate group. To include them when syncing, run:

uv sync --group docs

The package is built with Flit, as configured in pyproject.toml. This repository is a library, not a standalone application: use it from Python code by importing its public API, for example from itsdangerous import URLSafeSerializer. See README.md for a usage example.

Run tests and checks

Run the test suite with pytest:

uv run pytest

Pytest is configured to discover tests under tests and to treat warnings as errors in pyproject.toml. The project also defines tox environments for testing supported Python versions, style checks, type checks, and documentation builds. For example, run the style environment with:

uv run tox -e style

Run the type-checking environment with:

uv run tox -e typing

Build the documentation with:

uv run tox -e docs

The documentation build treats warnings as errors and writes its output under docs/_build/dirhtml, as configured in pyproject.toml. docs/Makefile also lets you run Sphinx targets directly; SPHINXBUILD selects the Sphinx command, SOURCEDIR and BUILDDIR set the source and output directories, and SPHINXOPTS and O pass extra options.

Configuration

There are no application-specific environment variables shown in the project configuration. Applications provide signing keys and options through the Python API. For example, serializer and signer constructors accept settings such as a secret key and salt; timed serializers also support loading options such as a maximum age. See src/itsdangerous/serializer.py, src/itsdangerous/signer.py, and src/itsdangerous/timed.py for those APIs. Keep signing keys private: a signature checks whether data was changed, but does not hide the data.

For development, pyproject.toml configures pytest, Ruff, mypy, Pyright, and tox. The documentation configuration uses Sphinx; its build environment can also use SPHINXOPTS and O through docs/Makefile.

Build and release

The repository includes a GitHub Actions workflow for publishing release files when a tag is pushed: .github/workflows/publish.yaml. The available material does not describe a manual release procedure, so follow the project’s release process rather than guessing at commands.

Common setup issues

• Python is too old: The package requires Python 3.10 or newer. Select a compatible Python interpreter before running uv sync.
• A check or build command is missing: Run uv sync again to install the configured development dependencies. For documentation, include the docs group.
• Documentation build reports warnings: The tox documentation environment treats warnings as errors. Review the warning and fix its cause before rebuilding.

File reference

Every analysed file, grouped by folder, with its real functions and classes. Use it as a map when you open the code.

Repository root

• .editorconfig: Sets consistent text-file formatting rules for editors used in the repository.
• .gitignore: Lists local development files and generated artifacts that Git should not track.
• .pre-commit-config.yaml: Configures automated checks that run through pre-commit.
• .readthedocs.yaml: Configures Read the Docs to build the project documentation.
• CHANGES.rst: Records release dates and notable changes across ItsDangerous versions.
• LICENSE.txt: States the BSD 3-Clause license terms for using, modifying, and redistributing the project.
• README.md: Introduces ItsDangerous and demonstrates creating and loading a signed URL-safe token.
• pyproject.toml: Defines package metadata, build behavior, development dependencies, and tool settings for testing, typing, formatting, and documentation.

.devcontainer/

• .devcontainer/devcontainer.json: Sets up the project’s development container for Visual Studio Code.
• .devcontainer/on-create-command.sh: Sets up a development container by installing uv if needed, syncing dependencies, and installing pre-commit hooks.

.github/

• .github/pull_request_template.md: Provides contributors with a checklist and prompts for pull request descriptions.

.github/ISSUE_TEMPLATE/

• .github/ISSUE_TEMPLATE/bug-report.md: Guides users in submitting useful bug reports for ItsDangerous.
• .github/ISSUE_TEMPLATE/config.yml: Disables blank issues and directs users to community channels for questions.
• .github/ISSUE_TEMPLATE/feature-request.md: Prompts users to provide actionable details when proposing a feature.

.github/workflows/

• .github/workflows/lock.yaml: Schedules automatic locking of inactive GitHub issues, pull requests, and discussions.
• .github/workflows/pre-commit.yaml: Runs the repository’s pre-commit checks in GitHub Actions.
• .github/workflows/publish.yaml: Builds release artifacts and publishes tagged releases to GitHub and PyPI.
• .github/workflows/tests.yaml: Defines GitHub Actions jobs for running tests and type checks across supported Python environments.

docs/

• docs/Makefile: Provides Make targets that run Sphinx documentation build modes.
• docs/changes.rst: Displays the project's change history in the documentation.
• docs/concepts.rst: Explains core signing concepts and safe ways to configure ItsDangerous.
• docs/conf.py: Configures Sphinx metadata, extensions, cross-references, theme, and presentation for the documentation site.
• docs/encoding.rst: Documents the package's base64 encoding and decoding helpers.
• docs/exceptions.rst: Lists and documents the exceptions provided by ItsDangerous.
• docs/index.rst: Introduces ItsDangerous and serves as the main documentation landing page.
• docs/license.rst: Includes the project license text in the documentation.
• docs/make.bat: Provides a Windows command for building the Sphinx documentation.
• docs/serializer.rst: Documents the serializer interface for signing and verifying serialized data.
• docs/signer.rst: Documents the low-level interface for signing and verifying byte strings.
• docs/timed.rst: Documents how to create signatures that expire after a specified amount of time.
• docs/url_safe.rst: Explains how to serialize and sign values into strings suitable for contexts with limited character sets.

src/itsdangerous/

• src/itsdangerous/__init__.py: Re-exports the package's commonly used helpers, exceptions, serializers, and signing classes from the top-level namespace.
• src/itsdangerous/_json.py: Provides a compact JSON wrapper used as the default serializer for URL-safe values. Defines _CompactJSON (lines 7–18), _CompactJSON.loads (lines 11–12), _CompactJSON.dumps (lines 15–18).
• src/itsdangerous/encoding.py: Provides byte conversion, URL-safe base64 helpers, and compact integer conversion used by signing formats. Defines want_bytes (lines 11–17), base64_encode (lines 20–25), base64_decode (lines 28–38), int_to_bytes (lines 49–50), bytes_to_int (lines 53–54).
• src/itsdangerous/exc.py: Defines the exception types used to report invalid data, signatures, timestamps, and payloads. Defines BadData (lines 7–19), BadData.__init__ (lines 14–16), BadData.__str__ (lines 18–19), BadSignature (lines 22–33), BadSignature.__init__ (lines 25–33), BadTimeSignature (lines 36–57).
• src/itsdangerous/py.typed: Marks the package as providing Python type information.
• src/itsdangerous/serializer.py: Serializes Python objects into signed values and verifies and loads them back. Defines _PDataSerializer (lines 24–29), _PDataSerializer.loads (lines 25–25), _PDataSerializer.dumps (lines 29–29), is_text_serializer (lines 33–37), Serializer (lines 40–404), Serializer.__init__ (lines 108–120).
• src/itsdangerous/signer.py: Signs byte strings and verifies signatures using configurable algorithms, derived keys, and optional key rotation. Defines SigningAlgorithm (lines 15–28), SigningAlgorithm.get_signature (lines 20–22), SigningAlgorithm.verify_signature (lines 24–28), NoneAlgorithm (lines 31–37), NoneAlgorithm.get_signature (lines 36–37), _lazy_sha1 (lines 40–45).
• src/itsdangerous/timed.py: Adds timestamps and expiration checks to signatures and serialized values. Defines TimestampSigner (lines 22–167), TimestampSigner.get_timestamp (lines 29–33), TimestampSigner.timestamp_to_datetime (lines 35–43), TimestampSigner.sign (lines 45–51), TimestampSigner.unsign (lines 57–62), TimestampSigner.unsign (lines 65–70).
• src/itsdangerous/url_safe.py: Provides serializers that encode signed payloads for URLs and compress them when doing so makes them smaller. Defines URLSafeSerializerMixin (lines 15–69), URLSafeSerializerMixin.load_payload (lines 23–53), URLSafeSerializerMixin.dump_payload (lines 55–69), URLSafeSerializer (lines 72–76), URLSafeTimedSerializer (lines 79–83).

tests/test_itsdangerous/

• tests/test_itsdangerous/__init__.py: Marks the package as providing Python type information.
• tests/test_itsdangerous/test_encoding.py: Checks that encoding helper functions convert text, bytes, and integers correctly. Defines test_want_bytes (lines 12–14), test_base64 (lines 18–22), test_base64_bad (lines 25–27), test_int_bytes (lines 33–37).
• tests/test_itsdangerous/test_serializer.py: Tests serialization, signing, loading, failure reporting, and compatibility options in Serializer. Defines coerce_str (lines 21–21), coerce_str (lines 25–25), coerce_str (lines 28–32), TestSerializer (lines 35–183), TestSerializer.serializer_factory (lines 37–38), TestSerializer.serializer (lines 41–42).
• tests/test_itsdangerous/test_signer.py: Tests signature creation, verification, key derivation, custom algorithms, and key rotation in Signer. Defines _ReverseAlgorithm (lines 13–15), _ReverseAlgorithm.get_signature (lines 14–15), TestSigner (lines 18–102), TestSigner.signer_factory (lines 20–21), TestSigner.signer (lines 24–25), TestSigner.test_signer (lines 27–32).
• tests/test_itsdangerous/test_timed.py: Tests timestamped signatures and serializers, including expiration and malformed timestamp handling. Defines FreezeMixin (lines 18–26), FreezeMixin.ts (lines 20–21), FreezeMixin.freeze (lines 24–26), TestTimestampSigner (lines 29–93), TestTimestampSigner.signer_factory (lines 31–32), TestTimestampSigner.test_max_age (lines 34–43).
• tests/test_itsdangerous/test_url_safe.py: Runs shared serializer tests against the URL-safe serializer classes. Defines TestURLSafeSerializer (lines 11–18), TestURLSafeSerializer.serializer_factory (lines 13–14), TestURLSafeSerializer.value (lines 17–18), TestURLSafeTimedSerializer (lines 21–24), TestURLSafeTimedSerializer.serializer_factory (lines 23–24).

Glossary & FAQ

Glossary

• Compression — Reducing the size of serialized data when the URL-safe serializer can do so; see src/itsdangerous/url_safe.py.
• Expiration — A rule that rejects a timed token after the allowed period; see src/itsdangerous/timed.py.
• Key rotation — Changing signing keys while keeping fallback keys available to verify older tokens; see src/itsdangerous/signer.py.
• Serialization — Turning a Python value, such as a dictionary, into a form that can be stored or sent; see src/itsdangerous/serializer.py.
• Signature — A value calculated from data and a signing key. Checking it helps detect changes to the signed data; see src/itsdangerous/signer.py.
• Token — Serialized data packaged with a signature so an application can pass it around; see src/itsdangerous/serializer.py.
• URL-safe encoding — Representing data with characters suitable for use in URLs; see src/itsdangerous/url_safe.py.
• Verification — Checking a token's signature before accepting its contents; see src/itsdangerous/serializer.py.
• pytest — The test framework used for the project's automated tests; see pyproject.toml.

FAQ

Where should I start reading?

Start with the example in README.md to see a serializer used to create and load a token. For an explanation of the ideas behind the library, read docs/concepts.rst.

Where can I find the classes applications import?

The package's public imports are collected in src/itsdangerous/__init__.py. The README example imports URLSafeSerializer from itsdangerous.

How do I create and load a token?

Use a serializer's Python API. The README shows URLSafeSerializer with dumps to create a token and loads to load it: README.md. The serializer implementation is in src/itsdangerous/serializer.py.

How do I make tokens expire?

Use the timed-token functionality described in docs/timed.rst and implemented in src/itsdangerous/timed.py.

How do I add or change a feature?

First find the relevant implementation: for example, signing is in src/itsdangerous/signer.py, and URL-safe serialization is in src/itsdangerous/url_safe.py. Add or update the matching tests under tests/test_itsdangerous/. The existing test files include tests/test_itsdangerous/test_signer.py and tests/test_itsdangerous/test_url_safe.py. The project also provides a feature-request template at .github/ISSUE_TEMPLATE/feature-request.md.

How do I run the tests?

Install the configured development dependencies with uv sync, then run uv run pytest. The project configuration is in pyproject.toml.

How can I debug a failing test?

Run the relevant test file with pytest, such as uv run pytest tests/test_itsdangerous/test_serializer.py. Check the failure against the related implementation, such as src/itsdangerous/serializer.py. For exceptions raised while loading or verifying tokens, see src/itsdangerous/exc.py.

Where does configuration live?

Signing keys and options are supplied through the library's Python APIs. Development and packaging configuration lives in pyproject.toml; the repository material does not show application-specific environment variables.

How do I build the documentation?

Documentation sources are in docs/. The Sphinx settings are in docs/conf.py, and the documentation build commands are defined in docs/Makefile.

Caveats & omitted files

This document was generated automatically from the code at commit 672971d66a2e. Its grounding score measures structure and grounding (real paths, real symbols, resolvable citations), not factual correctness. Check important details in the code.

How strongly names were checked

• Exact (parsed with Python's ast): Python (15 files).
• Not indexed: Shell (1 files), Make (1 files). Names in these files were checked against the raw repository text only.

Omitted files