A real beginner's guide

ItsDangerous: a beginner's guide

ItsDangerous helps applications send data in a token and check that nobody changed it.

Repository: github.com/pallets/itsdangerous · Commit: 672971d66a · Files analysed: 46 · Generated: 2026-11-10 15:49 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

In short: Install Python and uv, set up the project’s test dependencies, then run the tests or try a short Python example. There is no server or command-line application to start.

Prerequisites

• Install Python 3.10 or newer.
• Install uv, which manages the project’s development environment.

Set up the project

1. In a terminal, go to the project directory—the directory containing pyproject.toml.

2. Install the test dependencies:

   uv sync --group tests
   

   This prepares the project’s environment with the dependencies needed to run its tests.

3. Run the tests:

   uv run pytest
   

   Success means pytest finishes without reporting test failures. The test configuration points pytest at tests in pyproject.toml.

Try the package

ItsDangerous is a Python package, so you use it by importing its classes in Python code. The README shows a small example that signs a dictionary and then loads it:

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 final line prints:

itsdangerous

The token’s signature lets the application detect changes; it does not hide the data. Use an appropriate secret key for your application rather than copying the example key. The example uses URLSafeSerializer, which is exposed through the package’s public API in src/itsdangerous/__init__.py; the same example appears in README.md.

What this project does

In short: This section explains how ItsDangerous helps Python applications detect changes to data sent in a signed token. It also describes the main features and how to use the rest of this guide.

The problem it solves

Applications sometimes need to send data between requests or through an environment they do not control, then use that data later. If someone changes the data along the way, the application needs a way to detect that before trusting it.

ItsDangerous turns data into a token with a cryptographic signature. When an application loads the token, it can check the signature to find out whether the data has been changed. Signing does not hide the data: anyone who can read the token may be able to see its contents. The README shows a URL-safe serializer being used to pass a user's ID and name between requests (README.md).

Who it is for

ItsDangerous is for Python developers who need to carry data in a token and verify that it has not been tampered with before using it. An application provides the secret key used for signing. That key is important: the signature lets the application check the data, but it does not replace careful handling of sensitive information.

Main features

• Sign and verify data. The signing tools create and check signatures, and support configurable algorithms and key rotation (src/itsdangerous/signer.py).
• Serialize values. Serializers turn values into signed tokens and check their signatures when loading them (src/itsdangerous/serializer.py).
• Use URL-safe formats. URL-safe serializers provide token formats suitable for use in URLs and can compress data when appropriate (src/itsdangerous/url_safe.py).
• Check token age. Timestamped tokens let an application check how old a token is and reject it when it has expired (src/itsdangerous/timed.py).
• Choose and customize serialized data. The package supports different ways to serialize data before signing it (README.md).

ItsDangerous provides building blocks for an application; it is not a web server or a complete login or authorization system. The application decides what data to put in a token, where to send it, and how to use it after verification.

How to read this guide

Start with the sections that match what you need: serialization for turning values into tokens, signing for signatures and keys, timestamped tokens for age checks, or URL-safe formats for tokens used in URLs. The package’s public imports are exposed in src/itsdangerous/__init__.py; the relevant modules and the tests can help you explore how each feature works.

Key concepts for beginners

In short: This section explains how ItsDangerous turns Python data into tokens and checks them later. It also covers signatures, timestamps, encoding, and the errors you may need to handle.

Data becomes a token

Serialization means converting a Python value into a form that can be stored or sent, then converting it back later. ItsDangerous serializers handle this conversion, and the signer protects the serialized data from undetected changes. The dumps and loads methods provide the basic write-and-read pattern (src/itsdangerous/serializer.py · Serializer (lines 40–404), README.md).

from itsdangerous import URLSafeSerializer

serializer = URLSafeSerializer("secret key")
token = serializer.dumps({"id": 5})
data = serializer.loads(token)

Here, token is a string containing the serialized data and its signature. Calling loads checks the signature before returning the data. The README shows this pattern with a dictionary (README.md).

