diff options
Diffstat (limited to 'python/slugid/README.rst')
| -rw-r--r-- | python/slugid/README.rst | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/python/slugid/README.rst b/python/slugid/README.rst new file mode 100644 index 000000000..587cd7004 --- /dev/null +++ b/python/slugid/README.rst @@ -0,0 +1,121 @@ +slugid.py - Compressed UUIDs for python +======================================= + +.. image:: https://tools.taskcluster.net/lib/assets/taskcluster-120.png + +|Build Status| |Coverage Status| |License| |pypi Version| |Downloads| + +A python module for generating v4 UUIDs and encoding them into 22 character +URL-safe base64 slug representation (see `RFC 4648 sec. 5`_). + +Slugs are url-safe base64 encoded v4 uuids, stripped of base64 ``=`` padding. + +There are two methods for generating slugs - ``slugid.v4()`` and +``slugid.nice()``. + +- The ``slugid.v4()`` method returns a slug from a randomly generated v4 uuid. +- The ``slugid.nice()`` method returns a v4 slug which conforms to a set of + "nice" properties. At the moment the only "nice" property is that the slug + starts with ``[A-Za-f]``, which in turn implies that the first (most + significant) bit of its associated uuid is set to 0. + +The purpose of the ``slugid.nice()`` method is to support having slugids which +can be used in more contexts safely. Regular slugids can safely be used in +urls, and for example in AMQP routing keys. However, slugs beginning with ``-`` +may cause problems when used as command line parameters. + +In contrast, slugids generated by the ``slugid.nice()`` method can safely be +used as command line parameters. This comes at a cost to entropy (121 bits vs +122 bits for regular v4 slugs). + +Slug consumers should consider carefully which of these two slug generation +methods to call. Is it more important to have maximum entropy, or to have +slugids that do not need special treatment when used as command line +parameters? This is especially important if you are providing a service which +supplies slugs to unexpecting tool developers downstream, who may not realise +the risks of using your regular v4 slugs as command line parameters, especially +since this would arise only as an intermittent issue (one time in 64). + +Generated slugs take the form ``[A-Za-z0-9_-]{22}``, or more precisely: + +- ``slugid.v4()`` slugs conform to + ``[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]`` + +- ``slugid.nice()`` slugs conform to + ``[A-Za-f][A-Za-z0-9_-]{7}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]`` + +RFC 4122 defines the setting of 6 bits of the v4 UUID which implies v4 slugs +provide 128 - 6 = 122 bits entropy. Due to the (un)setting of the first bit +of "nice" slugs, nice slugs provide therefore 121 bits entropy. + + +Usage +----- + +.. code-block:: python + + import slugid + + # Generate "nice" URL-safe base64 encoded UUID version 4 (random) + slug = slugid.nice() # a8_YezW8T7e1jLxG7evy-A + + # Alternative, if slugs will not be used as command line parameters + slug = slugid.v4() # -9OpXaCORAaFh4sJRk7PUA + + # Get python uuid.UUID object + uuid = slugid.decode(slug) + + # Compress to slug again + assert(slug == slugid.encode(uuid)) + + +RNG Characteristics +------------------- +UUID generation is performed by the built-in python `uuid library`_ which does +not document its randomness, but falls back to system uuid-generation libraries +where available, then urandom, then random. Therefore generated slugids match +these rng characteristics. + +License +------- +The ``slugid`` library is released on the MPL 2.0 license, see the ``LICENSE`` +for complete license. + +Testing +------- + +.. code-block:: bash + + pip install -r requirements.txt + tox + +Publishing +---------- +To republish this library to pypi.python.org, update the version number in +``slugid/__init__.py``, commit it, push to github, and then run: + +.. code-block:: bash + + # delete stale versions + rm -rf dist + + # build source package + python setup.py sdist + + # publish it + twine upload -s dist/* + + +.. _RFC 4648 sec. 5: http://tools.ietf.org/html/rfc4648#section-5 +.. _uuid library: https://docs.python.org/2/library/uuid.html + +.. |Build Status| image:: https://travis-ci.org/taskcluster/slugid.py.svg?branch=master + :target: http://travis-ci.org/taskcluster/slugid.py +.. |Coverage Status| image:: https://coveralls.io/repos/taskcluster/slugid.py/badge.svg?branch=master&service=github + :target: https://coveralls.io/github/taskcluster/slugid.py?branch=master +.. |License| image:: https://img.shields.io/badge/license-MPL%202.0-orange.svg + :target: https://github.com/taskcluster/slugid.py/blob/master/LICENSE +.. |pypi Version| image:: https://img.shields.io/pypi/v/slugid.svg + :target: https://pypi.python.org/pypi/slugid +.. |Downloads| image:: https://img.shields.io/pypi/dm/slugid.svg + :target: https://pypi.python.org/pypi/slugid |