shortuuid-0.5.0/0000755000175000017500000000000013052325300014757 5ustar stavrosstavros00000000000000shortuuid-0.5.0/shortuuid.egg-info/0000755000175000017500000000000013052325300020477 5ustar stavrosstavros00000000000000shortuuid-0.5.0/shortuuid.egg-info/PKG-INFO0000644000175000017500000000157313052325300021602 0ustar stavrosstavros00000000000000Metadata-Version: 1.1 Name: shortuuid Version: 0.5.0 Summary: A generator library for concise, unambiguous and URL-safe UUIDs. Home-page: https://github.com/stochastic-technologies/shortuuid/ Author: Stochastic Technologies Author-email: info@stochastictechnologies.com License: BSD Description: A library that generates short, pretty, unambiguous unique IDs by using an extensive, case-sensitive alphabet and omitting similar-looking letters and numbers. Platform: UNKNOWN Classifier: License :: OSI Approved :: BSD License Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2.5 Classifier: Programming Language :: Python :: 2.6 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Topic :: Software Development :: Libraries :: Python Modules shortuuid-0.5.0/shortuuid.egg-info/dependency_links.txt0000644000175000017500000000000113052325300024545 0ustar stavrosstavros00000000000000 shortuuid-0.5.0/shortuuid.egg-info/top_level.txt0000644000175000017500000000001213052325300023222 0ustar stavrosstavros00000000000000shortuuid shortuuid-0.5.0/shortuuid.egg-info/SOURCES.txt0000644000175000017500000000036013052325300022362 0ustar stavrosstavros00000000000000COPYING MANIFEST.in README.rst setup.cfg setup.py shortuuid/__init__.py shortuuid/main.py shortuuid/tests.py shortuuid.egg-info/PKG-INFO shortuuid.egg-info/SOURCES.txt shortuuid.egg-info/dependency_links.txt shortuuid.egg-info/top_level.txtshortuuid-0.5.0/PKG-INFO0000644000175000017500000000157313052325300016062 0ustar stavrosstavros00000000000000Metadata-Version: 1.1 Name: shortuuid Version: 0.5.0 Summary: A generator library for concise, unambiguous and URL-safe UUIDs. Home-page: https://github.com/stochastic-technologies/shortuuid/ Author: Stochastic Technologies Author-email: info@stochastictechnologies.com License: BSD Description: A library that generates short, pretty, unambiguous unique IDs by using an extensive, case-sensitive alphabet and omitting similar-looking letters and numbers. Platform: UNKNOWN Classifier: License :: OSI Approved :: BSD License Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 2.5 Classifier: Programming Language :: Python :: 2.6 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Topic :: Software Development :: Libraries :: Python Modules shortuuid-0.5.0/setup.py0000755000175000017500000000226113052325201016475 0ustar stavrosstavros00000000000000#!/usr/bin/env python import sys from shortuuid import __version__ assert sys.version >= '2.5', "Requires Python v2.5 or above." from setuptools import setup classifiers = [ "License :: OSI Approved :: BSD License", "Programming Language :: Python", "Programming Language :: Python :: 2.5", "Programming Language :: Python :: 2.6", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.2", "Programming Language :: Python :: 3.3", "Topic :: Software Development :: Libraries :: Python Modules", ] setup( name="shortuuid", version=__version__, author="Stochastic Technologies", author_email="info@stochastictechnologies.com", url="https://github.com/stochastic-technologies/shortuuid/", description="A generator library for concise, " "unambiguous and URL-safe UUIDs.", long_description="A library that generates short, pretty, " "unambiguous unique IDs " "by using an extensive, case-sensitive alphabet and omitting " "similar-looking letters and numbers.", license="BSD", classifiers=classifiers, packages=["shortuuid"], test_suite='shortuuid.tests', tests_require=['pep8'], ) shortuuid-0.5.0/shortuuid/0000755000175000017500000000000013052325300017005 5ustar stavrosstavros00000000000000shortuuid-0.5.0/shortuuid/__init__.py0000644000175000017500000000022713052325247021131 0ustar stavrosstavros00000000000000from shortuuid.main import ( encode, decode, uuid, random, get_alphabet, set_alphabet, ShortUUID, ) __version__ = '0.5.0' shortuuid-0.5.0/shortuuid/main.py0000644000175000017500000001001713052325201020302 0ustar stavrosstavros00000000000000""" Concise UUID generation. """ import binascii import math import os import uuid as _uu def int_to_string(number, alphabet, padding=None): """ Convert a number to a string, using the given alphabet. """ output = "" alpha_len = len(alphabet) while number: number, digit = divmod(number, alpha_len) output += alphabet[digit] if padding: remainder = max(padding - len(output), 0) output = output + alphabet[0] * remainder return output def string_to_int(string, alphabet): """ Convert a string to a number, using the given alphabet. """ number = 0 alpha_len = len(alphabet) for char in string[::-1]: number = number * alpha_len + alphabet.index(char) return number class ShortUUID(object): def __init__(self, alphabet=None): if alphabet is None: alphabet = list("23456789ABCDEFGHJKLMNPQRSTUVWXYZ" "abcdefghijkmnopqrstuvwxyz") self.set_alphabet(alphabet) @property def _length(self): """ Return the necessary length to fit the entire UUID given the current alphabet. """ return int(math.ceil(math.log(2 ** 128, self._alpha_len))) def encode(self, uuid, pad_length=None): """ Encodes a UUID into a string (LSB first) according to the alphabet If leftmost (MSB) bits 0, string might be shorter """ if pad_length is None: pad_length = self._length return int_to_string(uuid.int, self._alphabet, padding=pad_length) def decode(self, string): """ Decodes a string according to the current alphabet into a UUID Raises ValueError when encountering illegal characters or too long string If string too short, fills leftmost (MSB) bits with 0. """ return _uu.UUID(int=string_to_int(string, self._alphabet)) def uuid(self, name=None, pad_length=None): """ Generate and return a UUID. If the name parameter is provided, set the namespace to the provided name and generate a UUID. """ if pad_length is None: pad_length = self._length # If no name is given, generate a random UUID. if name is None: uuid = _uu.uuid4() elif "http" not in name.lower(): uuid = _uu.uuid5(_uu.NAMESPACE_DNS, name) else: uuid = _uu.uuid5(_uu.NAMESPACE_URL, name) return self.encode(uuid, pad_length) def random(self, length=None): """ Generate and return a cryptographically-secure short random string of the specified length. """ if length is None: length = self._length random_num = int(binascii.b2a_hex(os.urandom(length)), 16) return int_to_string( random_num, self._alphabet, padding=length )[:length] def get_alphabet(self): """Return the current alphabet used for new UUIDs.""" return ''.join(self._alphabet) def set_alphabet(self, alphabet): """Set the alphabet to be used for new UUIDs.""" # Turn the alphabet into a set and sort it to prevent duplicates # and ensure reproducibility. new_alphabet = list(sorted(set(alphabet))) if len(new_alphabet) > 1: self._alphabet = new_alphabet self._alpha_len = len(self._alphabet) else: raise ValueError("Alphabet with more than " "one unique symbols required.") def encoded_length(self, num_bytes=16): """ Returns the string length of the shortened UUID. """ factor = math.log(256) / math.log(self._alpha_len) return int(math.ceil(factor * num_bytes)) # For backwards compatibility _global_instance = ShortUUID() encode = _global_instance.encode decode = _global_instance.decode uuid = _global_instance.uuid random = _global_instance.random get_alphabet = _global_instance.get_alphabet set_alphabet = _global_instance.set_alphabet shortuuid-0.5.0/shortuuid/tests.py0000644000175000017500000001313713052325201020526 0ustar stavrosstavros00000000000000import os import string import sys import unittest import pep8 from collections import defaultdict from uuid import UUID, uuid4 sys.path.insert(0, os.path.abspath(__file__ + "/../..")) from shortuuid.main import * # noqa class LegacyShortUUIDTest(unittest.TestCase): def test_generation(self): self.assertTrue(20 < len(uuid()) < 24) self.assertTrue(20 < len(uuid("http://www.example.com/")) < 24) self.assertTrue(20 < len(uuid("HTTP://www.example.com/")) < 24) self.assertTrue(20 < len(uuid("example.com/")) < 24) def test_encoding(self): u = UUID('{3b1f8b40-222c-4a6e-b77e-779d5a94e21c}') self.assertEqual(encode(u), "bYRT25J5s7Bniqr4b58cXC") def test_decoding(self): u = UUID('{3b1f8b40-222c-4a6e-b77e-779d5a94e21c}') self.assertEqual(decode("bYRT25J5s7Bniqr4b58cXC"), u) def test_alphabet(self): backup_alphabet = get_alphabet() alphabet = "01" set_alphabet(alphabet) self.assertEqual(alphabet, get_alphabet()) set_alphabet("01010101010101") self.assertEqual(alphabet, get_alphabet()) self.assertEqual(set(uuid()), set("01")) self.assertTrue(116 < len(uuid()) < 140) u = uuid4() self.assertEqual(u, decode(encode(u))) u = uuid() self.assertEqual(u, encode(decode(u))) self.assertRaises(ValueError, set_alphabet, "1") self.assertRaises(ValueError, set_alphabet, "1111111") set_alphabet(backup_alphabet) self.assertRaises(ValueError, lambda x: ShortUUID(x), "0") def test_random(self): self.assertEqual(len(random()), 22) for i in range(1, 100): self.assertEqual(len(random(i)), i) class ClassShortUUIDTest(unittest.TestCase): def test_generation(self): su = ShortUUID() self.assertTrue(20 < len(su.uuid()) < 24) self.assertTrue(20 < len(su.uuid("http://www.example.com/")) < 24) self.assertTrue(20 < len(su.uuid("HTTP://www.example.com/")) < 24) self.assertTrue(20 < len(su.uuid("example.com/")) < 24) def test_encoding(self): su = ShortUUID() u = UUID('{3b1f8b40-222c-4a6e-b77e-779d5a94e21c}') self.assertEqual(su.encode(u), "bYRT25J5s7Bniqr4b58cXC") def test_decoding(self): su = ShortUUID() u = UUID('{3b1f8b40-222c-4a6e-b77e-779d5a94e21c}') self.assertEqual(su.decode("bYRT25J5s7Bniqr4b58cXC"), u) def test_random(self): su = ShortUUID() for i in range(1000): self.assertEqual(len(su.random()), 22) for i in range(1, 100): self.assertEqual(len(su.random(i)), i) def test_alphabet(self): alphabet = "01" su1 = ShortUUID(alphabet) su2 = ShortUUID() self.assertEqual(alphabet, su1.get_alphabet()) su1.set_alphabet("01010101010101") self.assertEqual(alphabet, su1.get_alphabet()) self.assertEqual(set(su1.uuid()), set("01")) self.assertTrue(116 < len(su1.uuid()) < 140) self.assertTrue(20 < len(su2.uuid()) < 24) u = uuid4() self.assertEqual(u, su1.decode(su1.encode(u))) u = su1.uuid() self.assertEqual(u, su1.encode(su1.decode(u))) self.assertRaises(ValueError, su1.set_alphabet, "1") self.assertRaises(ValueError, su1.set_alphabet, "1111111") def test_encoded_length(self): su1 = ShortUUID() self.assertEqual(su1.encoded_length(), 22) base64_alphabet = string.ascii_uppercase + \ string.ascii_lowercase + string.digits + '+/' su2 = ShortUUID(base64_alphabet) self.assertEqual(su2.encoded_length(), 22) binary_alphabet = "01" su3 = ShortUUID(binary_alphabet) self.assertEqual(su3.encoded_length(), 128) su4 = ShortUUID() self.assertEqual(su4.encoded_length(num_bytes=8), 11) def test_pep8(self): pep8style = pep8.StyleGuide([['statistics', True], ['show-sources', True], ['repeat', True], ['paths', [os.path.dirname( os.path.abspath(__file__))]]], parse_argv=False) report = pep8style.check_files() assert report.total_errors == 0 class ShortUUIDPaddingTest(unittest.TestCase): def test_padding(self): su = ShortUUID() random_uid = uuid4() smallest_uid = UUID(int=0) encoded_random = su.encode(random_uid) encoded_small = su.encode(smallest_uid) self.assertEqual(len(encoded_random), len(encoded_small)) def test_decoding(self): su = ShortUUID() random_uid = uuid4() smallest_uid = UUID(int=0) encoded_random = su.encode(random_uid) encoded_small = su.encode(smallest_uid) self.assertEqual(su.decode(encoded_small), smallest_uid) self.assertEqual(su.decode(encoded_random), random_uid) def test_consistency(self): su = ShortUUID() num_iterations = 1000 uid_lengths = defaultdict(int) for count in range(num_iterations): random_uid = uuid4() encoded_random = su.encode(random_uid) uid_lengths[len(encoded_random)] += 1 decoded_random = su.decode(encoded_random) self.assertEqual(random_uid, decoded_random) self.assertEqual(len(uid_lengths), 1) uid_length = next(iter(uid_lengths.keys())) # Get the 1 value self.assertEqual(uid_lengths[uid_length], num_iterations) if __name__ == '__main__': unittest.main() shortuuid-0.5.0/README.rst0000644000175000017500000000637613052325201016462 0ustar stavrosstavros00000000000000=========== Description =========== ``shortuuid`` is a simple python library that generates concise, unambiguous, URL-safe UUIDs. Often, one needs to use non-sequential IDs in places where users will see them, but the IDs must be as concise and easy to use as possible. ``shortuuid`` solves this problem by generating uuids using Python's built-in ``uuid`` module and then translating them to base57 using lowercase and uppercase letters and digits, and removing similar-looking characters such as l, 1, I, O and 0. .. image:: https://travis-ci.org/skorokithakis/shortuuid.svg?branch=master :target: https://travis-ci.org/skorokithakis/shortuuid Installation ------------ To install ``shortuuid`` you need: * Python 2.5 or later in the 2.x line (earlier than 2.6 not tested). If you have the dependencies, you have multiple options of installation: * With pip (preferred), do ``pip install shortuuid``. * With setuptools, do ``easy_install shortuuid``. * To install the source, download it from https://github.com/stochastic-technologies/shortuuid and do ``python setup.py install``. Usage ----- To use ``shortuuid``, just import it in your project like so: >>> import shortuuid You can then generate a short UUID: >>> shortuuid.uuid() 'vytxeTZskVKR7C7WgdSP3d' If you prefer a version 5 UUID, you can pass a name (DNS or URL) to the call and it will be used as a namespace (uuid.NAMESPACE_DNS or uuid.NAMESPACE_URL) for the resulting UUID: >>> shortuuid.uuid(name="example.com") 'wpsWLdLt9nscn2jbTD3uxe' >>> shortuuid.uuid(name="http://example.com") 'c8sh5y9hdSMS6zVnrvf53T' You can also generate a cryptographically secure random string (using `os.urandom()`, internally) with: >>> shortuuid.ShortUUID().random(length=22) 'RaF56o2r58hTKT7AYS9doj' To see the alphabet that is being used to generate new UUIDs: >>> shortuuid.get_alphabet() '23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz' If you want to use your own alphabet to generate UUIDs, use ``set_alphabet()``: >>> shortuuid.set_alphabet("aaaaabcdefgh1230123") >>> shortuuid.uuid() '0agee20aa1hehebcagddhedddc0d2chhab3b' ``shortuuid`` will automatically sort and remove duplicates from your alphabet to ensure consistency: >>> shortuuid.get_alphabet() '0123abcdefgh' If the default 22 digits are too long for you, you can get shorter IDs by just truncating the string to the desired length. The IDs won't be universally unique any longer, but the probability of a collision will still be very low. To serialize existing UUIDs, use ``encode()`` and ``decode()``: >>> import uuid ; u = uuid.uuid4() ; u UUID('6ca4f0f8-2508-4bac-b8f1-5d1e3da2247a') >>> s = shortuuid.encode(u) ; s 'cu8Eo9RyrUsV4MXEiDZpLM' >>> shortuuid.decode(s) == u True >>> short = s[:7] ; short 'cu8Eo9R' >>> h = shortuuid.decode(short) UUID('00000000-0000-0000-0000-00b8c0b9f952') >>> shortuuid.decode(shortuuid.encode(h)) == h True Class-based usage ----------------- If you need to have various alphabets per-thread, you can use the `ShortUUID` class, like so: >>> su = shortuuid.ShortUUID(alphabet="01345678") >>> su.uuid() '034636353306816784480643806546503818874456' >>> su.get_alphabet() '01345678' >>> su.set_alphabet("21345687654123456") >>> su.get_alphabet() '12345678' License ------- ``shortuuid`` is distributed under the BSD license. shortuuid-0.5.0/setup.cfg0000644000175000017500000000020413052325300016574 0ustar stavrosstavros00000000000000[semantic_release] version_variable = shortuuid/__init__.py:__version__ [egg_info] tag_build = tag_date = 0 tag_svn_revision = 0 shortuuid-0.5.0/MANIFEST.in0000644000175000017500000000013013052325201016507 0ustar stavrosstavros00000000000000include MANIFEST.in include COPYING include README.rst recursive-include shortuuid *.py shortuuid-0.5.0/COPYING0000644000175000017500000000272413052325201016017 0ustar stavrosstavros00000000000000Copyright (c) 2011, Stochastic Technologies All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of Stochastic Technologies nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.