Signatures detect changes; they do not hide data

A signature is calculated using data and a secret key. Checking the signature helps detect whether the data was changed. It does not encrypt the data, so a signature is not a way to keep its contents private (src/itsdangerous/signer.py · HMACAlgorithm (lines 48–64), src/itsdangerous/signer.py · SigningAlgorithm.verify_signature (lines 24–28)).

A secret key is supplied by the application when it creates a signer or serializer. Keep it private: someone who knows it could create valid signatures (src/itsdangerous/serializer.py · Serializer.__init__ (lines 108–120)).

from itsdangerous import URLSafeSerializer

serializer = URLSafeSerializer("keep-this-private")
token = serializer.dumps({"role": "reader"})

Base64 encoding, which represents bytes as text, is also not encryption. It changes how data is represented, not whether it can be read (src/itsdangerous/encoding.py · base64_encode (lines 20–25)).

Timestamps and expiration

A timestamped token includes a time value. An application can set a maximum age in seconds and reject a token that is too old. TimestampSigner handles timestamps and age checks; its timestamp conversion method returns a UTC-aware datetime (src/itsdangerous/timed.py · TimestampSigner (lines 22–167)).

from itsdangerous import TimestampSigner

signer = TimestampSigner("secret key")
token = signer.sign(b"hello")
data = signer.unsign(token, max_age=60)

The example signs bytes and checks that the token is no more than 60 seconds old. Tests freeze the clock to make timestamp-related checks repeatable (tests/test_itsdangerous/test_timed.py).

URL-safe encoding and compression

URL-safe encoding represents data using characters suitable for URLs. ItsDangerous provides URL-safe serializer formats, and its URL-safe payload handling can also support compression (src/itsdangerous/url_safe.py · URLSafeSerializerMixin (lines 15–69), src/itsdangerous/url_safe.py · URLSafeSerializerMixin.dump_payload (lines 55–69)).

from itsdangerous import URLSafeSerializer

serializer = URLSafeSerializer("secret key")
token = serializer.dumps({"page": "home"})

The returned token is intended for a URL-safe format. Encoding does not make the contents secret.

Key rotation and verification

Key rotation means changing the key used to sign data while allowing verification with more than one key during a transition. The signer supports configurable signing and verification behavior (src/itsdangerous/signer.py · SigningAlgorithm (lines 15–28)). This helps applications move to a new key without immediately invalidating every token made with an older key.

Handling invalid tokens

When verification fails, ItsDangerous uses exceptions to report problems. BadSignature is a kind of BadData, so catching the parent BadData can also catch related data errors (src/itsdangerous/exc.py · BadData (lines 7–19), src/itsdangerous/exc.py · BadSignature (lines 22–33)). Timestamp checks can raise SignatureExpired when a token is too old (src/itsdangerous/exc.py · SignatureExpired (lines 60–63)).

from itsdangerous import BadData

try:
    data = serializer.loads(token)
except BadData:
    # Do not use data from an invalid token.
    pass

Handle these errors where your application decides what to do with invalid or expired tokens.

Architecture & data flow

