numcodecs 0.14.0__tar.gz → 0.15.0__tar.gz

numcodecs-0.15.0/.github/workflows/ci.yaml

@@ -0,0 +1,73 @@
+name: Tests
+
+on: [push, pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        # macos-13 is an intel runner, macos-14 is a arm64 runner
+        platform: [ubuntu-latest, windows-latest, macos-13, macos-14]
+
+    defaults:
+      run:
+        shell: bash -el {0}
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 0 # required for version resolution
+
+      - name: Set up Conda
+        uses: conda-incubator/setup-miniconda@v3.1.0
+        with:
+          channels: conda-forge
+          miniforge-version: latest
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install compilers
+        run: conda install -y c-compiler cxx-compiler
+
+      - name: Install clang
+        if: matrix.platform == 'macos-13'
+        run: conda install -y 'clang>=12.0.1,<17'
+
+      - name: Show conda environment info
+        run: |
+          conda info
+          conda config --show-sources
+          conda list --show-channel-urls
+
+      - name: Install numcodecs
+        run: |
+          export DISABLE_NUMCODECS_AVX2=""
+          python -m pip install -v -e .[test,test_extras,msgpack,crc32c,pcodec,zfpy]
+
+      - name: Install zarr-python
+        # Since zarr v3 requires numpy >= 1.25, on Python 3.11 leave it out
+        # so we can have some tests of our minimum version of numpy (1.24)
+        if: matrix.python-version != '3.11'
+        # TODO: remove --pre option when zarr v3 is out
+        run: python -m pip install --pre zarr>=3.0.0b2
+
+      - name: List installed packages
+        run: python -m pip list
+
+      - name: Run tests
+        shell: "bash -l {0}"
+        run: pytest -v
+
+      - uses: codecov/codecov-action@v5
+        with:
+          fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+          verbose: true

numcodecs-0.15.0/.github/workflows/wheel.yaml

@@ -0,0 +1,98 @@
+name: Wheels
+
+on: [push, pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_wheels:
+    name: Build wheel on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # macos-13 is an intel runner, macos-14 is a arm64 runner
+        os: [ubuntu-latest, windows-latest, macos-13, macos-14]
+    env:
+      CIBW_TEST_COMMAND: python -c "import numcodecs"
+      CIBW_BUILD: "cp311-* cp312-* cp313-*"
+      CIBW_SKIP: "pp* *-musllinux_* *win32 *_i686 *_s390x"
+      # note: CIBW_ENVIRONMENT is now set in pyproject.toml
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - uses: pypa/cibuildwheel@v2.22.0
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - uses: actions/setup-python@v5
+        name: Install Python
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - name: test install
+        run: pip install dist/numcodecs*.tar.gz
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  test_dist_pypi:
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - name: test
+        run: |
+          ls
+          ls dist
+
+  upload_pypi:
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@master
+        with:
+          user: __token__
+          password: ${{ secrets.pypi_password }}
+          # To test: repository_url: https://test.pypi.org/legacy/

numcodecs-0.15.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+exclude: ^fixture/  # files with trailing whitespaces on purpose
+ci:
+  autoupdate_commit_msg: "chore: update pre-commit hooks"
+  autoupdate_schedule: "monthly"
+  autofix_commit_msg: "style: pre-commit fixes"
+  autofix_prs: false
+default_stages: [pre-commit, pre-push]
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+    - id: trailing-whitespace
+    - id: check-yaml
+    - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+    - id: ruff
+      args: ["--fix", "--show-fixes"]
+    - id: ruff-format
+
+  - repo: https://github.com/scientific-python/cookie
+    rev: 2024.08.19
+    hooks:
+    - id: sp-repo-review
+
+  -   repo: https://github.com/pre-commit/mirrors-mypy
+      rev: v1.14.0
+      hooks:
+      -   id: mypy
+          args: [--config-file, pyproject.toml]
+          additional_dependencies: [numpy, pytest, crc32c, zfpy, 'zarr>=3.0.0rc1']

numcodecs-0.15.0/.readthedocs.yaml

@@ -0,0 +1,25 @@
+version: 2
+
+submodules:
+  include: all
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_install:
+      - python -m pip install --pre 'zarr>=3.0.0b2'
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+        - msgpack
+        - zfpy
+        - crc32c

numcodecs-0.15.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.2
+Name: numcodecs
+Version: 0.15.0
+Summary: A Python package providing buffer compression and transformation codecs for use in data storage and communication applications.
+Maintainer-email: Alistair Miles <alimanfoo@googlemail.com>
+License: MIT
+Project-URL: Bug Tracker, https://github.com/zarr-developers/numcodecs/issues
+Project-URL: Changelog, https://numcodecs.readthedocs.io/en/stable/release.html
+Project-URL: Documentation, https://numcodecs.readthedocs.io/
+Project-URL: Homepage, https://github.com/zarr-developers/numcodecs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Requires-Dist: numpy>=1.24
+Requires-Dist: deprecated
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-issues; extra == "docs"
+Requires-Dist: pydata-sphinx-theme; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: test-extras
+Requires-Dist: importlib_metadata; extra == "test-extras"
+Provides-Extra: msgpack
+Requires-Dist: msgpack; extra == "msgpack"
+Provides-Extra: zfpy
+Requires-Dist: zfpy>=1.0.0; extra == "zfpy"
+Provides-Extra: pcodec
+Requires-Dist: pcodec<0.4,>=0.3; extra == "pcodec"
+Provides-Extra: crc32c
+Requires-Dist: crc32c>=2.7; extra == "crc32c"
+
+Numcodecs
+=========
+
+Numcodecs is a Python package providing buffer compression and transformation
+codecs for use in data storage and communication applications.
+
+.. image:: https://readthedocs.org/projects/numcodecs/badge/?version=latest
+    :target: https://numcodecs.readthedocs.io/en/latest/?badge=latest
+
+.. image:: https://github.com/zarr-developers/numcodecs/workflows/Linux%20CI/badge.svg?branch=main
+    :target: https://github.com/zarr-developers/numcodecs/actions?query=workflow%3A%22Linux+CI%22
+
+.. image:: https://github.com/zarr-developers/numcodecs/workflows/OSX%20CI/badge.svg?branch=main
+    :target: https://github.com/zarr-developers/numcodecs/actions?query=workflow%3A%22OSX+CI%22
+
+.. image:: https://github.com/zarr-developers/numcodecs/workflows/Wheels/badge.svg?branch=main
+    :target: https://github.com/zarr-developers/numcodecs/actions?query=workflow%3AWheels
+
+.. image:: https://codecov.io/gh/zarr-developers/numcodecs/branch/main/graph/badge.svg
+    :target: https://codecov.io/gh/zarr-developers/numcodecs

numcodecs-0.15.0/adhoc/blosc_memleak_check.py

@@ -0,0 +1,13 @@
+import sys
+
+import numcodecs
+import numpy as np
+from numpy.testing import assert_array_equal
+
+codec = numcodecs.Blosc()
+data = np.arange(int(sys.argv[1]))
+for _ in range(int(sys.argv[2])):
+    enc = codec.encode(data)
+    dec = codec.decode(enc)
+    arr = np.frombuffer(dec, dtype=data.dtype)
+    assert_array_equal(data, arr)

numcodecs-0.15.0/docs/compression/blosc.rst

@@ -0,0 +1,26 @@
+Blosc
+=====
+.. automodule:: numcodecs.blosc
+
+.. autoclass:: Blosc
+
+    .. autoattribute:: codec_id
+    .. autoattribute:: NOSHUFFLE
+    .. autoattribute:: SHUFFLE
+    .. autoattribute:: BITSHUFFLE
+    .. autoattribute:: AUTOSHUFFLE
+    .. automethod:: encode
+    .. automethod:: decode
+    .. automethod:: get_config
+    .. automethod:: from_config
+    .. automethod:: decode_partial
+
+Helper functions
+----------------
+
+.. autofunction:: list_compressors
+.. autofunction:: get_nthreads
+.. autofunction:: set_nthreads
+.. autofunction:: cbuffer_complib
+.. autofunction:: compress
+.. autofunction:: decompress

numcodecs-0.15.0/docs/contributing.rst

@@ -0,0 +1,300 @@
+Contributing
+============
+
+NumCodecs is a community maintained project. We welcome contributions in the form of bug
+reports, bug fixes, documentation, enhancement proposals and more. This page provides
+information on how best to contribute.
+
+Asking for help
+---------------
+
+If you have a question about how to use NumCodecs, please post your question on
+StackOverflow using the `"numcodecs" tag <https://stackoverflow.com/questions/tagged/numcodecs>`_.
+If you don't get a response within a day or two, feel free to raise a `GitHub issue
+<https://github.com/zarr-developers/numcodecs/issues/new>`_ including a link to your
+StackOverflow question. We will try to respond to questions as quickly as possible, but
+please bear in mind that there may be periods where we have limited time to answer
+questions due to other commitments.
+
+Bug reports
+-----------
+
+If you find a bug, please raise a `GitHub issue
+<https://github.com/zarr-developers/numcodecs/issues/new>`_. Please include the following items in
+a bug report:
+
+1. A minimal, self-contained snippet of Python code reproducing the problem. You can
+   format the code nicely using markdown, e.g.::
+
+
+    ```python
+    >>> import numcodecs
+    >>> codec = numcodecs.Zlib(1)
+    ...
+    ```
+
+2. Information about the version of NumCodecs, along with versions of dependencies and the
+   Python interpreter, and installation information. The version of NumCodecs can be obtained
+   from the ``numcodecs.__version__`` property. Please also state how NumCodecs was installed,
+   e.g., "installed via pip into a virtual environment", or "installed using conda".
+   Information about other packages installed can be obtained by executing ``pip list``
+   (if using pip to install packages) or ``conda list`` (if using conda to install
+   packages) from the operating system command prompt. The version of the Python
+   interpreter can be obtained by running a Python interactive session, e.g.::
+
+    $ python
+    Python 3.8.15 | packaged by conda-forge | (default, Nov 22 2022, 08:49:06)
+    [Clang 14.0.6 ] on darwin
+
+3. An explanation of why the current behaviour is wrong/not desired, and what you
+   expect instead.
+
+Enhancement proposals
+---------------------
+
+If you have an idea about a new feature or some other improvement to NumCodecs, please raise a
+`GitHub issue <https://github.com/zarr-developers/numcodecs/issues/new>`_ first to discuss.
+
+We very much welcome ideas and suggestions for how to improve NumCodecs, but please bear in
+mind that we are likely to be conservative in accepting proposals for new features. The
+reasons for this are that we would like to keep the NumCodecs code base lean and focused on
+a core set of functionalities, and available time for development, review and maintenance
+of new features is limited. But if you have a great idea, please don't let that stop
+you posting it on GitHub, just please don't be offended if we respond cautiously.
+
+Contributing code and/or documentation
+--------------------------------------
+
+Forking the repository
+~~~~~~~~~~~~~~~~~~~~~~
+
+The NumCodecs source code is hosted on GitHub at the following location:
+
+* `https://github.com/zarr-developers/numcodecs <https://github.com/zarr-developers/numcodecs>`_
+
+You will need your own fork to work on the code. Go to the link above and hit
+the "Fork" button. Then clone your fork to your local machine::
+
+    $ git clone --recursive git@github.com:your-user-name/numcodecs.git  # with ``ssh``
+
+or::
+
+    $ git clone --recursive https://github.com/your-user-name/numcodecs.git  # with ``https``
+
+Then ``cd`` into the clone and add the ``upstream`` remote::
+
+    $ cd numcodecs
+    $ git remote add upstream https://github.com/zarr-developers/numcodecs.git
+
+Creating a development environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To work with the NumCodecs source code, it is recommended to set up a Python virtual
+environment and install all NumCodecs dependencies using the same versions as are used by
+the core developers and continuous integration services. Assuming you have a Python
+3 interpreter already installed matching the ``requires-python`` constraint from
+``pyproject.toml``, and you have cloned the NumCodecs source code and your
+current working directory is the root of the repository, you can do something
+like the following::
+
+    $ python3 -m venv ~/pyenv/numcodecs-dev
+    $ source ~/pyenv/numcodecs-dev/bin/activate
+    $ pip install -e .[docs,test,msgpack,zfpy]
+
+To verify that your development environment is working, you can run the unit tests::
+
+    $ pytest -v
+
+Creating a branch
+~~~~~~~~~~~~~~~~~
+
+Before you do any new work or submit a pull request, please open an issue on GitHub to
+report the bug or propose the feature you'd like to add.
+
+It's best to create a new, separate branch for each piece of work you want to do. E.g.::
+
+    git fetch upstream
+    git checkout -b shiny-new-feature upstream/main
+
+This changes your working directory to the 'shiny-new-feature' branch. Keep any changes in
+this branch specific to one bug or feature so it is clear what the branch brings to
+NumCodecs.
+
+To update this branch with latest code from NumCodecs, you can retrieve the changes from
+the main branch and perform a rebase::
+
+    git fetch upstream
+    git rebase upstream/main
+
+This will replay your commits on top of the latest NumCodecs git main. If this leads to
+merge conflicts, these need to be resolved before submitting a pull request.
+Alternatively, you can merge the changes in from upstream/main instead of rebasing,
+which can be simpler::
+
+    git fetch upstream
+    git merge upstream/main
+
+Again, any conflicts need to be resolved before submitting a pull request.
+
+Running the test suite
+~~~~~~~~~~~~~~~~~~~~~~
+
+NumCodecs includes a suite of unit tests, as well as doctests included in function and class
+docstrings. The simplest way to run the unit tests is to invoke::
+
+    $ pytest -v
+
+NumCodecs currently supports Python 6-3.9, so the above command must
+succeed before code can be accepted into the main code base.
+
+All tests are automatically run via Travis (Linux) and AppVeyor (Windows) continuous
+integration services for every pull request. Tests must pass under both services before
+code can be accepted.
+
+Code standards
+~~~~~~~~~~~~~~
+
+All code must conform to the PEP8 standard. Regarding line length, lines up to 100
+characters are allowed, although please try to keep under 90 wherever possible.
+Conformance can be checked by running::
+
+    $ pre-commit run ruff
+
+Test coverage
+~~~~~~~~~~~~~
+
+NumCodecs maintains 100% test coverage under the latest Python stable release (currently
+Python 3.9). Both unit tests and docstring doctests are included when computing
+coverage. Running ``pytest -v`` will automatically run the test suite with coverage
+and produce a coverage report. This should be 100% before code can be accepted into the
+main code base.
+
+When submitting a pull request, coverage will also be collected across all supported
+Python versions via the Codecov service, and will be reported back within the pull
+request. Codecov coverage must also be 100% before code can be accepted.
+
+Documentation
+~~~~~~~~~~~~~
+
+Docstrings for user-facing classes and functions should follow the `numpydoc
+<https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_ standard,
+including sections for Parameters and Examples. All examples will be run as doctests
+under Python 3.9.
+
+NumCodecs uses Sphinx for documentation, hosted on readthedocs.org. Documentation is
+written in the RestructuredText markup language (.rst files) in the ``docs`` folder.
+The documentation consists both of prose and API documentation. All user-facing classes
+and functions should be included in the API documentation. Any changes should also be
+included in the release notes (``docs/release.rst``).
+
+The documentation can be built by running::
+
+     $ cd docs
+     $ make clean; make html
+
+The resulting built documentation will be available in the ``docs/_build/html`` folder.
+
+Development best practices, policies and procedures
+---------------------------------------------------
+
+The following information is mainly for core developers, but may also be of interest to
+contributors.
+
+Merging pull requests
+~~~~~~~~~~~~~~~~~~~~~
+
+Pull requests submitted by an external contributor should be reviewed and approved by at least
+one core developers before being merged. Ideally, pull requests submitted by a core developer
+should be reviewed and approved by at least one other core developers before being merged.
+
+Pull requests should not be merged until all CI checks have passed (Travis, AppVeyor,
+Codecov) against code that has had the latest main merged in.
+
+Compatibility and versioning policies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Because NumCodecs is a data encoding/decoding library, there are two types of compatibility to
+consider: API compatibility and data format compatibility.
+
+API compatibility
+"""""""""""""""""
+
+All functions, classes and methods that are included in the API
+documentation (files under ``docs/api/*.rst``) are considered as part of the NumCodecs
+**public API**, except if they have been documented as an experimental feature, in which case they
+are part of the **experimental API**.
+
+Any change to the public API that does **not** break existing third party
+code importing NumCodecs, or cause third party code to behave in a different way, is a
+**backwards-compatible API change**. For example, adding a new function, class or method is usually
+a backwards-compatible change. However, removing a function, class or method; removing an argument
+to a function or method; adding a required argument to a function or method; or changing the
+behaviour of a function or method, are examples of **backwards-incompatible API changes**.
+
+If a release contains no changes to the public API (e.g., contains only bug fixes or
+other maintenance work), then the micro version number should be incremented (e.g.,
+2.2.0 -> 2.2.1). If a release contains public API changes, but all changes are
+backwards-compatible, then the minor version number should be incremented
+(e.g., 2.2.1 -> 2.3.0). If a release contains any backwards-incompatible public API changes,
+the major version number should be incremented (e.g., 2.3.0 -> 3.0.0).
+
+Backwards-incompatible changes to the experimental API can be included in a minor release,
+although this should be minimised if possible. I.e., it would be preferable to save up
+backwards-incompatible changes to the experimental API to be included in a major release, and to
+stabilise those features at the same time (i.e., move from experimental to public API), rather than
+frequently tinkering with the experimental API in minor releases.
+
+Data format compatibility
+"""""""""""""""""""""""""
+
+Each codec class in NumCodecs exposes a ``codec_id`` attribute, which is an identifier for the
+**format of the encoded data** produced by that codec. Thus it is valid for two or more codec
+classes to expose the same value for the ``codec_id`` attribute if the format of the encoded data
+is identical. The ``codec_id`` is intended to provide a basis for achieving and managing
+interoperability between versions of the NumCodecs package, as well as between NumCodecs and other
+software libraries that aim to provide compatible codec implementations. Currently there is no
+formal specification of the encoded data format corresponding to each ``codec_id``, so the codec
+classes provided in the NumCodecs package should be taken as the reference implementation for a
+given ``codec_id``.
+
+There must be a one-to-one mapping from ``codec_id`` values to encoded data formats, and that
+mapping must not change once the first implementation of a ``codec_id`` has been published within a
+NumCodecs release. If a change is proposed to the encoded data format for a particular type of
+codec, then this must be implemented in NumCodecs via a new codec class exposing a new ``codec_id``
+value.
+
+Note that the NumCodecs test suite includes a data fixture and tests to try and ensure that
+data format compatibility is not accidentally broken. See the
+:func:`test_backwards_compatibility` functions in test modules for each codec for examples.
+
+When to make a release
+~~~~~~~~~~~~~~~~~~~~~~
+
+Ideally, any bug fixes that don't change the public API should be released as soon as
+possible. It is fine for a micro release to contain only a single bug fix.
+
+When to make a minor release is at the discretion of the core developers. There are no
+hard-and-fast rules, e.g., it is fine to make a minor release to make a single new
+feature available; equally, it is fine to make a minor release that includes a number of
+changes.
+
+Major releases obviously need to be given careful consideration, and should be done as
+infrequently as possible, as they will break existing code and/or affect data
+compatibility in some way.
+
+Release procedure
+~~~~~~~~~~~~~~~~~
+
+Checkout and update the main branch::
+
+    $ git checkout main
+    $ git pull
+
+Tag the version (where "X.X.X" stands for the version number, e.g., "2.2.0")::
+
+    $ version=X.X.X
+    $ git tag -a v$version -m v$version
+    $ git push --tags
+
+This will trigger a GitHub Action which will build the source
+distribution as well as wheels for all major platforms.