import FIREFOX_52_6_0esr_RELEASE from mozilla-esr52 hg repo

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