flowchart TB
  accTitle: Building blocks of ItsDangerous
  subgraph g_core_package["Core package"]
    n_api["Public Python API"]
    n_serializer["Serialization"]
    n_signer["Signing"]
    n_encoding["Encoding helpers"]
  end
  subgraph g_token_formats["Token formats"]
    n_timed["Timestamped tokens"]
    n_url["URL-safe tokens"]
  end
  subgraph g_quality["Quality"]
    n_tests["Automated tests"]
  end
  subgraph g_project_support["Project support"]
    n_docs["Documentation"]
    n_config["Project configuration"]
    n_ci["GitHub workflows"]
  end
  n_app(["Application code"])
  n_app -->|"imports package"| n_api
  n_api -->|"exports classes"| n_serializer
  n_api -->|"exports classes"| n_signer
  n_api -->|"exports classes"| n_timed
  n_api -->|"exports classes"| n_url
  n_serializer -->|"signs tokens"| n_signer
  n_timed -->|"signs timestamps"| n_signer
  n_url -->|"serializes values"| n_serializer
  n_url -->|"encodes tokens"| n_encoding
  n_tests -->|"checks behavior"| n_api
  n_docs -->|"explains usage"| n_api
  n_config -->|"configures tests"| n_tests
  n_config -->|"configures builds"| n_docs
  n_ci -->|"runs checks"| n_tests
  n_ci -->|"publishes package"| n_api
  class n_app external
  class n_api interface
  class n_serializer,n_signer,n_timed,n_url,n_encoding component
  class n_tests tests
  class n_docs docs
  class n_config config
  class n_ci tooling
  %% path n_api src/itsdangerous/__init__.py
  %% tech n_api Python module
  %% path n_serializer src/itsdangerous/serializer.py
  %% tech n_serializer Python module
  %% path n_signer src/itsdangerous/signer.py
  %% tech n_signer Python module
  %% path n_timed src/itsdangerous/timed.py
  %% tech n_timed Python module
  %% path n_url src/itsdangerous/url_safe.py
  %% tech n_url Python module
  %% path n_encoding src/itsdangerous/encoding.py
  %% tech n_encoding Python module
  %% path n_tests tests/test_itsdangerous/
  %% tech n_tests pytest tests
  %% path n_docs docs/
  %% tech n_docs Sphinx docs
  %% path n_config pyproject.toml
  %% tech n_config Python project manifest
  %% path n_ci .github/workflows/
  %% tech n_ci GitHub Actions
  %% via n_api n_serializer imports
  %% via n_api n_signer imports
  %% via n_api n_timed imports
  %% via n_api n_url imports
  %% via n_serializer n_signer imports
  %% via n_timed n_signer imports
  %% via n_url n_serializer imports
  %% via n_url n_encoding imports

In short: This section follows a value from application code into a signed token and back again. It also shows where URL-safe formatting, expiration checks, and verification errors fit.

Main components

Applications use the public names re-exported by src/itsdangerous/__init__.py. There is no server or command-line entry point: the application creates a serializer or signer and supplies a secret key.

• src/itsdangerous/serializer.py connects data conversion to signing. A serializer turns a Python value into a payload, signs it, and checks the signature before loading the value again.
• src/itsdangerous/signer.py handles signatures for byte strings. Its configurable signing algorithms and support for multiple keys allow an application to change signing settings or rotate keys.
• src/itsdangerous/url_safe.py adds URL-friendly payload encoding and optional compression. src/itsdangerous/_json.py provides compact JSON for URL-safe serializers.
• src/itsdangerous/timed.py adds timestamps and checks token age when loading. This is useful when an application wants tokens to expire.
• src/itsdangerous/encoding.py supplies byte, URL-safe base64, and integer conversion helpers used by the package. src/itsdangerous/exc.py defines shared exceptions for invalid data and verification failures.

These layers keep separate jobs separate: serializers handle Python values, signers handle signatures, and specialized formats add URL or time behavior. Signing detects changes; it does not conceal the data.

Creating and loading a URL-safe token

The README’s example uses URLSafeSerializer to pass a dictionary between requests (README.md):

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

data = auth_s.loads(token)

The flow is:

1. The application imports URLSafeSerializer through src/itsdangerous/__init__.py, then creates it with a secret key and a salt.
2. dumps serializes the dictionary. URL-safe serializers use compact JSON by default, and the URL-safe mixin can compress a payload when compression makes it smaller (src/itsdangerous/url_safe.py, src/itsdangerous/_json.py).
3. The serializer passes the payload to signing logic. The signer creates a signature and appends it to the value; encoding helpers support conversions and URL-safe base64 (src/itsdangerous/serializer.py, src/itsdangerous/signer.py, src/itsdangerous/encoding.py).
4. When the application calls loads, the URL-safe serializer decodes the payload, decompressing it if it was marked as compressed. The serializer checks the signature before returning the decoded value. If verification fails, the package reports an exception from its shared hierarchy (src/itsdangerous/url_safe.py, src/itsdangerous/serializer.py, src/itsdangerous/exc.py).

