Fix interface compatibility with blake3 package.

Touched up the blake3 object interface so it's a better match
with the the "blake3" package on PyPI:
  * derive_key_context is now a (Unicode) string.
  * Added a reset() method.
  * Enforce that key, if specified, is exactly 32 bytes.
  * Error strings used in exceptions are converging with what's
    in the "blake3" package.

Also, improved the setup.py build logic:
  * It now preserves the .o files from one build to another.
  * It does time stamp comparisons, so it rebuilds the .o file
    if it's out of date.
  * It remembers if building an extension completely failed.
In short, it now behaves completely properly like a normal "make".
It never extraneously re-tries a compilation.

Author: larryhastings

Lib/test/test_hashlib.py

@@ -819,7 +819,7 @@ def test_blake3_vectors(self):
             test_vectors = json.load(f)
 
         blake3_key = test_vectors['key'].encode('ascii')
-        blake3_derive_key_context = test_vectors['context_string'].encode('ascii')
+        blake3_derive_key_context = test_vectors['context_string']
 
         def test(case):
             nonlocal data

Modules/_blake3/blake3_impl.c

@@ -58,21 +58,31 @@ _blake3.blake3.__new__ as py_blake3_new
     /
     *
     key: Py_buffer(c_default="NULL", py_default="b''") = None
-    derive_key_context: Py_buffer(c_default="NULL", py_default="b''") = None
-    max_threads: size_t = 1
+    derive_key_context: unicode(c_default="NULL") = None
+    max_threads: Py_ssize_t = -1
     usedforsecurity: bool = True
 
 Return a new BLAKE3 hash object.
 [clinic start generated code]*/
 
 static PyObject *
 py_blake3_new_impl(PyTypeObject *type, PyObject *data, Py_buffer *key,
-                   Py_buffer *derive_key_context, size_t max_threads,
+                   PyObject *derive_key_context, Py_ssize_t max_threads,
                    int usedforsecurity)
-/*[clinic end generated code: output=6e24ea74302a9e97 input=3d50acf8631d64ae]*/
+/*[clinic end generated code: output=5520c7ccfcc0ea6c input=484a9211624e61a2]*/
 {
-    if ((key->obj != NULL) && (derive_key_context->obj != NULL)) {
-        PyErr_SetString(PyExc_ValueError, "cannot specify both key and derive_key_context");
+    if ((derive_key_context != NULL) && !PyUnicode_GetLength(derive_key_context)) {
+        PyErr_SetString(PyExc_ValueError, "empty derive_key_context string is invalid");
+        return NULL;
+    }
+
+    if ((key->obj != NULL) && (derive_key_context != NULL)) {
+        PyErr_SetString(PyExc_ValueError, "key and derive_key_context can't be used together");
+        return NULL;
+    }
+
+    if ((max_threads < 1) && (max_threads != -1)) {
+        PyErr_SetString(PyExc_ValueError, "invalid value for max_threads");
         return NULL;
     }
 
@@ -83,19 +93,22 @@ py_blake3_new_impl(PyTypeObject *type, PyObject *data, Py_buffer *key,
 
     /* Initialize with key */
     if ((key->obj != NULL) && key->len) {
-        if (key->len > BLAKE3_KEY_LEN) {
-            PyErr_Format(PyExc_ValueError,
-                "maximum key length is %d bytes",
-                BLAKE3_KEY_LEN);
+        if (key->len != BLAKE3_KEY_LEN) {
+            PyErr_SetString(PyExc_ValueError, "key must be exactly 32 bytes");
             goto error;
         }
 
         uint8_t key_array[BLAKE3_KEY_LEN];
         memset(key_array, 0, sizeof(key_array));
         memcpy(key_array, key->buf, key->len);
         blake3_hasher_init_keyed(&self->self, key_array);
-    } else if ((derive_key_context->obj != NULL) && derive_key_context->len) {
-        blake3_hasher_init_derive_key_raw(&self->self, derive_key_context->buf, derive_key_context->len);
+    } else if (derive_key_context != NULL) {
+        Py_ssize_t length;
+        const char *utf8_key_context = PyUnicode_AsUTF8AndSize(derive_key_context, &length);
+        if (!utf8_key_context) {
+            goto error;
+        }
+        blake3_hasher_init_derive_key_raw(&self->self, utf8_key_context, length);
     } else {
         blake3_hasher_init(&self->self);
     }
@@ -123,6 +136,22 @@ py_blake3_new_impl(PyTypeObject *type, PyObject *data, Py_buffer *key,
     return NULL;
 }
 
+/*[clinic input]
+_blake3.blake3.reset
+
+Reset this hash object to its initial state.
+[clinic start generated code]*/
+
+static PyObject *
+_blake3_blake3_reset_impl(BLAKE3Object *self)
+/*[clinic end generated code: output=d03fd37d58b87017 input=ba958463850a68df]*/
+{
+    ENTER_HASHLIB(self);
+    blake3_hasher_reset(&self->self);
+    LEAVE_HASHLIB(self);
+    Py_RETURN_NONE;
+}
+
 /*[clinic input]
 _blake3.blake3.copy
 
@@ -256,10 +285,11 @@ _blake3_blake3_hexdigest_impl(BLAKE3Object *self, size_t length, size_t seek)
 
 
 static PyMethodDef py_blake3_methods[] = {
-    _BLAKE3_BLAKE3_COPY_METHODDEF
-    _BLAKE3_BLAKE3_DIGEST_METHODDEF
-    _BLAKE3_BLAKE3_HEXDIGEST_METHODDEF
     _BLAKE3_BLAKE3_UPDATE_METHODDEF
+    _BLAKE3_BLAKE3_HEXDIGEST_METHODDEF
+    _BLAKE3_BLAKE3_DIGEST_METHODDEF
+    _BLAKE3_BLAKE3_COPY_METHODDEF
+    _BLAKE3_BLAKE3_RESET_METHODDEF
     {NULL, NULL}
 };
 
@@ -327,7 +357,7 @@ py_blake3_dealloc(PyObject *o)
 {
     BLAKE3Object *self = (BLAKE3Object *)o;
 
-    /* Try not to leave state in memory. */
+    /* Don't leave state in memory. */
     secure_zero_memory(&self->self, sizeof(self->self));
     if (self->lock) {
         PyThread_free_lock(self->lock);

Modules/_blake3/blake3module.c

@@ -108,6 +108,7 @@ blake3_exec(PyObject *m)
     ADD_INT("block_length", BLAKE3_BLOCK_LEN);
     ADD_INT("chunk_length", BLAKE3_CHUNK_LEN);
     ADD_INT("max_depth", BLAKE3_MAX_DEPTH);
+    ADD_INT("AUTO", -1);
 
     ADD_CONSTANT("supports_multithreading", Py_False);
 
@@ -135,4 +136,4 @@ PyMODINIT_FUNC
 PyInit__blake3(void)
 {
     return PyModuleDef_Init(&blake3_module);
-}
+}