before library released

Author: mpcabd

.gitignore

@@ -0,0 +1,52 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.tox/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+.pytest_cache/
+
+# virtualenv
+venv/
+
+# ignore
+.ignore/
+.DS_Store
+
+optimus-primes/

.travis.yml

@@ -0,0 +1,13 @@
+language: python
+install:
+  - pip install tox
+  - pip install -e .
+matrix:
+  include:
+    - python: 3.8
+      env:
+        - TOX_ENV=py38
+    - python: 3.9
+      env:
+        - TOX_ENV=py39
+script: tox -e $TOX_ENV

README.md

@@ -0,0 +1,83 @@
+# python-optimus
+This is based fully on [pjebs/optimus-go](https://github.com/pjebs/optimus-go) for Go which is based on [jenssegers/optimus](https://github.com/jenssegers/optimus) for PHP which is based on Knuth's Integer Hashing (Multiplicative Hashing) from his book [The Art Of Computer Programming, Vol. 3, 2nd Edition](https://archive.org/details/B-001-001-250/page/n535/mode/2up), Section 6.4, Page 516.
+
+With this library, you can transform your internal id's to obfuscated integers based on Knuth's integer hash. It is similar to Hashids, but will generate integers instead of random strings. It is also super fast.
+
+This library supports both 32 and 64 bits integers, although in Python you don't have that differentiation between int32 and int64, even bigint or bignum is the same since [PEP 237](https://www.python.org/dev/peps/pep-0237/). The reason you need a bitlength is that the algorithm itself works on a fixed bitlength. By default this library uses 64 bits.
+
+## Python Support
+
+So far it's only tested on Python 3.8 and Python 3.9
+
+## Installation
+
+    pip install python-optimus
+
+## Usage
+
+Basic usage:
+
+```
+from optimus_ids import Optimus
+my_optimus = Optimus(
+    prime=<your prime number>
+)
+my_int_id = <some id you have>
+my_int_id_hashed = my_optimus.encode(my_int_id)
+assert my_int_id == my_optimus.decode(my_int_id_hashed)
+```
+
+The caveat with the usage above is that every time you create your `Optimus` instance it will have a random component, even with using the same prime, so a proper usage should be like this:
+
+```
+from optimus_ids import Optimus
+my_optimus = Optimus(
+    prime=<your prime number>,
+    random=<some random number>
+)
+my_int_id = <some id you have>
+my_int_id_hashed = my_optimus.encode(my_int_id)
+assert my_int_id == my_optimus.decode(my_int_id_hashed)
+
+To generate a random number you could do this:
+```
+
+```
+from optimus_ids import rand_n, MAX_64_INT  # use 32 instead of 64 if you want to
+my_random_number = rand_n(MAX_64_INT - 1)
+```
+
+You can also generate an `Optimus` intance and then keep its `prime`, `inverese` and `random` properties stored, so you can always configure a new instance with the same components, or even pickle it:
+
+```
+from optimus_ids import generate, Optimus
+my_optimus = generate()
+
+# store the following variables or pickle the my_optimus variable
+prime = my_optimus.prime
+inverse = my_optimus.inverse
+random = my_optimus.random
+bitlength = my_optimus.bitlength
+
+# create a new instance with the same parameters or unpickle an instance
+my_other_optimus = Optimus(
+    prime=prime,
+    inverse=inverse,
+    random=random,
+    bitlength=bitlength,
+)
+assert my_optimus.encode(42) == my_other_optimus.encode(42)
+assert my_optimus.decode(my_other_optimus.encode(42)) == my_other_optimus.decode(my_optimus.encode(42))
+```
+
+**NOTE** for the generate function to work, it needs data, the data is large, and not available with the package, the data should be downloaded from [here](https://github.com/pjebs/optimus-go-primes) and the path to it is passed to the `generate` function. By default it expects the data to be in a folder called `optimus-primes` in the current working directory.
+
+```
+├── your-app.py
+├── ...
+└── optimus-primes
+    ├── p1.txt
+    ├── p2.txt
+    ├── ...
+    └── p50.txt
+```

optimus_ids/__init__.py

@@ -0,0 +1,65 @@
+import secrets
+
+from typing import Union
+from pathlib import Path
+
+MAX_64_INT = 2 ** 63 - 1
+MAX_32_INT = 2 ** 31 - 1
+
+
+class Optimus:
+    prime: int
+    inverse: int
+    random: int
+    max_int: int
+
+    def __init__(self,
+                 prime: int,
+                 inverse: int = None,
+                 random: int = None,
+                 bitlength: int = 64):
+        if bitlength not in (32, 64):
+            raise ValueError('bitlength can only be 32 or 64')
+        self.max_int = bitlength == 32 and MAX_32_INT or MAX_64_INT
+        self.prime = prime
+        if inverse is None:
+            inverse = mod_inverse(prime, self.max_int)
+        self.inverse = inverse
+        if random is None:
+            random = rand_n(self.max_int - 1)
+        self.random = random
+
+    def encode(self, n: int) -> int:
+        return ((n * self.prime) & self.max_int) ^ self.random
+
+    def decode(self, n: int) -> int:
+        return ((n ^ self.random) * self.inverse) & self.max_int
+
+
+def mod_inverse(n: int, p: int) -> int:
+    return pow(n, -1, p + 1)
+
+
+def generate(
+    path_to_primes: Union[str, Path] = 'optimus-primes',
+    bitlength: int = 64
+) -> Optimus:
+    if bitlength not in (32, 64):
+        raise ValueError('bitlength can only be 32 or 64')
+    if isinstance(path_to_primes, str):
+        path_to_primes = Path(path_to_primes)
+    if not (path_to_primes.exists() and path_to_primes.is_dir()):
+        raise ValueError(
+            f'{str(path_to_primes)} does not exist or is not a directory'
+        )
+    n = rand_n(50)
+    input_file = str(path_to_primes.joinpath(f'p{n}.txt').absolute())
+    line_number = rand_n(1_000_000)
+    with open(input_file, 'r') as f:
+        for i in range(line_number):
+            f.readline()
+        return Optimus(int(f.readline().strip()), bitlength=bitlength)
+
+
+def rand_n(n: int) -> int:
+    return secrets.randbelow(n) + 1

setup.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python
+# coding=utf-8
+
+import os
+
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="python-optimus",
+    version="1.0.0",
+    author="Abdullah Diab",
+    author_email="[email protected]",
+    maintainer="Abdullah Diab",
+    maintainer_email="[email protected]",
+    description="Transform internal id's to "
+                "obfuscated integers using Knuth's integer hash",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/mpcabd/python-optimus",
+    packages=find_packages(),
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires='>=3.8',
+    platforms="ALL",
+    license="MIT",
+    keywords="hashing hashids optimus knuth",
+)

tests/test-optimus.py

@@ -0,0 +1,99 @@
+import itertools
+import unittest
+import secrets
+import pathlib
+
+import optimus_ids
+
+
+class TestOptimus(unittest.TestCase):
+
+    def test_mod_inverse(self):
+        self.assertEqual(
+            optimus_ids.mod_inverse(309779747, optimus_ids.MAX_32_INT),
+            49560203
+        )
+
+    def test_validation(self):
+        with self.assertRaises(ValueError):
+            o = optimus_ids.Optimus(prime=5, bitlength=16)
+
+        with self.assertRaises(ValueError):
+            o = optimus_ids.generate(bitlength=16)
+
+        with self.assertRaises(ValueError):
+            optimus_ids.generate(path_to_primes='invalid-path')
+
+    def test_generation(self):
+        path = pathlib.Path('optimus-primes')
+        if not (path.exists() and path.is_dir()):
+            self.skipTest('optimus-primes not available for generation')
+
+        o64 = optimus_ids.generate()
+        o32 = optimus_ids.generate(bitlength=32)
+
+        self.assertEqual(o64.decode(o64.encode(42)), 42)
+        self.assertEqual(o32.decode(o32.encode(42)), 42)
+
+    def test_encoding(self):
+        optimus_instances = [
+            optimus_ids.Optimus(
+                prime=309779747,
+                inverse=49560203,
+                random=57733611,
+                bitlength=32
+            ),
+            optimus_ids.Optimus(
+                prime=684934207,
+                inverse=1505143743,
+                random=846034763,
+                bitlength=32
+            ),
+            optimus_ids.Optimus(
+                prime=743534599,
+                inverse=1356791223,
+                random=1336232185,
+                bitlength=32
+            ),
+            optimus_ids.Optimus(
+                prime=54661037,
+                inverse=1342843941,
+                random=576322863,
+                bitlength=32
+            ),
+            optimus_ids.Optimus(
+                prime=198194831,
+                inverse=229517423,
+                random=459462336,
+                bitlength=32
+            ),
+            optimus_ids.Optimus(
+                prime=198194831,
+                random=459462336,
+                bitlength=32
+            ),
+        ]
+
+        for i in range(5):
+            o = optimus_instances[i]
+            c = 10
+            h = 100
+            y = list(itertools.chain(
+                range(c),
+                (secrets.randbelow(optimus_ids.MAX_32_INT - 2 * c) + c
+                    for j in range(h)),
+                range(
+                    optimus_ids.MAX_32_INT,
+                    optimus_ids.MAX_32_INT - c - 1,
+                    -1
+                )
+            ))
+            for n in y:
+                encoded = o.encode(n)
+                decoded = o.decode(encoded)
+                with self.subTest(i=i, n=n):
+                    self.assertEqual(decoded, n)
+
+
+if __name__ == '__main__':
+    unittest.main()

tox.ini

@@ -0,0 +1,21 @@
+# tox (https://tox.readthedocs.io/) is a tool for running tests
+# in multiple virtualenvs. This configuration file will run the
+# test suite on all supported python versions. To use it, "pip install tox"
+# and then run "tox" from this directory.
+
+[tox]
+envlist = py38,py39
+
+[testenv]
+allowlist_externals =
+	ln
+deps =
+    pytest
+commands =
+    python -m pytest
+commands_pre =
+	- ln -s {toxinidir}/optimus-primes {toxworkdir}/optimus-primes
+
+[pytest]
+testpaths = tests
+python_files = test*.py