Adding an expiration check

For tokens that should stop being accepted after a period of time, an application can use a timed serializer. Its timestamp-aware signer adds a timestamp when signing and checks the token’s age when it is loaded. Loading can reject expired or future-dated signatures (src/itsdangerous/timed.py). URL-safe timed tokens combine this behavior with URL-safe formatting (src/itsdangerous/url_safe.py).

The tests exercise these separate responsibilities: serializer round trips and signature checks, signer behavior and key rotation, and timestamp and expiration handling (tests/test_itsdangerous/test_serializer.py, tests/test_itsdangerous/test_signer.py, tests/test_itsdangerous/test_timed.py).

Module reference

In short: This section maps the main package modules and explains how they work together. It also points to the tests and project files that support the code.

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

The serializer turns Python values into tokens and loads them back after checking their signatures. Serializer is the main class; its dumps and loads methods handle creating and reading tokens. Its loading path relies on signer classes to verify the token before the serialized value is used. The module also defines _PDataSerializer and is_text_serializer for serialization-related handling. README.md shows a basic URLSafeSerializer example that creates a token and loads it back.

The serializer’s tests exercise round trips, signature checks, error handling, and file-like inputs. TestSerializer provides shared serializer test behavior. src/itsdangerous/url_safe.py and src/itsdangerous/timed.py build on the same general serialization use case with URL-safe formatting and timestamps.
Sources: src/itsdangerous/serializer.py · Serializer (lines 40–404), src/itsdangerous/serializer.py · _PDataSerializer (lines 24–29), src/itsdangerous/serializer.py · is_text_serializer (lines 33–37), tests/test_itsdangerous/test_serializer.py · TestSerializer (lines 35–183), README.md

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

A signer adds a signature to data and checks that signature later. This is what lets a caller detect tampering; it does not conceal the data. The module provides SigningAlgorithm as an interface for signing behavior, along with HMACAlgorithm and NoneAlgorithm. Signer configuration also supports key rotation, so applications can work with more than one signing key during a transition.

Serializers use signer classes to protect their payloads. Tests cover signer configuration, algorithms, and altered signatures; _ReverseAlgorithm is a test-specific algorithm implementation.
Sources: src/itsdangerous/signer.py · SigningAlgorithm (lines 15–28), src/itsdangerous/signer.py · HMACAlgorithm (lines 48–64), src/itsdangerous/signer.py · NoneAlgorithm (lines 31–37), tests/test_itsdangerous/test_signer.py · TestSigner (lines 18–102), tests/test_itsdangerous/test_signer.py · _ReverseAlgorithm (lines 13–15)

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

TimestampSigner adds a timestamp to signed data. When loading or validating a timestamped signature, it can check the token’s age and reject tokens outside an allowed age. This module provides the signing and verification layer for timestamp-aware serializers.

The timed tests use FreezeMixin to control time while checking behavior such as maximum age and missing timestamps.
Sources: src/itsdangerous/timed.py · TimestampSigner (lines 22–167), src/itsdangerous/timed.py · TimestampSigner.sign (lines 45–51), src/itsdangerous/timed.py · TimestampSigner.unsign (lines 57–62), tests/test_itsdangerous/test_timed.py · FreezeMixin (lines 18–26), tests/test_itsdangerous/test_timed.py · TestTimestampSigner (lines 29–93)

src/itsdangerous/url_safe.py — URL-safe token formats

This module supplies URL-safe serializer classes. URLSafeSerializerMixin handles payload encoding and decoding, and supports optional compression. URLSafeSerializer provides the regular URL-safe format; URLSafeTimedSerializer combines URL-safe serialization with timestamp checks.

