1slugid.py - Compressed UUIDs for python 2======================================= 3 4.. image:: https://tools.taskcluster.net/lib/assets/taskcluster-120.png 5 6|Build Status| |Coverage Status| |License| |pypi Version| |Downloads| 7 8A python 2.7 and python 3.5 compatible module for generating v4 UUIDs and 9encoding them into 22 character URL-safe base64 slug representation (see `RFC 104648 sec. 5`_). 11 12Slugs are url-safe base64 encoded v4 uuids, stripped of base64 ``=`` padding. 13 14There are two methods for generating slugs - ``slugid.v4()`` and 15``slugid.nice()``. 16 17- The ``slugid.v4()`` method returns a slug from a randomly generated v4 uuid. 18- The ``slugid.nice()`` method returns a v4 slug which conforms to a set of 19 "nice" properties. At the moment the only "nice" property is that the slug 20 starts with ``[A-Za-f]``, which in turn implies that the first (most 21 significant) bit of its associated uuid is set to 0. 22 23The purpose of the ``slugid.nice()`` method is to support having slugids which 24can be used in more contexts safely. Regular slugids can safely be used in 25urls, and for example in AMQP routing keys. However, slugs beginning with ``-`` 26may cause problems when used as command line parameters. 27 28In contrast, slugids generated by the ``slugid.nice()`` method can safely be 29used as command line parameters. This comes at a cost to entropy (121 bits vs 30122 bits for regular v4 slugs). 31 32Slug consumers should consider carefully which of these two slug generation 33methods to call. Is it more important to have maximum entropy, or to have 34slugids that do not need special treatment when used as command line 35parameters? This is especially important if you are providing a service which 36supplies slugs to unexpecting tool developers downstream, who may not realise 37the risks of using your regular v4 slugs as command line parameters, especially 38since this would arise only as an intermittent issue (one time in 64). 39 40Generated slugs take the form ``[A-Za-z0-9_-]{22}``, or more precisely: 41 42- ``slugid.v4()`` slugs conform to 43 ``[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]`` 44 45- ``slugid.nice()`` slugs conform to 46 ``[A-Za-f][A-Za-z0-9_-]{7}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]`` 47 48RFC 4122 defines the setting of 6 bits of the v4 UUID which implies v4 slugs 49provide 128 - 6 = 122 bits entropy. Due to the (un)setting of the first bit 50of "nice" slugs, nice slugs provide therefore 121 bits entropy. 51 52 53Usage 54----- 55 56.. code-block:: python 57 58 import slugid 59 60 # Generate "nice" URL-safe base64 encoded UUID version 4 (random) 61 slug = slugid.nice() # a8_YezW8T7e1jLxG7evy-A 62 63 # Alternative, if slugs will not be used as command line parameters 64 slug = slugid.v4() # -9OpXaCORAaFh4sJRk7PUA 65 66 # Get python uuid.UUID object 67 uuid = slugid.decode(slug) 68 69 # Compress to slug again 70 assert(slug == slugid.encode(uuid)) 71 72 73RNG Characteristics 74------------------- 75UUID generation is performed by the built-in python `uuid library`_ which does 76not document its randomness, but falls back to system uuid-generation libraries 77where available, then urandom, then random. Therefore generated slugids match 78these rng characteristics. 79 80License 81------- 82The ``slugid`` library is released on the MPL 2.0 license, see the ``LICENSE`` 83for complete license. 84 85Testing 86------- 87 88.. code-block:: bash 89 90 pip install -r requirements.txt 91 tox 92 93Publishing 94---------- 95To republish this library to pypi.python.org, update the version number in 96``slugid/__init__.py``, commit it, push to github, and then run: 97 98.. code-block:: bash 99 100 # delete stale versions 101 rm -rf dist 102 103 # build source package 104 python setup.py sdist 105 106 # publish it 107 twine upload -s dist/* 108 109 110.. _RFC 4648 sec. 5: http://tools.ietf.org/html/rfc4648#section-5 111.. _uuid library: https://docs.python.org/2/library/uuid.html 112 113.. |Build Status| image:: https://travis-ci.org/taskcluster/slugid.py.svg?branch=master 114 :target: http://travis-ci.org/taskcluster/slugid.py 115.. |Coverage Status| image:: https://coveralls.io/repos/taskcluster/slugid.py/badge.svg?branch=master&service=github 116 :target: https://coveralls.io/github/taskcluster/slugid.py?branch=master 117.. |License| image:: https://img.shields.io/badge/license-MPL%202.0-orange.svg 118 :target: https://github.com/taskcluster/slugid.py/blob/master/LICENSE 119.. |pypi Version| image:: https://img.shields.io/pypi/v/slugid.svg 120 :target: https://pypi.python.org/pypi/slugid 121.. |Downloads| image:: https://img.shields.io/pypi/dm/slugid.svg 122 :target: https://pypi.python.org/pypi/slugid 123
