Try and add readthedocs generation

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# https://docs.readthedocs.io/en/stable/config-file/v2.html#supported-settings
+
+version: 2
+
+sphinx:
+  builder: html
+
+build:
+  os: "ubuntu-24.04"
+  tools:
+    python: "3.12"
+    rust: "latest"
+
+python:
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,7 @@
+API Documentation
+=================
+
+.. autosummary::
+   :toctree: generated/
+
+   xof_py

docs/conf.py

@@ -0,0 +1,43 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Code location -----------------------------------------------------------
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../"))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'xof-py'
+copyright = '2024, CryptoHack'
+author = 'CryptoHack'
+release = '0.1'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+intersphinx_mapping = {"Python": ("https://docs.python.org/", None)}
+
+autodoc_default_options = {
+    "undoc-members": True,
+    "inherited-members": True,
+}

docs/index.rst

@@ -0,0 +1,22 @@
+.. xof_py documentation master file, created by
+   sphinx-quickstart on Sat Jul 27 23:21:22 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to xof_py's documentation!
+==================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   api
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1 @@
+sphinx-rtd-theme

docs/xof_py.rst

@@ -0,0 +1,10 @@
+xof\_py package
+=================
+
+Module contents
+---------------
+
+.. automodule:: xof_py
+   :members:
+   :undoc-members:
+   :show-inheritance:

speed_test.py

@@ -3,6 +3,7 @@
 from xof_py import Shaker128
 import time
 import os
+from Crypto.Hash.SHAKE128 import SHAKE128_XOF
 
 for _ in range(100):
     absorb = os.urandom(32)
@@ -11,6 +12,15 @@
     b = Shaker128(absorb).finalize().read(n)
     assert a == b
 
+for _ in range(3):
+    absorb = os.urandom(32)
+    xof1 = Shaker128(absorb).finalize()
+    xof2 = Shaker128(absorb).finalize()
+    a = shake_128(absorb).digest(100_000)
+    b = b"".join(xof1.read(1) for _ in range(100_000))
+    c = xof2.read(100_000)
+    assert a == b == c
+
 random.seed(0)
 t0 = time.time()
 xof = Shaker128(b"123").finalize()
@@ -19,4 +29,37 @@
     a = xof.read(n)
 print(f"10_000 calls with class pyo3: {time.time() - t0 }")
 
+random.seed(0)
+t0 = time.time()
+for _ in range(10_000):
+    n = random.randint(1, 5000)
+    a = shake_128(b"123").digest(n)
+print(f"10_000 calls with hashlib: {time.time() - t0 }")
+
 print("-" * 80)
+
+t0 = time.time()
+xof = Shaker128(b"123").finalize()
+for _ in range(1_000_000):
+    a = xof.read(1)
+print(f"1_000_000 single byte reads pyo3: {time.time() - t0 }")
+
+t0 = time.time()
+xof = SHAKE128_XOF()
+xof.update(b"123")
+for _ in range(1_000_000):
+    a = xof.read(1)
+print(f"1_000_000 single byte reads pycryptodome: {time.time() - t0 }")
+
+t0 = time.time()
+xof = Shaker128(b"123").finalize()
+for _ in range(1_000_000):
+    a = xof.read(168)
+print(f"100_000 block reads pyo3: {time.time() - t0 }")
+
+t0 = time.time()
+xof = SHAKE128_XOF()
+xof.update(b"123")
+for _ in range(1_000_000):
+    a = xof.read(168)
+print(f"100_000 block reads pycryptodome: {time.time() - t0 }")

src/lib.rs

@@ -25,6 +25,7 @@ macro_rules! impl_sponge_shaker_classes {
 
         #[pymethods]
         impl $sponge_name {
+            /// Docstring for the read??
             fn read<'py>(&mut self, py: Python<'py>, n: usize) -> PyResult<Bound<'py, PyBytes>> {
                 PyBytes::new_bound_with(py, n, |bytes| {
                     self.xof.read(bytes);
@@ -96,18 +97,21 @@ macro_rules! impl_sponge_shaker_classes {
         impl $shaker_name {
             #[new]
             #[pyo3(signature = (input_bytes = None))]
+            /// Here is some docstrings...
             fn new(input_bytes: Option<&[u8]>) -> Self {
                 let mut hasher = $hasher::default();
                 if let Some(initial_data) = input_bytes {
                     hasher.update(initial_data);
                 }
                 Self { hasher }
             }
-
+
+            /// This should be the absorb one...
             fn absorb(&mut self, input_bytes: &[u8]) {
                 self.hasher.update(input_bytes);
             }
 
+            /// This should be the finalize one...
             fn finalize(&mut self) -> $sponge_name {
                 $sponge_name {
                     xof: self.hasher.finalize_xof_reset(),
@@ -142,7 +146,7 @@ impl_sponge_shaker_classes!(
 
 /// A Python module implemented in Rust.
 #[pymodule]
-fn xof(m: &Bound<'_, PyModule>) -> PyResult<()> {
+fn xof_py(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Sponge128>()?;
     m.add_class::<Shaker128>()?;
     m.add_class::<Sponge256>()?;

xof_py.pyi

@@ -0,0 +1,21 @@
+class Sponge128:
+    def read(n: int) -> bytes:
+        ...
+
+class Shake128:
+    def absorb(input_bytes: bytes) -> None:
+        ...
+
+    def finalize() -> Sponge128:
+        ...
+
+class Sponge256:
+    def read(n: int) -> bytes:
+        ...
+
+class Shake256:
+    def absorb(input_bytes: bytes) -> None:
+        ...
+
+    def finalize() -> Sponge256:
+        ...