The URL-safe tests reuse serializer test behavior and cover both URL-safe serializer classes, including compressed values.
Sources: src/itsdangerous/url_safe.py · URLSafeSerializerMixin (lines 15–69), src/itsdangerous/url_safe.py · URLSafeSerializer (lines 72–76), src/itsdangerous/url_safe.py · URLSafeTimedSerializer (lines 79–83), tests/test_itsdangerous/test_url_safe.py · TestURLSafeSerializer (lines 11–18), tests/test_itsdangerous/test_url_safe.py · TestURLSafeTimedSerializer (lines 21–24)

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

The shared exception hierarchy gives callers a way to handle problems with data and signatures. BadData is the base for bad input, BadSignature represents signature failures, and BadTimeSignature and SignatureExpired cover timestamp-related failures. Other modules use these exceptions to report verification or loading problems.
Sources: src/itsdangerous/exc.py · BadData (lines 7–19), src/itsdangerous/exc.py · BadSignature (lines 22–33), src/itsdangerous/exc.py · BadTimeSignature (lines 36–57), src/itsdangerous/exc.py · SignatureExpired (lines 60–63)

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

encoding.py contains shared conversions used across the package: want_bytes handles byte conversion, the base64 helpers encode and decode data, and the integer helpers convert between integers and bytes. _json.py provides _CompactJSON, a compact JSON implementation used for serialized payloads. These utilities support the higher-level serializer and signer modules.
Sources: 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), src/itsdangerous/encoding.py · int_to_bytes (lines 49–50), src/itsdangerous/encoding.py · bytes_to_int (lines 53–54), src/itsdangerous/_json.py · _CompactJSON (lines 7–18)

src/itsdangerous/__init__.py — public imports

Applications can import the package’s main classes and exceptions from this top-level module instead of locating each implementation module. For example, the README.md uses from itsdangerous import URLSafeSerializer. The py.typed marker indicates that the package includes type information for type-checking tools.
Sources: src/itsdangerous/__init__.py, src/itsdangerous/py.typed, README.md

tests/test_itsdangerous/ — behavior checks

The tests correspond to the package’s main areas: encoding, serialization, signing, timestamp handling, and URL-safe formats. The shared test setup is in tests/test_itsdangerous/__init__.py. Together, the tests check normal use as well as cases such as altered data and invalid signatures.
Sources: tests/test_itsdangerous/__init__.py, tests/test_itsdangerous/test_encoding.py, 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

Project and documentation files

pyproject.toml holds Python project configuration, including package and development-tool settings. The docs/ files explain usage, APIs, and security concepts; docs/conf.py configures Sphinx, and docs/Makefile provides documentation build targets. These files support development and learning, while the implementation modules above provide the package behavior.
Sources: pyproject.toml, docs/conf.py, docs/Makefile, docs/index.rst, docs/concepts.rst, docs/serializer.rst, docs/signer.rst, docs/timed.rst, docs/url_safe.rst, docs/encoding.rst, docs/exceptions.rst

Setup, tests, config & deploy

In short: Install the project’s development dependencies with uv, then run the test suite with pytest. This section also covers the project’s settings, documentation build, and release process.

Install the project

You need Python 3.10 or newer and uv. From the project directory, install the test dependencies with:

uv sync --group tests

The project is a Python package, not a server or command-line application. To try it, import its classes in Python code. For example, the README creates a URL-safe serializer, signs a value, and loads it again:

from itsdangerous import URLSafeSerializer

serializer = URLSafeSerializer("secret key", "auth")
token = serializer.dumps({"id": 5, "name": "itsdangerous"})
data = serializer.loads(token)

Run tests and other checks

Run the automated tests with:

uv run pytest

Pytest is configured to look for tests under tests, and to treat warnings as errors. The project also defines tox environments for running tests on its configured Python versions, checking style and types, and building documentation. These tasks are configured in pyproject.toml.

