<NME> index.rst
<BEF> .. rst-class:: hide-header

ItsDangerous
============

.. image:: _static/itsdangerous-logo.png
    :align: center
    :target: https://palletsprojects.com/p/itsdangerous/

Sometimes you want to send some data to untrusted environments, then get
it back later. To do this safely, the data must be signed to detect
changes.

Given a key only you know, you can cryptographically sign your data and
hand it over to someone else. When you get the data back you can ensure
that nobody tampered with it.

The receiver can see the data, but they can not modify it unless they
also have your key. So if you keep the key secret and complex, you will
be fine.


Installing
----------

Install and update using `pip`_:

.. code-block:: text

    pip install -U itsdangerous

.. _pip: https://pip.pypa.io/en/stable/quickstart/


Example Use Cases
-----------------

-   Sign a user ID in a URL and email it to them to unsubscribe from a
    newsletter. This way you don't need to generate one-time tokens and
    store them in the database. Same thing with any kind of activation
    link for accounts and similar things.
-   Signed objects can be stored in cookies or other untrusted sources
    which means you don't need to have sessions stored on the server,
    which reduces the number of necessary database queries.
-   Signed information can safely do a round trip between server and
    client in general which makes them useful for passing server-side
    state to a client and then back.


Table of Contents
-----------------

.. toctree::

    concepts
    serializer
    signer
    exceptions
    timed
    url_safe
    encoding
    license
    changes
Python 3 Notes
--------------

On Python 3 the return serialized versions are represented as bytes.
However in many cases (for instance when using the URL safe serializers)
the data fits into ASCII so it can trivially be converted into unicode
strings by adding an ``.encode('ascii')``.  It also assumes that custom
serializers operate on bytes as well.


.. include:: ../CHANGES

<MSG> Fundamentally changed unicode/byte dumping behavior for Python 3

<DFF> @@ -231,11 +231,14 @@ signature was correct.
 Python 3 Notes
 --------------
 
-On Python 3 the return serialized versions are represented as bytes.
-However in many cases (for instance when using the URL safe serializers)
-the data fits into ASCII so it can trivially be converted into unicode
-strings by adding an ``.encode('ascii')``.  It also assumes that custom
-serializers operate on bytes as well.
+On Python 3 the interface that itsdangerous provides can be confusing at
+first.  Depending on the internal serializer it wraps the return value of
+the functions can alter between unicode strings or bytes objects.  The
+internal signer is always byte based.
+
+This is done to allow the module to operate on different serializers
+independent of how they are implemented.  The module decides on the
+type of the serializer by doing a test serialization of an empty object.
 
 
 .. include:: ../CHANGES

Fundamentally changed unicode/byte dumping behavior for Python 3