From bec000810e9e8f924c1ab8e0205dcbc11674198c Mon Sep 17 00:00:00 2001 From: David Stansby Date: Mon, 28 Oct 2024 22:50:16 +0000 Subject: [PATCH 1/4] Deprecate blosc helper functions --- docs/compression/blosc.rst | 6 ------ numcodecs/blosc.pyx | 26 +++++++++++++++++++------- 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/docs/compression/blosc.rst b/docs/compression/blosc.rst index 4a7681c9..dd87b3ac 100644 --- a/docs/compression/blosc.rst +++ b/docs/compression/blosc.rst @@ -18,15 +18,9 @@ Blosc Helper functions ---------------- -.. autofunction:: init -.. autofunction:: destroy -.. autofunction:: compname_to_compcode .. autofunction:: list_compressors .. autofunction:: get_nthreads .. autofunction:: set_nthreads -.. autofunction:: cbuffer_sizes .. autofunction:: cbuffer_complib -.. autofunction:: cbuffer_metainfo .. autofunction:: compress .. autofunction:: decompress -.. autofunction:: decompress_partial diff --git a/numcodecs/blosc.pyx b/numcodecs/blosc.pyx index 2c43dd04..b7a97b5a 100644 --- a/numcodecs/blosc.pyx +++ b/numcodecs/blosc.pyx @@ -6,6 +6,7 @@ import threading import multiprocessing import os +from deprecated import deprecated from cpython.buffer cimport PyBUF_ANY_CONTIGUOUS, PyBUF_WRITEABLE @@ -95,17 +96,22 @@ def get_mutex(): _importer_pid = os.getpid() -def init(): +def _init(): """Initialize the Blosc library environment.""" blosc_init() +init = deprecated(_init) -def destroy(): + +def _destroy(): """Destroy the Blosc library environment.""" blosc_destroy() -def compname_to_compcode(cname): +destroy = deprecated(_destroy) + + +def _compname_to_compcode(cname): """Return the compressor code associated with the compressor name. If the compressor name is not recognized, or there is not support for it in this build, -1 is returned instead.""" @@ -113,6 +119,8 @@ def compname_to_compcode(cname): cname = cname.encode('ascii') return blosc_compname_to_compcode(cname) +compname_to_compcode = deprecated(_compname_to_compcode) + def list_compressors(): """Get a list of compressors supported in the current build.""" @@ -133,7 +141,7 @@ def set_nthreads(int nthreads): return blosc_set_nthreads(nthreads) -def cbuffer_sizes(source): +def _cbuffer_sizes(source): """Return information about a compressed buffer, namely the number of uncompressed bytes (`nbytes`) and compressed (`cbytes`). It also returns the `blocksize` (which is used internally for doing the compression by blocks). @@ -160,6 +168,7 @@ def cbuffer_sizes(source): return nbytes, cbytes, blocksize +cbuffer_sizes = deprecated(_cbuffer_sizes) def cbuffer_complib(source): """Return the name of the compression library used to compress `source`.""" @@ -180,7 +189,7 @@ def cbuffer_complib(source): return complib -def cbuffer_metainfo(source): +def _cbuffer_metainfo(source): """Return some meta-information about the compressed buffer in `source`, including the typesize, whether the shuffle or bit-shuffle filters were used, and the whether the buffer was memcpyed. @@ -217,11 +226,13 @@ def cbuffer_metainfo(source): return typesize, shuffle, memcpyed +cbuffer_metainfo = deprecated(_cbuffer_metainfo) -def err_bad_cname(cname): +def _err_bad_cname(cname): raise ValueError('bad compressor or compressor not supported: %r; expected one of ' '%s' % (cname, list_compressors())) +err_bad_cname = deprecated(_err_bad_cname) def compress(source, char* cname, int clevel, int shuffle=SHUFFLE, int blocksize=AUTOBLOCKS): @@ -405,7 +416,7 @@ def decompress(source, dest=None): return dest -def decompress_partial(source, start, nitems, dest=None): +def _decompress_partial(source, start, nitems, dest=None): """**Experimental** Decompress data of only a part of a buffer. @@ -478,6 +489,7 @@ def decompress_partial(source, start, nitems, dest=None): return dest +decompress_partial = deprecated(_decompress_partial) # set the value of this variable to True or False to override the # default adaptive behaviour From e6d42987d0aabb298dcfa647a689a6f7a0c1499f Mon Sep 17 00:00:00 2001 From: David Stansby Date: Tue, 3 Dec 2024 08:58:02 +0000 Subject: [PATCH 2/4] Fix calling deprecated functions --- numcodecs/__init__.py | 2 +- numcodecs/blosc.pyx | 6 +++--- numcodecs/tests/test_blosc.py | 10 +++++----- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/numcodecs/__init__.py b/numcodecs/__init__.py index 3e44085c..b4b983ce 100644 --- a/numcodecs/__init__.py +++ b/numcodecs/__init__.py @@ -49,7 +49,7 @@ ncores = multiprocessing.cpu_count() except OSError: # pragma: no cover ncores = 1 -blosc.init() +blosc._init() blosc.set_nthreads(min(8, ncores)) atexit.register(blosc.destroy) diff --git a/numcodecs/blosc.pyx b/numcodecs/blosc.pyx index b7a97b5a..3caa3607 100644 --- a/numcodecs/blosc.pyx +++ b/numcodecs/blosc.pyx @@ -273,7 +273,7 @@ def compress(source, char* cname, int clevel, int shuffle=SHUFFLE, # check valid cname early cname_str = cname.decode('ascii') if cname_str not in list_compressors(): - err_bad_cname(cname_str) + _err_bad_cname(cname_str) # setup source buffer source_buffer = Buffer(source, PyBUF_ANY_CONTIGUOUS) @@ -311,7 +311,7 @@ def compress(source, char* cname, int clevel, int shuffle=SHUFFLE, if compressor_set < 0: # shouldn't happen if we checked against list of compressors # already, but just in case - err_bad_cname(cname_str) + _err_bad_cname(cname_str) # set blocksize blosc_set_blocksize(blocksize) @@ -587,7 +587,7 @@ class Blosc(Codec): def decode_partial(self, buf, int start, int nitems, out=None): '''**Experimental**''' buf = ensure_contiguous_ndarray(buf, self.max_buffer_size) - return decompress_partial(buf, start, nitems, dest=out) + return _decompress_partial(buf, start, nitems, dest=out) def __repr__(self): r = '%s(cname=%r, clevel=%r, shuffle=%s, blocksize=%s)' % \ diff --git a/numcodecs/tests/test_blosc.py b/numcodecs/tests/test_blosc.py index 8c187201..0bc14010 100644 --- a/numcodecs/tests/test_blosc.py +++ b/numcodecs/tests/test_blosc.py @@ -124,12 +124,12 @@ def test_compress_blocksize_default(use_threads): # default blocksize enc = blosc.compress(arr, b'lz4', 1, Blosc.NOSHUFFLE) - _, _, blocksize = blosc.cbuffer_sizes(enc) + _, _, blocksize = blosc._cbuffer_sizes(enc) assert blocksize > 0 # explicit default blocksize enc = blosc.compress(arr, b'lz4', 1, Blosc.NOSHUFFLE, 0) - _, _, blocksize = blosc.cbuffer_sizes(enc) + _, _, blocksize = blosc._cbuffer_sizes(enc) assert blocksize > 0 @@ -140,7 +140,7 @@ def test_compress_blocksize(use_threads, bs): blosc.use_threads = use_threads enc = blosc.compress(arr, b'lz4', 1, Blosc.NOSHUFFLE, bs) - _, _, blocksize = blosc.cbuffer_sizes(enc) + _, _, blocksize = blosc._cbuffer_sizes(enc) assert blocksize == bs @@ -174,7 +174,7 @@ def test_compress_metainfo(dtype, use_threads): blosc.use_threads = use_threads for cname in blosc.list_compressors(): enc = blosc.compress(arr, cname.encode(), 1, shuffle) - typesize, did_shuffle, _ = blosc.cbuffer_metainfo(enc) + typesize, did_shuffle, _ = blosc._cbuffer_metainfo(enc) assert typesize == arr.dtype.itemsize assert did_shuffle == shuffle @@ -186,7 +186,7 @@ def test_compress_autoshuffle(use_threads): blosc.use_threads = use_threads for cname in blosc.list_compressors(): enc = blosc.compress(varr, cname.encode(), 1, Blosc.AUTOSHUFFLE) - typesize, did_shuffle, _ = blosc.cbuffer_metainfo(enc) + typesize, did_shuffle, _ = blosc._cbuffer_metainfo(enc) assert typesize == varr.dtype.itemsize if typesize == 1: assert did_shuffle == Blosc.BITSHUFFLE From 3f1e2fa8a6d71ac469a64072d35bef3745a49c11 Mon Sep 17 00:00:00 2001 From: David Stansby Date: Tue, 3 Dec 2024 09:01:42 +0000 Subject: [PATCH 3/4] Add release notes --- docs/release.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/release.rst b/docs/release.rst index ebbe13d6..5c8f83b9 100644 --- a/docs/release.rst +++ b/docs/release.rst @@ -22,6 +22,20 @@ Breaking changes are now keyword only, to support the updated API. By :user:`Sam Levang `, :issue:`623` +Deprecations +~~~~~~~~~~~~ +The following ``blosc`` funcitons are deprecated, with no replacement. +This is because they are not intended to be public API. + +- ``numcodecs.blosc.init`` +- ``numcodecs.blosc.destroy`` +- ``numcodecs.blosc.compname_to_compcode`` +- ``numcodecs.blosc.cbuffer_sizes`` +- ``numcodecs.blosc.cbuffer_metainfo`` + +In addition, ``numcodecs.blosc.decompress_partial`` is deprecated as +has always been experimental and there is no equivalent in the official +blsoc Python package. Fixes ~~~~~ From c2d10a55cc0f1de4872ccc5c9db78e528d7fd438 Mon Sep 17 00:00:00 2001 From: David Stansby Date: Sat, 4 Jan 2025 15:49:43 +0000 Subject: [PATCH 4/4] Add deprecated dep --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 059a2534..817f138c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -16,6 +16,7 @@ for use in data storage and communication applications.""" readme = "README.rst" dependencies = [ "numpy>=1.24", + "deprecated" ] requires-python = ">=3.11" dynamic = [