Metadata-Version: 2.1
Name: gid
Version: 1.0.0
Summary: Gid is a small library for generating short globally unique, sortable uri safe identifiers.
Home-page: https://github.com/kodemore/gid
License: MIT
Keywords: guid,id,short,sortable,uri-safe,urisafe,uri,safe
Author: Dawid Kraczkowski
Author-email: dawid.kraczkowski@gmail.com
Requires-Python: >=3.8,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Project-URL: Documentation, https://github.com/kodemore/gid
Project-URL: Repository, https://github.com/kodemore/gid
Description-Content-Type: text/markdown

# Gid <br> [![Release](https://github.com/kodemore/gid/actions/workflows/release.yml/badge.svg)](https://github.com/kodemore/gid/actions/workflows/release.yml) [![Linting and Tests](https://github.com/kodemore/gid/actions/workflows/main.yaml/badge.svg)](https://github.com/kodemore/gid/actions/workflows/main.yaml) [![codecov](https://codecov.io/gh/kodemore/gid/branch/main/graph/badge.svg?token=N6AROCAN9S)](https://codecov.io/gh/kodemore/gid) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
Gid is a small library for generating short globally unique, sortable uri safe identifiers.

## Features
- Generated ids are sortable
- Generated ids carry creation time expressed in microseconds
- Generated ids are globally unique
- Minimal footprint
- High performance


## Installation

With pip,
```shell
pip install gid
```
or through poetry
```shell
poetry add gid
```

## Example ids

```
ShjZz5Dvr0JyJL00
Shja07nr23XgJk00
Shja1AOUhKufOh00
Shja2CxdQ0AgNa00
Shja3FWSn2wuWu00
Shja4I6kVG860e00
```

# Usage

## Generating id
```python
from gid import Guid

some_id = Guid()
some_id.timestamp # contains timestamp expressed in milliseconds
str(some_id) # can be cast to a string
```

## Recreating id from string
```python
from gid import Guid
my_id = Guid()

same_id = Guid(str(my_id))

assert same_id == my_id
assert same_id.timestamp == my_id.timestamp
```

# Id structure
Generated identifiers are case-sensitive, which means string functions (like lowercase or uppercase) on generated 
identifiers may break it because `Sbt5LrD9iSAwb300` is not the same value as `Sbt5LrD9iSAwB300`.

The below diagram represents single identifier's structure, which is 16-character long:
```
    Sbt5LrD9iSAwb300
    |      |      |
    +- first 7 characters for millisecond timestamp
           |      |
           +- next 7 characters is randomly generated hash
                  |
                  + last two characters to ensure uniqueness of guid in a single millisecond
```

> Within 1 ms there can be 62^2 unique generated ids on a single machine.