Configuration

No required environment variables are shown in the provided project settings. Applications supply signing key material when creating a signer or serializer. Keep that key private: signing detects changes to a token but does not hide its contents. For example, the README passes a key directly to URLSafeSerializer in README.md.

The project’s pyproject.toml contains package metadata, dependency groups, and tool settings. Its development dependencies are grouped for tests, docs, typing, and other tasks. The project uses Flit to build the package, and requires Python 3.10 or newer.

Build the documentation

The documentation build is available through Sphinx. With the docs dependencies installed, you can build the HTML docs using:

uv run sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml

This is the command configured for the docs tox environment in pyproject.toml. The docs/Makefile also provides a generic Sphinx wrapper: for example, make html runs the Sphinx html build target. Its defaults set the source directory to . and the output directory to _build; SPHINXBUILD, SPHINXOPTS, and O can adjust the command.

Release and common fixes

The release workflow builds and publishes the package when a Git tag is pushed. It uses a PyPI publishing environment; the repository material does not specify a manual publishing command. See .github/workflows/publish.yaml.

If a command cannot find uv, install it and make sure it is available on your shell’s PATH. If imports fail because dependencies are missing, run the install command above from the project directory. If the docs build fails because Sphinx is unavailable, install the docs dependency group before building.

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 formatting defaults for editors working in the repository.
• .gitignore: Lists local development and generated files that Git should not track.
• .pre-commit-config.yaml: Configures automated checks that run through pre-commit.
• .readthedocs.yaml: Configures the Read the Docs environment and command for building the documentation.
• CHANGES.rst: Records the project’s release history and user-visible changes across versions.
• LICENSE.txt: States the BSD 3-Clause license terms governing use and redistribution of the project.
• README.md: Introduces ItsDangerous and shows a basic example of creating and loading a signed token.
• pyproject.toml: Defines package metadata, build settings, development dependencies, and tool configurations for ItsDangerous.

.devcontainer/

• .devcontainer/devcontainer.json: Configures a development container for working on the repository in VS Code.
• .devcontainer/on-create-command.sh: Sets up the development container by installing uv if needed, syncing dependencies, and installing pre-commit hooks.

.github/

• .github/pull_request_template.md: Provides a checklist and prompts for contributors opening pull requests.

.github/ISSUE_TEMPLATE/

• .github/ISSUE_TEMPLATE/bug-report.md: Provides prompts for filing a bug report about ItsDangerous.
• .github/ISSUE_TEMPLATE/config.yml: Configures the issue chooser and directs questions to community support channels.
• .github/ISSUE_TEMPLATE/feature-request.md: Provides prompts for suggesting a new ItsDangerous feature.

.github/workflows/

• .github/workflows/lock.yaml: Schedules automatic locking of inactive, already-closed GitHub discussions, issues, and pull requests.
• .github/workflows/pre-commit.yaml: Runs the repository's pre-commit checks in GitHub Actions.
• .github/workflows/publish.yaml: Builds release artifacts and publishes a tagged ItsDangerous release.
• .github/workflows/tests.yaml: Defines GitHub Actions workflows for running the test suite and type checks.

docs/

• docs/Makefile: Provides Make targets that invoke Sphinx to build or inspect the project documentation.
• docs/changes.rst: Includes the project change log in the documentation.
• docs/concepts.rst: Explains the main security concepts and configuration choices behind ItsDangerous signing.
• docs/conf.py: Configures Sphinx metadata, extensions, cross-references, theme, and presentation for the project documentation.
• docs/encoding.rst: Documents the package's Base64 encoding and decoding utilities.
• docs/exceptions.rst: Lists and documents the public exceptions raised by ItsDangerous.
• docs/index.rst: Introduces ItsDangerous and serves as the main documentation landing page.
• docs/license.rst: Displays the project's BSD-3-Clause license in the documentation.
• docs/make.bat: Provides a Windows command script for building the Sphinx documentation.
• docs/serializer.rst: Documents how to serialize data, sign it, and respond to serializer failures.
• docs/signer.rst: Documents the basic interface for attaching and checking signatures on byte strings.
• docs/timed.rst: Documents how to create signatures with timestamps and reject signatures that are too old.
• docs/url_safe.rst: Documents serializers that encode signed values into strings suitable for URL-safe contexts.

