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.
[](https://travis-ci.org/skorokithakis/shortuuid)
Installation
------------
To install `shortuuid` you need:
- Python 3.x.
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="<http://example.com>")
'shortuuid.uuid(name="<http://example.com>")'
```
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/skorokithakis/shortuuid/",
"name": "shortuuid",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "",
"author": "Stavros Korokithakis",
"author_email": "hi@stavros.io",
"download_url": "https://files.pythonhosted.org/packages/cf/a0/f7a811bbe38e4c82b48ca8ffde6f7ba0d8a3516ab2540363843a60e63ca4/shortuuid-1.0.12.tar.gz",
"platform": null,
"description": "Description\n===========\n\n`shortuuid` is a simple python library that generates concise, unambiguous, URL-safe\nUUIDs.\n\nOften, one needs to use non-sequential IDs in places where users will see them, but the\nIDs must be as concise and easy to use as possible. `shortuuid` solves this problem by\ngenerating uuids using Python's built-in `uuid` module and then translating them to\nbase57 using lowercase and uppercase letters and digits, and removing similar-looking\ncharacters such as l, 1, I, O and 0.\n\n[](https://travis-ci.org/skorokithakis/shortuuid)\n\n\nInstallation\n------------\n\nTo install `shortuuid` you need:\n\n- Python 3.x.\n\nIf you have the dependencies, you have multiple options of installation:\n\n- With pip (preferred), do `pip install shortuuid`.\n- With setuptools, do `easy_install shortuuid`.\n- To install the source, download it from\n https://github.com/stochastic-technologies/shortuuid and run `python setup.py\n install`.\n\n\nUsage\n-----\n\nTo use `shortuuid`, just import it in your project like so:\n\n```python\n>>> import shortuuid\n```\n\nYou can then generate a short UUID:\n\n```python\n>>> shortuuid.uuid()\n'vytxeTZskVKR7C7WgdSP3d'\n```\n\nIf you prefer a version 5 UUID, you can pass a name (DNS or URL) to the call and it will\nbe used as a namespace (`uuid.NAMESPACE_DNS` or `uuid.NAMESPACE_URL`) for the resulting\nUUID:\n\n```python\n>>> shortuuid.uuid(name=\"example.com\")\n'exu3DTbj2ncsn9tLdLWspw'\n\n>>> shortuuid.uuid(name=\"<http://example.com>\")\n'shortuuid.uuid(name=\"<http://example.com>\")'\n```\n\nYou can also generate a cryptographically secure random string (using `os.urandom()`\ninternally) with:\n\n```python\n>>> shortuuid.ShortUUID().random(length=22)\n'RaF56o2r58hTKT7AYS9doj'\n```\n\nTo see the alphabet that is being used to generate new UUIDs:\n\n```python\n>>> shortuuid.get_alphabet()\n'23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'\n```\n\nIf you want to use your own alphabet to generate UUIDs, use `set_alphabet()`:\n\n```python\n>>> shortuuid.set_alphabet(\"aaaaabcdefgh1230123\")\n>>> shortuuid.uuid()\n'0agee20aa1hehebcagddhedddc0d2chhab3b'\n```\n\nThe default alphabet matches the regex `[2-9A-HJ-NP-Za-km-z]{22}`.\n\n`shortuuid` will automatically sort and remove duplicates from your alphabet to ensure\nconsistency:\n\n```python\n>>> shortuuid.get_alphabet()\n'0123abcdefgh'\n```\n\nIf the default 22 digits are too long for you, you can get shorter IDs by just\ntruncating the string to the desired length. The IDs won't be universally unique any\nlonger, but the probability of a collision will still be very low.\n\nTo serialize existing UUIDs, use `encode()` and `decode()`:\n\n```python\n>>> import uuid\n>>> u = uuid.uuid4()\n>>> u\nUUID('6ca4f0f8-2508-4bac-b8f1-5d1e3da2247a')\n\n>>> s = shortuuid.encode(u)\n>>> s\n'MLpZDiEXM4VsUryR9oE8uc'\n\n>>> shortuuid.decode(s) == u\nTrue\n\n>>> short = s[:7]\n>>> short\n'MLpZDiE'\n\n>>> h = shortuuid.decode(short)\nUUID('00000000-0000-0000-0000-009a5b27f8b9')\n\n>>> shortuuid.decode(shortuuid.encode(h)) == h\nTrue\n```\n\n\nClass-based usage\n-----------------\n\nIf you need to have various alphabets per-thread, you can use the `ShortUUID` class,\nlike so:\n\n```python\n>>> su = shortuuid.ShortUUID(alphabet=\"01345678\")\n>>> su.uuid()\n'034636353306816784480643806546503818874456'\n\n>>> su.get_alphabet()\n'01345678'\n\n>>> su.set_alphabet(\"21345687654123456\")\n>>> su.get_alphabet()\n'12345678'\n```\n\n\nCommand-line usage\n------------------\n\n`shortuuid` provides a simple way to generate a short UUID in a terminal:\n\n```bash\n$ shortuuid\nfZpeF6gcskHbSpTgpQCkcJ\n```\n\n\nDjango field\n------------\n\n`shortuuid` includes a Django field that generates random short UUIDs by default, for\nyour convenience:\n\n```python\nfrom shortuuid.django_fields import ShortUUIDField\n\nclass MyModel(models.Model):\n # A primary key ID of length 16 and a short alphabet.\n id = ShortUUIDField(\n length=16,\n max_length=40,\n prefix=\"id_\",\n alphabet=\"abcdefg1234\",\n primary_key=True,\n )\n\n # A short UUID of length 22 and the default alphabet.\n api_key = ShortUUIDField()\n```\n\nThe field is the same as the `CharField`, with a `length` argument (the length of the\nID), an `alphabet` argument, and the `default` argument removed. Everything else is\nexactly the same, e.g. `index`, `help_text`, `max_length`, etc.\n\n\nCompatibility note\n------------------\n\nVersions of ShortUUID prior to 1.0.0 generated UUIDs with their MSB last, i.e. reversed.\nThis was later fixed, but if you have some UUIDs stored as a string with the old method,\nyou need to pass `legacy=True` to `decode()` when converting your strings back to UUIDs.\n\nThat option will go away in the future, so you will want to convert your UUIDs to\nstrings using the new method. This can be done like so:\n\n```python\n>>> new_uuid_str = encode(decode(old_uuid_str, legacy=True))\n```\n\nLicense\n-------\n\n`shortuuid` is distributed under the BSD license.\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A generator library for concise, unambiguous and URL-safe UUIDs.",
"version": "1.0.12",
"project_urls": {
"Homepage": "https://github.com/skorokithakis/shortuuid/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dbad24714961452e94152c12ef340841fbcac6ce6deb9e07854142a11d1a31ff",
"md5": "d0295c9a37a4529ea2bc6b3ef07d614c",
"sha256": "dd855d8c10ced5dc2790b97e31f16ad55a6f4871b478feb4351dd3128a8aa82b"
},
"downloads": -1,
"filename": "shortuuid-1.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d0295c9a37a4529ea2bc6b3ef07d614c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 10562,
"upload_time": "2024-02-28T23:17:50",
"upload_time_iso_8601": "2024-02-28T23:17:50.317152Z",
"url": "https://files.pythonhosted.org/packages/db/ad/24714961452e94152c12ef340841fbcac6ce6deb9e07854142a11d1a31ff/shortuuid-1.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cfa0f7a811bbe38e4c82b48ca8ffde6f7ba0d8a3516ab2540363843a60e63ca4",
"md5": "979365e3d04f64352dada182e13bbc71",
"sha256": "c39f1b348b3c1e9b115a954b33b76c8c522d2d177a9d20acdbb20d24fac3ccfd"
},
"downloads": -1,
"filename": "shortuuid-1.0.12.tar.gz",
"has_sig": false,
"md5_digest": "979365e3d04f64352dada182e13bbc71",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 9738,
"upload_time": "2024-02-28T23:17:51",
"upload_time_iso_8601": "2024-02-28T23:17:51.598763Z",
"url": "https://files.pythonhosted.org/packages/cf/a0/f7a811bbe38e4c82b48ca8ffde6f7ba0d8a3516ab2540363843a60e63ca4/shortuuid-1.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-28 23:17:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "skorokithakis",
"github_project": "shortuuid",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "shortuuid"
}
JSON
