Skip to main content

Transform integer ids into readable, nonconsecutive ids

Project description

# Readable ID
[![CircleCI](https://circleci.com/gh/nziehn/readableID.svg?style=svg)](https://circleci.com/gh/nziehn/readableID)

Use readableID to transform integer item ids to readable, nonconsecutive ids

Criteria for a good readable id:
- as short as possible
- should contain only numbers and characters that are easy to distinguish regardless of font, e.g. no `0` vs `O`.
- not create any duplicates with increase number of items!
- consecutive numbers should not create consecutive ids

```python
id_generator.generate_id(0) # returns 9MBE
id_generator.generate_id(1) # returns QCAH
```

This library does not use any dependencies outside of the python std lib!


### Installing

Just install using `pip`:
```
pip install readableID
```


### Usage

Usage is very simple after creating an object, just call the `generate_id` method:
```python
import readableID

id_generator = readableID.ReadableID()

for x in range(1000):
readable_id = id_generator.generate_id(x)
print(readable_id)
```

Generally it is easiest to use this library in conjunction with a database that allows auto-incrementing ids
which you use as input for the generate_id method.


### Adapting parameters to your needs

To create your own unique numbers, you can salt them using the following parameters:

```python
import readableID
id_generator = readableID.ReadableID(
charset=readableID.DEFAULT_CHARSET,
min_length=readableID.DEFAULT_MINIMAL_LENGTH,
prime=readableID.DEFAULT_PRIME,
xor=readableID.DEFAULT_XOR
)
```

#### `charset`:

The `charset` controls the allowed characters. There are 2 criteria for this string:
1. characters must be unique
2. length of string must be a power of 2, e.g. 8, 16, 32, 64

The default charset is chosen to create minimal confusion for readers, since only very distinct chars were chosen.

#### `min_length`:

The `min_length` controls the length of the generated ids. The library will fit as many item ids into the given `min_length` as possible,
but if your number of items grows beyond this number, the ids will automatically get longer!

Example: with the default parameters, you can fit `32 ^ 4` item ids into 4 characters.
So if you call `generate_id` with any number `0 <= x < 32^4` it will produce a id with length of 4.
Starting at `32^4`, you will see ids with length of 5! Starting at `32^5` you will see ids with length of 6 and so on.

#### `prime`:

The `prime` parameter allows you to change how the next number is chosen. It is critical that this is a `prime number > 2` if you want to avoid duplicates!

If you are unsure - you can skip changing this parameter and rather chose a different `xor` value!

#### `xor`:

The `xor` value allows you to create different sequences of numbers, you can chose `any integer >= 0`,
but generally it makes more since to pick a number:
`100 < x < len(charset) ^ min_length`. Changing `xor` will not have as big of an effect as changing the `prime` value,
but will still create reasonably different sequences of numbers/

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for readableID, version 0.0.4
Filename, size File type Python version Upload date Hashes
Filename, size readableID-0.0.4-py3-none-any.whl (5.2 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size readableID-0.0.4.tar.gz (2.8 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page