src/itsdangerous/

• src/itsdangerous/__init__.py: Re-exports the package’s main helpers, exception classes, signers, and serializers from the top-level itsdangerous namespace.
• src/itsdangerous/_json.py: Provides compact JSON serialization for URL-safe serializers. 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 encoding, and compact integer conversion helpers for signed values. 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 exceptions used to report invalid data, signatures, timestamps, headers, 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 type information for Python type checkers.
• src/itsdangerous/serializer.py: Serializes Python objects into signed values and verifies signatures before loading 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: Implements signing and verification of byte strings using configurable algorithms, key derivation, and rotating secret keys. 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 signing timestamps and expiration checks to signers and serializers. 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 compression 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 type information for Python type checkers.
• tests/test_itsdangerous/test_encoding.py: Checks the encoding helpers that convert values between bytes, base64, and integers. 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, deserialization, file handling, unsafe loading, and signer configuration 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 generation, verification, key derivation, custom algorithms, separators, and key rotation. 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 signing and serialization, including expiration, timestamp return values, and malformed timestamp errors. 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

In short: This section defines common terms and points to files that can help you understand, change, and test the package.

Glossary

• Expiration: A rule that rejects a timestamped token after its allowed period.
• Key rotation: Using more than one key for verification while changing which key is used to sign.
• Serialization: Converting a Python value, such as a dictionary, into a format that can be sent or stored, then converting it back.
• Secret key: A private value an application provides to create and check signatures.
• Signature: A value calculated from data and a secret key; checking it helps detect changes but does not hide the data.
• Token: Serialized data packaged with its signature as a string.
• URL-safe encoding: Representing token data with characters suitable for use in URLs.

FAQ

Where should I start reading?

Start with the usage example in README.md. For a guided explanation of serialization and signing, see docs/serializer.rst and docs/signer.rst. The public classes and exceptions available for import are exposed through src/itsdangerous/__init__.py.

Where should I look to understand how tokens are created and checked?

Read src/itsdangerous/serializer.py for serializing values into signed tokens and loading them after signature checks. The signing and verification details are in src/itsdangerous/signer.py.

Where do timestamp and expiration rules live?

The timestamped-token behavior is implemented in src/itsdangerous/timed.py. The guide to that behavior is docs/timed.rst.

How do URL-safe tokens and compression work?

Start with src/itsdangerous/url_safe.py, which contains the URL-safe token formats and optional compression support. The corresponding documentation is docs/url_safe.rst.

Where does application configuration live?

The package configuration, including build settings and development tasks, is in pyproject.toml. Applications supply the secret key when creating a signer or serializer; the provided material does not show a required environment variable for it.

How can I add a feature safely?

First inspect the relevant implementation file, such as src/itsdangerous/serializer.py for serialization behavior. Add or update tests in the matching test area, tests/test_itsdangerous/, and update the related documentation in docs/. For feature proposals, the repository provides .github/ISSUE_TEMPLATE/feature-request.md.

How do I run the tests?

The project instructions give uv run pytest as the test command. Tests are under tests/test_itsdangerous/, with separate files for areas such as signing, timestamps, encoding, URL-safe tokens, and serialization.

How can I debug unexpected behavior?

Use the test file for the feature you are investigating to see how that behavior is checked. For example, serialization tests are in tests/test_itsdangerous/test_serializer.py, and timestamp tests are in tests/test_itsdangerous/test_timed.py. Compare the relevant implementation in src/itsdangerous/serializer.py or src/itsdangerous/timed.py with the explanation in the matching documentation file.

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