tweak comments

python · AA-Turner · May 12, 2025 · May 10, 2025 · May 10, 2025 · May 10, 2025
commit bb6c416052e164d82e47491156221941d9fa8b1f
@@ -288,8 +288,8 @@ def test_unknown_compression_parameter(self):
         KEY = 100001234
         option = {CompressionParameter.compression_level: 10,
                   KEY: 200000000}
-        pattern = r'Zstd compression parameter.*?"unknown parameter \(key %d\)"' \
-                  % KEY
+        pattern = (r'Invalid zstd compression parameter.*?'
+                   fr'"unknown parameter \(key {KEY}\)"')
         with self.assertRaisesRegex(ZstdError, pattern):
             ZstdCompressor(options=option)
 
@@ -420,8 +420,8 @@ def test_unknown_decompression_parameter(self):
         KEY = 100001234
         options = {DecompressionParameter.window_log_max: DecompressionParameter.window_log_max.bounds()[1],
                   KEY: 200000000}
-        pattern = r'Zstd decompression parameter.*?"unknown parameter \(key %d\)"' \
-                  % KEY
+        pattern = (r'Invalid zstd decompression parameter.*?'
+                   fr'"unknown parameter \(key {KEY}\)"')
         with self.assertRaisesRegex(ZstdError, pattern):
             ZstdDecompressor(options=options)
 

@@ -149,7 +149,7 @@ set_parameter_error(const _zstd_state* const state, int is_compress,
     }
     if (ZSTD_isError(bounds.error)) {
         PyErr_Format(state->ZstdError,
-                     "Zstd %s parameter \"%s\" is invalid.",
+                     "Invalid zstd %s parameter \"%s\".",
                      type, name);
         return;
     }
@@ -184,13 +184,13 @@ _zstd.train_dict
         The size of the dictionary.
     /
 
-Internal function, train a Zstandard dictionary on sample data.
+Train a Zstandard dictionary on sample data.
 [clinic start generated code]*/
 
 static PyObject *
 _zstd_train_dict_impl(PyObject *module, PyBytesObject *samples_bytes,
                       PyObject *samples_sizes, Py_ssize_t dict_size)
