Metadata-Version: 2.2
Name: huuid
Version: 0.9.0
Summary: library to convert uuids forth and back to a human-readable and pronounceable format
Home-page: https://github.com/polarwinkel/huuid
Author: Dirk Winkel
Author-email: it@polarwinkel.de
Project-URL: Bug Reports, https://github.com/polarwinkel/mdtex2html/issues
Project-URL: Source, https://github.com/polarwinkel/mdtex2html
Keywords: TeX,LaTeX,Markdown,HTML markdown2html,latex2mathml
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Topic :: Database
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.7, <4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: uuid
Requires-Dist: math
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python

# huuid - human UUIDs
python3-library to convert uuids forth and back to a human-readable and pronounceable format

## What is `huuid`

`hhuid` does a bijective transformation from uuids to a format that can be read, pronounced and typed a lot better than the default formats.
No Information is lost in the mapping.

Here is an example-output of the `demo.py` in the `tests`-folder:

```
generated uuid:          f3ad6cef-2732-4b18-97dd-137a459eb656
human-readable:          tapratnaz-vorjonfif-Tezjozdin-sejgipneh
Afer back-translation:   f3ad6cef-2732-4b18-97dd-137a459eb656
--- other usecases: ---
first 32bit human-readable:  tapratnaz
generated 32bit-Password:    Sunmuhnud
generated 64bit-Password:    Vezvegdum-ladzibkal
```

## How to use `huuid`

Install it using pip:

`pip install huuid`

or just put the folder `huuid` in your project-root. (Jep, just that one file - that's all!)

Then in python import it in your code with

`import huuid`

and convert any uuid-object or uuid-string to a huuid-string with

`huuid.uuid2human(myUuidObject)`

Optionally you can limit the huuid-string to the 32, 64 or 96 bit:

`huuid.uuid2human(myUuidObject, 64)`

Convert it back to a uuid-string with

`huuid.human2uuid(myUuidObject)`

## Background

The hexadecimal representation of the UUID is translated to letters that have an unambiguous pronounciation. The 2nd, and then every third letter is a vowel, the other ones are consonants which makes up a well pronounced word that sounds like it is made up of syllables.

There are 5 vowels and 16 consonants (just unambiguous ones) being used, and (only) for the first letter capitals are allowed.
(And a capital-C additional to the 16 chosen unambiguous consonants to reach 32bit with 9 letters)

With this pattern there are a little more than 2^32 possibilities to generate a word with 9 letters.
4 "Words" hit the 128bit of UUIDs (>10^38).

## Dependencies

This only uses the python3-modules `uuid` and `math`.

## Credits

This is highly inspired by

https://arxiv.org/html/0901.4016

published by Daniel Shawcross Wilkerson
and its implementation:

https://github.com/dsw/proquint
