Metadata-Version: 2.4
Name: coolname-hash
Version: 1.0.0
Summary: Human-readable deterministic pseudo-hash, based on coolname
Author-email: Alexander Lukanin <alexander.lukanin.13@gmail.com>
License-Expression: BSD-2-Clause
Project-URL: Homepage, https://github.com/alexanderlukanin13/coolname-hash
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: coolname<4.2,>=4.1
Dynamic: license-file

============================================
Human-readable pseudo-hash based on coolname
============================================

|pypi| |build| |coverage|

For any int/str/bytes, return deterministic human-readable string generated by `coolname <https://pypi.org/project/coolname/>`_.

.. code-block:: python

    >>> from coolname_hash import pseudohash_slug
    >>> pseudohash_slug(123)
    'ambrosial-amorphous-jackal-of-expertise'
    >>> pseudohash_slug('qwerty')
    'logical-ingenious-albatross-of-spirit'
    >>> pseudohash_slug(b'\x00\x01\xFF')
    'small-polar-mole-of-wholeness'

Get sequences instead of strings:

.. code-block:: python

    >>> from coolname_hash import pseudohash
    >>> pseudohash('foobar')
    ['loud', 'gabby', 'finch', 'of', 'variation']

Pseudohash functions are stateless, thread-safe and don't use the ``random`` module.

This package is a drop-in replacement for coolname, you can also import and use all of the ordinary functions like
``generate`` and ``generate_slug``. You can create custom ``RandomGenerator`` as per
`documentation <https://coolname.readthedocs.io/en/latest/customization.html>`_, and use ``pseudohash`` and
``pseudohash_slug`` methods.

**WARNING:** Random sequence varies from version to version of coolname, so make sure you pin version exactly in your
project's requirements file. You MUST include something like ``coolname_hash==1.0.0`` or ``coolname_hash>=1.0,<2.0``
in your project's dependencies. Don't specify ``coolname`` in your requirements file at all - ``coolname_hash``
always pins specific version of it. ``coolname`` version (except patches) only changes in major releases of
``coolname_hash``.

If you care about consistency of pseudohashes across multiple executions of your application,
the best practice is to add an import-time assert like this, with the actual pseudohash for 0:

.. code-block:: python

    from coolname_hash import pseudohash_slug
    assert pseudohash_slug(0) == 'elusive-fabulous-sloth-of-wizardry'  # NEVER CHANGE THIS LINE: specific version of coolname_hash is required

Caveats for variable types:

- Same integer represented as int/str/bytes (e.g. ``123``, ``'123'`` and ``b'123'``) will yield the same result.

- Same text as ``bytes`` and ``str`` will yield the same result when encoded in UTF-8.

- Float/Decimal and Boolean values are not allowed (makes no sense anyway).

- ``None`` is not allowed, you should handle it explicitly in your code.


.. |pypi| image:: https://img.shields.io/pypi/v/coolname_hash.svg
    :target: https://pypi.python.org/pypi/coolname_hash
    :alt: pypi

.. |build| image:: https://github.com/alexanderlukanin13/coolname-hash/actions/workflows/ci.yml/badge.svg?branch=master
    :target: https://github.com/alexanderlukanin13/coolname-hash/actions/workflows/ci.yml
    :alt: build status

.. |coverage| image:: https://coveralls.io/repos/alexanderlukanin13/coolname-hash/badge.svg?branch=master&service=github
    :target: https://coveralls.io/github/alexanderlukanin13/coolname-hash?branch=master
    :alt: coverage
