mirror of
https://github.com/classilla/tenfourfox.git
synced 2024-09-11 02:56:06 +00:00
122 lines
4.4 KiB
ReStructuredText
122 lines
4.4 KiB
ReStructuredText
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
|