-/*[clinic end generated code: output=8e87fe43935e8f77 input=829e31fbbf3454b0]*/
+/*[clinic end generated code: output=8e87fe43935e8f77 input=d20dedb21c72cb62]*/
 {
     // TODO(emmatyping): The preamble and suffix to this function and _finalize_dict
     // are pretty similar. We should see if we can refactor them to share that code.
@@ -255,7 +255,7 @@ _zstd_train_dict_impl(PyObject *module, PyBytesObject *samples_bytes,
                                      chunk_sizes, (uint32_t)chunks_number);
     Py_END_ALLOW_THREADS
 
-    /* Check zstd dict error */
+    /* Check Zstandard dict error */
     if (ZDICT_isError(zstd_ret)) {
         _zstd_state* const mod_state = get_zstd_state(module);
         set_zstd_error(mod_state, ERR_TRAIN_DICT, zstd_ret);
@@ -289,18 +289,18 @@ _zstd.finalize_dict
     dict_size: Py_ssize_t
         The size of the dictionary.
     compression_level: int
-        Optimize for a specific zstd compression level, 0 means default.
+        Optimize for a specific Zstandard compression level, 0 means default.
     /
 
-Internal function, finalize a Zstandard dictionary.
+Finalize a Zstandard dictionary.
 [clinic start generated code]*/
 
 static PyObject *
 _zstd_finalize_dict_impl(PyObject *module, PyBytesObject *custom_dict_bytes,
                          PyBytesObject *samples_bytes,
                          PyObject *samples_sizes, Py_ssize_t dict_size,
                          int compression_level)
-/*[clinic end generated code: output=f91821ba5ae85bda input=11af97dcc7608059]*/
+/*[clinic end generated code: output=f91821ba5ae85bda input=3c7e2480aa08fb56]*/
 {
     Py_ssize_t chunks_number;
     size_t *chunk_sizes = NULL;
@@ -357,7 +357,7 @@ _zstd_finalize_dict_impl(PyObject *module, PyBytesObject *custom_dict_bytes,
 
     /* Parameters */
 
-    /* Optimize for a specific zstd compression level, 0 means default. */
+    /* Optimize for a specific Zstandard compression level, 0 means default. */
     params.compressionLevel = compression_level;
     /* Write log to stderr, 0 = none. */
     params.notificationLevel = 0;
@@ -373,7 +373,7 @@ _zstd_finalize_dict_impl(PyObject *module, PyBytesObject *custom_dict_bytes,
                         (uint32_t)chunks_number, params);
     Py_END_ALLOW_THREADS
 
-    /* Check zstd dict error */
+    /* Check Zstandard dict error */
     if (ZDICT_isError(zstd_ret)) {
         _zstd_state* const mod_state = get_zstd_state(module);
         set_zstd_error(mod_state, ERR_FINALIZE_DICT, zstd_ret);
@@ -404,12 +404,12 @@ _zstd.get_param_bounds
     is_compress: bool
         True for CompressionParameter, False for DecompressionParameter.
 
-Internal function, get CompressionParameter/DecompressionParameter bounds.
+Get CompressionParameter/DecompressionParameter bounds.
 [clinic start generated code]*/
 
 static PyObject *
 _zstd_get_param_bounds_impl(PyObject *module, int parameter, int is_compress)
-/*[clinic end generated code: output=4acf5a876f0620ca input=84e669591e487008]*/
+/*[clinic end generated code: output=4acf5a876f0620ca input=45742ef0a3531b65]*/
 {
     ZSTD_bounds bound;
     if (is_compress) {
@@ -439,14 +439,12 @@ _zstd.get_frame_size
         A bytes-like object, it should start from the beginning of a frame,
         and contains at least one complete frame.
 
-Get the size of a zstd frame, including frame header and 4-byte checksum if it has one.
-
-It will iterate all blocks' headers within a frame, to accumulate the frame size.
+Get the size of a Zstandard frame, including the header and optional checksum.
 [clinic start generated code]*/
 
 static PyObject *
 _zstd_get_frame_size_impl(PyObject *module, Py_buffer *frame_buffer)
-/*[clinic end generated code: output=a7384c2f8780f442 input=7d3ad24311893bf3]*/
+/*[clinic end generated code: output=a7384c2f8780f442 input=3b9f73f8c8129d38]*/
 {
     size_t frame_size;
 
@@ -469,14 +467,14 @@ _zstd_get_frame_size_impl(PyObject *module, Py_buffer *frame_buffer)
 _zstd.get_frame_info
 
     frame_buffer: Py_buffer
-        A bytes-like object, containing the header of a zstd frame.
+        A bytes-like object, containing the header of a Zstandard frame.
 
-Internal function, get zstd frame infomation from a frame header.
+Get Zstandard frame infomation from a frame header.
 [clinic start generated code]*/
 
 static PyObject *
 _zstd_get_frame_info_impl(PyObject *module, Py_buffer *frame_buffer)
-/*[clinic end generated code: output=56e033cf48001929 input=1816f14656b6aa22]*/
+/*[clinic end generated code: output=56e033cf48001929 input=94b240583ae22ca5]*/
 {
     uint64_t decompressed_size;
     uint32_t dict_id;
@@ -515,13 +513,13 @@ _zstd.set_parameter_types
     d_parameter_type: object(subclass_of='&PyType_Type')
         DecompressionParameter IntEnum type object
 
-Internal function, set CompressionParameter/DecompressionParameter types for validity check.
+Set CompressionParameter and DecompressionParameter types for validity check.
 [clinic start generated code]*/
 
 static PyObject *
 _zstd_set_parameter_types_impl(PyObject *module, PyObject *c_parameter_type,
                                PyObject *d_parameter_type)
-/*[clinic end generated code: output=f3313b1294f19502 input=30402523871b8280]*/
+/*[clinic end generated code: output=f3313b1294f19502 input=75d7a953580fae5f]*/
 {
     _zstd_state* const mod_state = get_zstd_state(module);
 

diff --git a/Modules/_zstd/clinic/_zstdmodule.c.h b/Modules/_zstd/clinic/_zstdmodule.c.h
diff --git a/Modules/_zstd/clinic/compressor.c.h b/Modules/_zstd/clinic/compressor.c.h
diff --git a/Modules/_zstd/clinic/decompressor.c.h b/Modules/_zstd/clinic/decompressor.c.h
diff --git a/Modules/_zstd/clinic/zstddict.c.h b/Modules/_zstd/clinic/zstddict.c.h
@@ -115,7 +115,7 @@ _zstd_set_c_parameters(ZstdCompressor *self, PyObject *level_or_options,
                 self->compression_level = value_v;
             }
             else if (key_v == ZSTD_c_nbWorkers) {
-                /* From zstd library doc:
+                /* From the zstd library docs:
                    1. When nbWorkers >= 1, triggers asynchronous mode when
                       used with ZSTD_compressStream2().
                    2, Default value is `0`, aka "single-threaded mode" : no
@@ -319,7 +319,7 @@ _zstd.ZstdCompressor.__new__ as _zstd_ZstdCompressor_new
     options: object = None
         A dict object that contains advanced compression parameters.
     zstd_dict: object = None
-        A ZstdDict object, a pre-trained zstd dictionary.
+        A ZstdDict object, a pre-trained Zstandard dictionary.
 
 Create a compressor object for compressing data incrementally.
 
@@ -330,7 +330,7 @@ function instead.
 static PyObject *
 _zstd_ZstdCompressor_new_impl(PyTypeObject *type, PyObject *level,
                               PyObject *options, PyObject *zstd_dict)
-/*[clinic end generated code: output=cdef61eafecac3d7 input=b9ea61ecafbb1b1e]*/
+/*[clinic end generated code: output=cdef61eafecac3d7 input=92de0211ae20ffdc]*/
 {
     ZstdCompressor* self = PyObject_GC_New(ZstdCompressor, type);
     if (self == NULL) {
@@ -371,7 +371,7 @@ _zstd_ZstdCompressor_new_impl(PyTypeObject *type, PyObject *level,
         }
     }
 
-    /* Load zstd dictionary to compression context */
+    /* Load Zstandard dictionary to compression context */
     self->dict = NULL;
     if (zstd_dict != Py_None) {
         if (_zstd_load_c_dict(self, zstd_dict) < 0) {
@@ -446,7 +446,7 @@ compress_impl(ZstdCompressor *self, Py_buffer *data,
     }
 
 
-    /* zstd stream compress */
+    /* Zstandard stream compress */
     while (1) {
         Py_BEGIN_ALLOW_THREADS
         zstd_ret = ZSTD_compressStream2(self->cctx, &out, &in, end_directive);
@@ -510,7 +510,7 @@ compress_mt_continue_impl(ZstdCompressor *self, Py_buffer *data)
         goto error;
     }
 
-    /* zstd stream compress */
+    /* Zstandard stream compress */
     while (1) {
         Py_BEGIN_ALLOW_THREADS
         do {
@@ -619,14 +619,14 @@ _zstd.ZstdCompressor.flush
 
 Finish the compression process.
 
-Flush any remaining data left in internal buffers. Since zstd data consists
-of one or more independent frames, the compressor object can still be used
-after this method is called.
+Flush any remaining data left in internal buffers. Since Zstandard data
+consists of one or more independent frames, the compressor object can still
+be used after this method is called.
 [clinic start generated code]*/
 
 static PyObject *
 _zstd_ZstdCompressor_flush_impl(ZstdCompressor *self, int mode)
-/*[clinic end generated code: output=b7cf2c8d64dcf2e3 input=a766870301932b85]*/
+/*[clinic end generated code: output=b7cf2c8d64dcf2e3 input=0ab19627f323cdbc]*/
 {
     PyObject *ret;