From 5b4aa1e29a42a132d497ca7cdb7a6a6640ce2561 Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Mon, 8 Mar 2021 15:56:12 -0600
Subject: [PATCH] Document persistent_dict.KeyBuilder
---
pytools/persistent_dict.py | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/pytools/persistent_dict.py b/pytools/persistent_dict.py
index c559299..0047aa9 100644
--- a/pytools/persistent_dict.py
+++ b/pytools/persistent_dict.py
@@ -173,6 +173,22 @@ class ItemDirManager(CleanupBase):
# {{{ key generation
class KeyBuilder:
+ """A (stateless) object that computes hashes of objects fed to it. Subclassing
+ this class permits customizing the computation of hash keys.
+
+ .. automethod:: __call__
+ .. automethod:: rec
+ .. staticmethod:: new_hash()
+
+ Return a new hash instance following the protocol of the ones
+ from :mod:`hashlib`. This will permit switching to different
+ hash algorithms in the future. Subclasses are expected to use
+ this to create new hashes. Not doing so is deprecated and
+ may stop working as early as 2022.
+
+ .. versionadded:: 2021.1.3
+ """
+
# this exists so that we can (conceivably) switch algorithms at some point
# down the road
new_hash = hashlib.sha256
--
GitLab