Refine docstrings and improve API reference

docs/api.md

@@ -0,0 +1,73 @@
+# API Reference
+
+```{caution}
+  This reference contains functions that are not yet released in the stable
+  version.
+```
+
+## Functions for immutables
+
+The following functions are used to hash immutable types, specifically
+`bytes` and `str`. String inputs are automatically converted to `bytes` using
+UTF-8 encoding before hashing.
+
+```{eval-rst}
+.. autofunction:: mmh3.hash
+.. autofunction:: mmh3.hash128
+.. autofunction:: mmh3.hash64
+.. autofunction:: mmh3.hash_bytes
+```
+
+## Functions for Buffer
+
+The following functions are used to hash types that implement the buffer
+protocol such as `bytes`, `bytearray`, `memoryview`, and `numpy` arrays.
+String inputs are also supported and are automatically converted to `bytes`
+using UTF-8 encoding before hashing.
+
+The buffer protocol,
+[originally implemented as a part of Python/C API](https://docs.python.org/3/c-api/buffer.html),
+was formally defined as a Python-level API in
+[PEP 688](https://peps.python.org/pep-0688/)
+in 2022 and its corresponding type hint was introduced as
+[collections.abc.Buffer](https://docs.python.org/3/library/collections.abc.html#collections.abc.Buffer)
+in Python 3.12. For earlier Python versions, `mmh3` uses a type alias for the
+type hint
+[\_typeshed.ReadableBuffer](https://github.com/python/typeshed/blob/d326c9bd424ad60c2b63c2ca1c5c1006c61c3562/stdlib/_typeshed/__init__.pyi#L281),
+which is itself an alias for
+[typing_extensions.Buffer](https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.Buffer),
+the backported type hint for `collections.abc.Buffer`.
+
+```{eval-rst}
+.. autofunction:: mmh3.hash_from_buffer
+.. autofunction:: mmh3.mmh3_32_digest
+.. autofunction:: mmh3.mmh3_32_sintdigest
+.. autofunction:: mmh3.mmh3_32_uintdigest
+.. autofunction:: mmh3.mmh3_x64_128_digest
+.. autofunction:: mmh3.mmh3_x64_128_sintdigest
+.. autofunction:: mmh3.mmh3_x64_128_stupledigest
+.. autofunction:: mmh3.mmh3_x64_128_uintdigest
+.. autofunction:: mmh3.mmh3_x64_128_utupledigest
+.. autofunction:: mmh3.mmh3_x86_128_digest
+.. autofunction:: mmh3.mmh3_x86_128_sintdigest
+.. autofunction:: mmh3.mmh3_x86_128_stupledigest
+.. autofunction:: mmh3.mmh3_x86_128_uintdigest
+.. autofunction:: mmh3.mmh3_x86_128_utupledigest
+```
+
+## Hasher Classes
+
+```{eval-rst}
+.. autoclass:: mmh3.mmh3_32
+   :members:
+```
+
+```{eval-rst}
+.. autoclass:: mmh3.mmh3_x64_128
+   :members:
+```
+
+```{eval-rst}
+.. autoclass:: mmh3.mmh3_x86_128
+   :members:
+```

docs/conf.py

@@ -17,7 +17,12 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "myst_parser"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+    "myst_parser",
+]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
@@ -30,3 +35,8 @@
 html_theme_options = {
     "github_url": "https://github.com/hajimes/mmh3",
 }
+
+# -- Options for autodoc -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+
+autodoc_member_order = "groupwise"

pyproject.toml

@@ -36,7 +36,8 @@ test = [
 docs = [
   "myst-parser == 4.0.0",
   "shibuya == 2024.8.30",
-  "sphinx == 8.0.2"
+  "sphinx == 8.0.2",
+  "sphinx-copybutton == 0.5.2"
 ]
 benchmark = [
   "pymmh3 == 0.0.5",

src/mmh3/__init__.pyi

@@ -1,52 +1,52 @@
 # to use list, tuple, dict ... in Python 3.7 and 3.8
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Union, final
+import sys
+from typing import Union, final
 
-if TYPE_CHECKING:
-    from _typeshed import ReadableBuffer
+if sys.version_info >= (3, 12):
+    from collections.abc import Buffer
+else:
+    from _typeshed import ReadableBuffer as Buffer
 
-HashableImmutable = Union[str, bytes]
-HashableBuffer = Union[HashableImmutable, ReadableBuffer]
-
-def hash(key: HashableImmutable, seed: int = 0, signed: bool = True) -> int: ...
+def hash(key: Union[bytes, str], seed: int = 0, signed: bool = True) -> int: ...
 def hash_from_buffer(
-    key: HashableBuffer, seed: int = 0, signed: bool = True
+    key: Union[Buffer, str], seed: int = 0, signed: bool = True
 ) -> int: ...
 def hash64(
-    key: HashableImmutable, seed: int = 0, x64arch: bool = True, signed: bool = True
+    key: Union[bytes, str], seed: int = 0, x64arch: bool = True, signed: bool = True
 ) -> tuple[int, int]: ...
 def hash128(
-    key: HashableImmutable, seed: int = 0, x64arch: bool = True, signed: bool = False
+    key: Union[bytes, str], seed: int = 0, x64arch: bool = True, signed: bool = False
 ) -> int: ...
 def hash_bytes(
-    key: HashableImmutable, seed: int = 0, x64arch: bool = True
+    key: Union[bytes, str], seed: int = 0, x64arch: bool = True
 ) -> bytes: ...
-def mmh3_32_digest(key: HashableBuffer, seed: int = 0) -> bytes: ...
-def mmh3_32_sintdigest(key: HashableBuffer, seed: int = 0) -> int: ...
-def mmh3_32_uintdigest(key: HashableBuffer, seed: int = 0) -> int: ...
-def mmh3_x64_128_digest(key: HashableBuffer, seed: int = 0) -> bytes: ...
-def mmh3_x64_128_sintdigest(key: HashableBuffer, seed: int = 0) -> int: ...
-def mmh3_x64_128_uintdigest(key: HashableBuffer, seed: int = 0) -> int: ...
+def mmh3_32_digest(key: Union[Buffer, str], seed: int = 0) -> bytes: ...
+def mmh3_32_sintdigest(key: Union[Buffer, str], seed: int = 0) -> int: ...
+def mmh3_32_uintdigest(key: Union[Buffer, str], seed: int = 0) -> int: ...
+def mmh3_x64_128_digest(key: Union[Buffer, str], seed: int = 0) -> bytes: ...
+def mmh3_x64_128_sintdigest(key: Union[Buffer, str], seed: int = 0) -> int: ...
+def mmh3_x64_128_uintdigest(key: Union[Buffer, str], seed: int = 0) -> int: ...
 def mmh3_x64_128_stupledigest(
-    key: HashableBuffer, seed: int = 0
+    key: Union[Buffer, str], seed: int = 0
 ) -> tuple[int, int]: ...
 def mmh3_x64_128_utupledigest(
-    key: HashableBuffer, seed: int = 0
+    key: Union[Buffer, str], seed: int = 0
 ) -> tuple[int, int]: ...
-def mmh3_x86_128_digest(key: HashableBuffer, seed: int = 0) -> bytes: ...
-def mmh3_x86_128_sintdigest(key: HashableBuffer, seed: int = 0) -> int: ...
-def mmh3_x86_128_uintdigest(key: HashableBuffer, seed: int = 0) -> int: ...
+def mmh3_x86_128_digest(key: Union[Buffer, str], seed: int = 0) -> bytes: ...
+def mmh3_x86_128_sintdigest(key: Union[Buffer, str], seed: int = 0) -> int: ...
+def mmh3_x86_128_uintdigest(key: Union[Buffer, str], seed: int = 0) -> int: ...
 def mmh3_x86_128_stupledigest(
-    key: HashableBuffer, seed: int = 0
+    key: Union[Buffer, str], seed: int = 0
 ) -> tuple[int, int]: ...
 def mmh3_x86_128_utupledigest(
-    key: HashableBuffer, seed: int = 0
+    key: Union[Buffer, str], seed: int = 0
 ) -> tuple[int, int]: ...
 
 class Hasher:
     def __init__(self, seed: int = 0) -> None: ...
-    def update(self, input: ReadableBuffer) -> None: ...
+    def update(self, data: Buffer) -> None: ...
     def digest(self) -> bytes: ...
     def sintdigest(self) -> int: ...
     def uintdigest(self) -> int: ...