././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1636629546.5072904 shortuuid-1.0.13/COPYING0000644000000000000000000000271414143176053011613 0ustar00Copyright (c) 2011, Stavros Korokithakis 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. ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1710187572.647255 shortuuid-1.0.13/README.md0000644000000000000000000001147314573662065012053 0ustar00Description =========== `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)](https://travis-ci.org/skorokithakis/shortuuid) Installation ------------ To install `shortuuid` you need: - Python 3.6+ 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 run `python setup.py install`. Usage ----- To use `shortuuid`, just import it in your project like so: ```python >>> import shortuuid ``` You can then generate a short UUID: ```python >>> 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: ```python >>> shortuuid.uuid(name="example.com") 'exu3DTbj2ncsn9tLdLWspw' >>> shortuuid.uuid(name="") 'shortuuid.uuid(name="")' ``` You can also generate a cryptographically secure random string (using `os.urandom()` internally) with: ```python >>> shortuuid.ShortUUID().random(length=22) 'RaF56o2r58hTKT7AYS9doj' ``` To see the alphabet that is being used to generate new UUIDs: ```python >>> shortuuid.get_alphabet() '23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz' ``` If you want to use your own alphabet to generate UUIDs, use `set_alphabet()`: ```python >>> shortuuid.set_alphabet("aaaaabcdefgh1230123") >>> shortuuid.uuid() '0agee20aa1hehebcagddhedddc0d2chhab3b' ``` The default alphabet matches the regex `[2-9A-HJ-NP-Za-km-z]{22}`. `shortuuid` will automatically sort and remove duplicates from your alphabet to ensure consistency: ```python >>> 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()`: ```python >>> import uuid >>> u = uuid.uuid4() >>> u UUID('6ca4f0f8-2508-4bac-b8f1-5d1e3da2247a') >>> s = shortuuid.encode(u) >>> s 'MLpZDiEXM4VsUryR9oE8uc' >>> shortuuid.decode(s) == u True >>> short = s[:7] >>> short 'MLpZDiE' >>> h = shortuuid.decode(short) UUID('00000000-0000-0000-0000-009a5b27f8b9') >>> 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: ```python >>> su = shortuuid.ShortUUID(alphabet="01345678") >>> su.uuid() '034636353306816784480643806546503818874456' >>> su.get_alphabet() '01345678' >>> su.set_alphabet("21345687654123456") >>> su.get_alphabet() '12345678' ``` Command-line usage ------------------ `shortuuid` provides a simple way to generate a short UUID in a terminal: ```bash $ shortuuid fZpeF6gcskHbSpTgpQCkcJ ``` Django field ------------ `shortuuid` includes a Django field that generates random short UUIDs by default, for your convenience: ```python from shortuuid.django_fields import ShortUUIDField class MyModel(models.Model): # A primary key ID of length 16 and a short alphabet. id = ShortUUIDField( length=16, max_length=40, prefix="id_", alphabet="abcdefg1234", primary_key=True, ) # A short UUID of length 22 and the default alphabet. api_key = ShortUUIDField() ``` The field is the same as the `CharField`, with a `length` argument (the length of the ID), an `alphabet` argument, and the `default` argument removed. Everything else is exactly the same, e.g. `index`, `help_text`, `max_length`, etc. Compatibility note ------------------ Versions of ShortUUID prior to 1.0.0 generated UUIDs with their MSB last, i.e. reversed. This was later fixed, but if you have some UUIDs stored as a string with the old method, you need to pass `legacy=True` to `decode()` when converting your strings back to UUIDs. That option will go away in the future, so you will want to convert your UUIDs to strings using the new method. This can be done like so: ```python >>> new_uuid_str = encode(decode(old_uuid_str, legacy=True)) ``` License ------- `shortuuid` is distributed under the BSD license. ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1710187778.5496745 shortuuid-1.0.13/pyproject.toml0000644000000000000000000000155114573662403013500 0ustar00[tool.poetry] name = "shortuuid" version = "1.0.13" description = "A generator library for concise, unambiguous and URL-safe UUIDs." license = "BSD-3-Clause" classifiers = [ "License :: OSI Approved :: BSD License", "Programming Language :: Python", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Topic :: Software Development :: Libraries :: Python Modules" ] homepage = "https://github.com/skorokithakis/shortuuid/" authors = ["Stavros Korokithakis "] readme = "README.md" include = ["COPYING"] [tool.poetry.scripts] shortuuid = "shortuuid.cli:cli" [tool.poetry.dependencies] python = ">=3.6" [build-system] requires = ["poetry-core"] build-backend = "poetry.core.masonry.api" ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1710187572.647255 shortuuid-1.0.13/shortuuid/__init__.py0000644000000000000000000000062014573662065014723 0ustar00from shortuuid.main import decode from shortuuid.main import encode from shortuuid.main import get_alphabet from shortuuid.main import random from shortuuid.main import set_alphabet from shortuuid.main import ShortUUID from shortuuid.main import uuid __version__ = "1.0.11" __all__ = [ "decode", "encode", "get_alphabet", "random", "set_alphabet", "ShortUUID", "uuid", ] ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1667993163.1610334 shortuuid-1.0.13/shortuuid/cli.py0000644000000000000000000000261614332707113013725 0ustar00import argparse import sys from typing import Any from uuid import UUID from .main import decode from .main import encode from .main import uuid def encode_cli(args: argparse.Namespace): print(encode(args.uuid)) def decode_cli(args: argparse.Namespace): print(str(decode(args.shortuuid, legacy=args.legacy))) def cli(*args: Any) -> None: parser = argparse.ArgumentParser( description="Generate, encode and decode shortuuids", epilog="top-level command generates a random shortuuid", ) subparsers = parser.add_subparsers(help="sub-command help") encode_parser = subparsers.add_parser( "encode", help="Encode a UUID into a short UUID", description=encode.__doc__ ) encode_parser.add_argument("uuid", type=UUID, help="UUID to be encoded") encode_parser.set_defaults(func=encode_cli) decode_parser = subparsers.add_parser( "decode", help="Decode a short UUID into a UUID", description=decode.__doc__ ) decode_parser.add_argument("shortuuid", type=str, help="Short UUID to be decoded") decode_parser.add_argument("--legacy", action="store_true") decode_parser.set_defaults(func=decode_cli) passed_args = parser.parse_args(*args) if hasattr(passed_args, "func"): passed_args.func(passed_args) else: # Maintain legacy behaviour print(uuid()) if __name__ == "__main__": cli(sys.argv[1:]) ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1710187572.647255 shortuuid-1.0.13/shortuuid/django_fields.py0000644000000000000000000000250514573662065015760 0ustar00from typing import Any from typing import Dict from typing import Tuple from django.db import models from django.utils.translation import gettext_lazy as _ from . import ShortUUID class ShortUUIDField(models.CharField): description = _("A short UUID field.") def __init__(self, *args: Any, **kwargs: Any) -> None: self.length: int = kwargs.pop("length", 22) # type: ignore self.prefix: str = kwargs.pop("prefix", "") # type: ignore if "max_length" not in kwargs: # If `max_length` was not specified, set it here. kwargs["max_length"] = self.length + len(self.prefix) # type: ignore self.alphabet: str = kwargs.pop("alphabet", None) # type: ignore kwargs["default"] = self._generate_uuid # type: ignore super().__init__(*args, **kwargs) def _generate_uuid(self) -> str: """Generate a short random string.""" return self.prefix + ShortUUID(alphabet=self.alphabet).random( length=self.length ) def deconstruct(self) -> Tuple[str, str, Tuple, Dict[str, Any]]: name, path, args, kwargs = super().deconstruct() kwargs["alphabet"] = self.alphabet kwargs["length"] = self.length kwargs["prefix"] = self.prefix kwargs.pop("default", None) return name, path, args, kwargs ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1710187572.647255 shortuuid-1.0.13/shortuuid/main.py0000644000000000000000000001112014573662065014105 0ustar00"""Concise UUID generation.""" import math import secrets import uuid as _uu from typing import List from typing import Optional def int_to_string( number: int, alphabet: List[str], padding: Optional[int] = None ) -> str: """ Convert a number to a string, using the given alphabet. The output has the most significant digit first. """ 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[::-1] def string_to_int(string: str, alphabet: List[str]) -> int: """ Convert a string to a number, using the given alphabet. The input is assumed to have the most significant digit first. """ number = 0 alpha_len = len(alphabet) for char in string: number = number * alpha_len + alphabet.index(char) return number class ShortUUID(object): def __init__(self, alphabet: Optional[str] = None) -> None: if alphabet is None: alphabet = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ" "abcdefghijkmnopqrstuvwxyz" self.set_alphabet(alphabet) @property def _length(self) -> int: """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: _uu.UUID, pad_length: Optional[int] = None) -> str: """ Encode a UUID into a string (LSB first) according to the alphabet. If leftmost (MSB) bits are 0, the string might be shorter. """ if not isinstance(uuid, _uu.UUID): raise ValueError("Input `uuid` must be a UUID object.") if pad_length is None: pad_length = self._length return int_to_string(uuid.int, self._alphabet, padding=pad_length) def decode(self, string: str, legacy: bool = False) -> _uu.UUID: """ Decode a string according to the current alphabet into a UUID. Raises ValueError when encountering illegal characters or a too-long string. If string too short, fills leftmost (MSB) bits with 0. Pass `legacy=True` if your UUID was encoded with a ShortUUID version prior to 1.0.0. """ if not isinstance(string, str): raise ValueError("Input `string` must be a str.") if legacy: string = string[::-1] return _uu.UUID(int=string_to_int(string, self._alphabet)) def uuid(self, name: Optional[str] = None, pad_length: Optional[int] = None) -> str: """ 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: u = _uu.uuid4() elif name.lower().startswith(("http://", "https://")): u = _uu.uuid5(_uu.NAMESPACE_URL, name) else: u = _uu.uuid5(_uu.NAMESPACE_DNS, name) return self.encode(u, pad_length) def random(self, length: Optional[int] = None) -> str: """Generate and return a cryptographically secure short random string of `length`.""" if length is None: length = self._length return "".join(secrets.choice(self._alphabet) for _ in range(length)) def get_alphabet(self) -> str: """Return the current alphabet used for new UUIDs.""" return "".join(self._alphabet) def set_alphabet(self, alphabet: str) -> None: """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: int = 16) -> int: """Return 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 ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1710187572.647255 shortuuid-1.0.13/shortuuid/py.typed0000644000000000000000000000000014573662065014301 0ustar00././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1667993163.1610334 shortuuid-1.0.13/shortuuid/test_shortuuid.py0000644000000000000000000001604714332707113016246 0ustar00import os import string import sys import unittest from collections import defaultdict from unittest.mock import patch from uuid import UUID from uuid import uuid4 from shortuuid.cli import cli from shortuuid.main import decode from shortuuid.main import encode from shortuuid.main import get_alphabet from shortuuid.main import random from shortuuid.main import set_alphabet from shortuuid.main import ShortUUID from shortuuid.main import uuid sys.path.insert(0, os.path.abspath(__file__ + "/../..")) 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), "CXc85b4rqinB7s5J52TRYb") def test_decoding(self): u = UUID("{3b1f8b40-222c-4a6e-b77e-779d5a94e21c}") self.assertEqual(decode("CXc85b4rqinB7s5J52TRYb"), 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), "CXc85b4rqinB7s5J52TRYb") def test_decoding(self): su = ShortUUID() u = UUID("{3b1f8b40-222c-4a6e-b77e-779d5a94e21c}") self.assertEqual(su.decode("CXc85b4rqinB7s5J52TRYb"), 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) 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) class EncodingEdgeCasesTest(unittest.TestCase): def test_decode_dict(self): su = ShortUUID() self.assertRaises(ValueError, su.encode, []) self.assertRaises(ValueError, su.encode, {}) self.assertRaises(ValueError, su.decode, (2,)) self.assertRaises(ValueError, su.encode, 42) self.assertRaises(ValueError, su.encode, 42.0) class DecodingEdgeCasesTest(unittest.TestCase): def test_decode_dict(self): su = ShortUUID() self.assertRaises(ValueError, su.decode, []) self.assertRaises(ValueError, su.decode, {}) self.assertRaises(ValueError, su.decode, (2,)) self.assertRaises(ValueError, su.decode, 42) self.assertRaises(ValueError, su.decode, 42.0) class CliTest(unittest.TestCase): @patch("shortuuid.cli.print") def test_shortuuid_command_produces_uuid(self, mock_print): # When we call the main cli function cli([]) # Then a shortuuid is printed out mock_print.assert_called() terminal_output = mock_print.call_args[0][0] self.assertEqual(len(terminal_output), 22) @patch("shortuuid.cli.print") def test_encode_command(self, mock_print): cli(["encode", "3b1f8b40-222c-4a6e-b77e-779d5a94e21c"]) terminal_output = mock_print.call_args[0][0] self.assertEqual(terminal_output, "CXc85b4rqinB7s5J52TRYb") @patch("shortuuid.cli.print") def test_decode_command(self, mock_print): cli(["decode", "CXc85b4rqinB7s5J52TRYb"]) terminal_output = mock_print.call_args[0][0] self.assertEqual(terminal_output, "3b1f8b40-222c-4a6e-b77e-779d5a94e21c") if __name__ == "__main__": unittest.main() shortuuid-1.0.13/PKG-INFO0000644000000000000000000001320700000000000011611 0ustar00Metadata-Version: 2.1 Name: shortuuid Version: 1.0.13 Summary: A generator library for concise, unambiguous and URL-safe UUIDs. Home-page: https://github.com/skorokithakis/shortuuid/ License: BSD-3-Clause Author: Stavros Korokithakis Author-email: hi@stavros.io Requires-Python: >=3.6 Classifier: License :: OSI Approved :: BSD License Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.6 Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: 3.8 Classifier: Programming Language :: Python :: 3.9 Classifier: Programming Language :: Python :: 3.10 Classifier: Programming Language :: Python :: 3.11 Classifier: Topic :: Software Development :: Libraries :: Python Modules Description-Content-Type: text/markdown 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)](https://travis-ci.org/skorokithakis/shortuuid) Installation ------------ To install `shortuuid` you need: - Python 3.6+ 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 run `python setup.py install`. Usage ----- To use `shortuuid`, just import it in your project like so: ```python >>> import shortuuid ``` You can then generate a short UUID: ```python >>> 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: ```python >>> shortuuid.uuid(name="example.com") 'exu3DTbj2ncsn9tLdLWspw' >>> shortuuid.uuid(name="") 'shortuuid.uuid(name="")' ``` You can also generate a cryptographically secure random string (using `os.urandom()` internally) with: ```python >>> shortuuid.ShortUUID().random(length=22) 'RaF56o2r58hTKT7AYS9doj' ``` To see the alphabet that is being used to generate new UUIDs: ```python >>> shortuuid.get_alphabet() '23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz' ``` If you want to use your own alphabet to generate UUIDs, use `set_alphabet()`: ```python >>> shortuuid.set_alphabet("aaaaabcdefgh1230123") >>> shortuuid.uuid() '0agee20aa1hehebcagddhedddc0d2chhab3b' ``` The default alphabet matches the regex `[2-9A-HJ-NP-Za-km-z]{22}`. `shortuuid` will automatically sort and remove duplicates from your alphabet to ensure consistency: ```python >>> 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()`: ```python >>> import uuid >>> u = uuid.uuid4() >>> u UUID('6ca4f0f8-2508-4bac-b8f1-5d1e3da2247a') >>> s = shortuuid.encode(u) >>> s 'MLpZDiEXM4VsUryR9oE8uc' >>> shortuuid.decode(s) == u True >>> short = s[:7] >>> short 'MLpZDiE' >>> h = shortuuid.decode(short) UUID('00000000-0000-0000-0000-009a5b27f8b9') >>> 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: ```python >>> su = shortuuid.ShortUUID(alphabet="01345678") >>> su.uuid() '034636353306816784480643806546503818874456' >>> su.get_alphabet() '01345678' >>> su.set_alphabet("21345687654123456") >>> su.get_alphabet() '12345678' ``` Command-line usage ------------------ `shortuuid` provides a simple way to generate a short UUID in a terminal: ```bash $ shortuuid fZpeF6gcskHbSpTgpQCkcJ ``` Django field ------------ `shortuuid` includes a Django field that generates random short UUIDs by default, for your convenience: ```python from shortuuid.django_fields import ShortUUIDField class MyModel(models.Model): # A primary key ID of length 16 and a short alphabet. id = ShortUUIDField( length=16, max_length=40, prefix="id_", alphabet="abcdefg1234", primary_key=True, ) # A short UUID of length 22 and the default alphabet. api_key = ShortUUIDField() ``` The field is the same as the `CharField`, with a `length` argument (the length of the ID), an `alphabet` argument, and the `default` argument removed. Everything else is exactly the same, e.g. `index`, `help_text`, `max_length`, etc. Compatibility note ------------------ Versions of ShortUUID prior to 1.0.0 generated UUIDs with their MSB last, i.e. reversed. This was later fixed, but if you have some UUIDs stored as a string with the old method, you need to pass `legacy=True` to `decode()` when converting your strings back to UUIDs. That option will go away in the future, so you will want to convert your UUIDs to strings using the new method. This can be done like so: ```python >>> new_uuid_str = encode(decode(old_uuid_str, legacy=True)) ``` License ------- `shortuuid` is distributed under the BSD license.