Metadata-Version: 2.1
Name: vasuki
Version: 0.3.3
Summary: Vasuki generates different kinds of random unique identifiers, tokens and words
Home-page: https://github.com/daq-tools/vasuki
Author: Andreas Motl
Author-email: andreas@terkin.org
License: AGPL 3, EUPL 1.2
Keywords: random unique identifier token word generator id uuid ulid hashid gibberish nagamani19
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Topic :: Communications
Classifier: Topic :: Database
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Object Brokering
Classifier: Topic :: System :: Archiving
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Utilities
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Provides-Extra: service
License-File: LICENSE

.. image:: https://img.shields.io/pypi/pyversions/vasuki.svg
    :alt: Supported versions of Python
    :target: https://pypi.org/project/vasuki/

.. image:: https://img.shields.io/pypi/v/vasuki.svg
    :alt: Version on PyPI
    :target: https://pypi.org/project/vasuki/

.. image:: https://img.shields.io/pypi/status/vasuki.svg
    :alt: Status
    :target: https://pypi.org/project/vasuki/

.. image:: https://img.shields.io/pypi/l/vasuki.svg
    :alt: License
    :target: https://pypi.org/project/vasuki/

|

.. figure:: https://ptrace.hiveeyes.org/2019-06-29_vasuki-small.jpg
    :target: https://en.wikipedia.org/wiki/Vasuki#/media/File:Kurma,_the_tortoise_incarnation_of_Vishnu.jpg

.. vasuki-readme:

######
Vasuki
######


*****
About
*****
Vasuki generates different kinds of random unique identifiers, tokens and words.

It aims to make identifier generation effortless.

There might still be dragons.


**********
Disclaimer
**********
The algorithms curated here generate different kinds of random and
pseudo-random identifiers, tokens, names or passwords, let's just call
them "prwords". While some of the generated "prwords" max out on the
randomness and uniqueness aspects like UUIDs, others compromise on the
time vs. space domain but focus more on human memorability and empathize
with their common sense and humor. Saying that, humans should know what
they are doing when using these identifiers in different contexts. YMMV.


*******
Install
*******

Prerequisites
=============
::

    pip install vasuki

With service API::

    pip install vasuki[service]


********
Features
********

Unique ID generators
====================
- UUIDv4_ universally unique identifier
- ULID_ universally unique lexicographically sortable identifier
- Gibberish_ random, pronounceable pseudo-words
- MomentName, a short epoch slug
- Nagamani19, a short, unique, non-sequential identifier based on Hashids_
  and a custom Epoch starting on January 1, 2019.

Time and randomness is usually taking from the system
as implemented by the libraries underpinning this package.

Slugifiers
==========
- `six-nibble-name`_ converts six nibbles (three bytes) into a 4-character name

Optional service API
====================
The fine responder_ optionally exposes the machinery as HTTP API.

.. _UUIDv4: https://en.wikipedia.org/wiki/Universally_unique_identifier
.. _ULID: https://github.com/ulid/spec
.. _Hashids: https://hashids.org/
.. _Gibberish: https://github.com/greghaskins/gibberish
.. _six-nibble-name: https://github.com/HowManyOliversAreThere/six-nibble-name
.. _responder: https://pypi.org/project/responder/


********
Synopsis
********
::

    # UUIDv4 universally unique identifier.
    vasuki uuid

    # ULID universally unique lexicographically sortable identifier.
    vasuki ulid

    # Gibberish random, pronounceable pseudo-words
    vasuki gibberish

    # MomentName short epoch slugs
    vasuki moment

    # Nagamani19 short, unique, non-sequential identifier.
    vasuki naga19


********
Examples
********

Identifier generation
=====================
::

    # UUIDv4
    vasuki uuid
    d192b464-d32c-48f1-9c23-0fe04a4e8133

    # ULID
    01DEFKXYCJ0E91DQY0YPWZY01D

    # Gibberish
    vasuki gibberish
    shoomly

    # MomentName
    vasuki moment
    Zese

    # Nagamani19
    vasuki naga19
    Xm3k6mWq


With transformations
====================
Vasuki can apply uppercase or lowercase transformation to the
generated identifier or word::

    # UUIDv4, uppercase
    vasuki uuid --upper
    43FA0272-CA48-40AE-8CC1-204302D91D89

    # ULID, lowercase
    vasuki ulid --lower
    01defkz01k47dqkvcyhy0mz06e

With variable word length
=========================
::

    vasuki gibberish --size medium
    schreblyiopp


Slug tools
==========
::

    vasuki slug 42 --format=sixnibble
    Baca

Multiple tokens at once
=======================
::

    vasuki naga19 --count 10
    vasuki gibberish --size large --count 50


HTTP API
========
Start the Vasuki service as daemon::

    vasuki service

Example requests would look like::

    # UUIDv4
    /unique/uuid

    # Uppercase UUIDv4
    /unique/uuid?upper=true

    # Multiple ULIDs
    /unique/ulid?count=10

    # Very short Nagamani19
    /unique/naga19?size=small


***********
Development
***********
::

    python3 -m venv .venv
    source .venv/bin/activate
    pip install --editable=.[service]
    vasuki --version


*******
Credits
*******
- Andrew Hawker for https://github.com/ahawker/ulid
- David Aurelio for https://github.com/davidaurelio/hashids-python
- Gregory Haskins for https://github.com/greghaskins/gibberish
- Oliver Robson for https://github.com/HowManyOliversAreThere/six-nibble-name
- All authors for all other fine pieces this software is made of.
- Mozilla for `Zilla Slab`_
- Vasuki Logo from https://en.wikipedia.org/wiki/Vasuki

.. _Zilla Slab: https://blog.mozilla.org/opendesign/zilla-slab-common-language-shared-font/


*********
Etymology
*********

Kurma_ is one of the avatars of Vishnu_. He appears in the form of a tortoise
or turtle to support the foundation of the cosmos, while the gods and demons
churn the cosmic ocean with the help of serpent Vasuki_ to produce the nectar
of immortality.

Vasuki is a naga serpent king, occasionally coiling around Kurma's or Shiva's
neck, who blessed and wore him as an ornament. He is described as having
a gem called Nagamani on his head.

.. _Kurma: https://en.wikipedia.org/wiki/Kurma
.. _Vishnu: https://en.wikipedia.org/wiki/Vishnu
.. _Vasuki: https://en.wikipedia.org/wiki/Vasuki


