numcodecs-mask 0.1.0__tar.gz

numcodecs_mask-0.1.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

numcodecs_mask-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the Repository
+        uses: actions/checkout@v6
+
+      - name: Check with ruff
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: check
+
+  fmt:
+    name: Formatting
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the Repository
+        uses: actions/checkout@v6
+
+      - name: Check with ruff
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: "format --diff --check"
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the Repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Setup the Python venv
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest -v
+
+  mypy:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the Repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Setup the Python venv
+        run: uv sync --all-extras --dev
+
+      - name: Typecheck numcodecs-mask
+        run: uv run mypy -p numcodecs_mask

numcodecs_mask-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish
+
+on:
+  release:
+    branch: main
+    types: [released]
+
+jobs:
+  publish:
+    name: Publish to PyPi
+    runs-on: ubuntu-latest
+    environment: publish
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout the Repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build the package
+        run: uv build
+
+      - name: Publish the package to PyPi
+        run: uv publish

numcodecs_mask-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+/.venv
+/.mypy_cache
+/.pytest_cache
+/.ruff_cache
+/uv.lock
+
+/build
+/site
+
+**/__pycache__
+**/*.egg-info

numcodecs_mask-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

numcodecs_mask-0.1.0/.readthedocs.yaml

@@ -0,0 +1,18 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --group docs --link-mode=copy
+    build:
+      html:
+        - python -m properdocs build --clean --site-dir "${READTHEDOCS_OUTPUT}/html"

numcodecs_mask-0.1.0/LICENSE

@@ -0,0 +1,375 @@
+Copyright (c) 2026, Juniper Tyree
+
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

numcodecs_mask-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: numcodecs-mask
+Version: 0.1.0
+Summary: Masking codecs for the `numcodecs` buffer compression API
+License-Expression: MPL-2.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: leb128~=1.0.8
+Requires-Dist: numcodecs-combinators~=0.2.15
+Requires-Dist: numcodecs<0.17,>=0.13.0
+Requires-Dist: numpy~=2.0
+Requires-Dist: typing-extensions~=4.6
+Description-Content-Type: text/markdown
+
+[![image](https://img.shields.io/github/actions/workflow/status/juntyr/numcodecs-mask/ci.yml?branch=main)](https://github.com/juntyr/numcodecs-mask/actions/workflows/ci.yml?query=branch%3Amain)
+[![image](https://img.shields.io/pypi/v/numcodecs-mask.svg)](https://pypi.python.org/pypi/numcodecs-mask)
+[![image](https://img.shields.io/pypi/l/numcodecs-mask.svg)](https://github.com/juntyr/numcodecs-mask/blob/main/LICENSE)
+[![image](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fjuntyr%2Fnumcodecs-mask%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)](https://pypi.python.org/pypi/numcodecs-mask)
+[![image](https://readthedocs.org/projects/numcodecs-mask/badge/?version=latest)](https://numcodecs-mask.readthedocs.io/en/latest/?badge=latest)
+
+# numcodecs-mask
+
+Masking codecs for the [`numcodecs`] buffer compression API.
+
+[`numcodecs`]: https://numcodecs.readthedocs.io/en/stable/
+
+## License
+
+Licensed under the Mozilla Public License, Version 2.0 ([LICENSE](LICENSE) or https://www.mozilla.org/en-US/MPL/2.0/).
+
+
+## Funding
+
+The `numcodecs-mask` package has been developed as part of [ESiWACE3](https://www.esiwace.eu), the third phase of the Centre of Excellence in Simulation of Weather and Climate in Europe.
+
+Funded by the European Union. This work has received funding from the European High Performance Computing Joint Undertaking (JU) under grant agreement No 101093054.

numcodecs_mask-0.1.0/README.md

@@ -0,0 +1,22 @@
+[![image](https://img.shields.io/github/actions/workflow/status/juntyr/numcodecs-mask/ci.yml?branch=main)](https://github.com/juntyr/numcodecs-mask/actions/workflows/ci.yml?query=branch%3Amain)
+[![image](https://img.shields.io/pypi/v/numcodecs-mask.svg)](https://pypi.python.org/pypi/numcodecs-mask)
+[![image](https://img.shields.io/pypi/l/numcodecs-mask.svg)](https://github.com/juntyr/numcodecs-mask/blob/main/LICENSE)
+[![image](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fjuntyr%2Fnumcodecs-mask%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)](https://pypi.python.org/pypi/numcodecs-mask)
+[![image](https://readthedocs.org/projects/numcodecs-mask/badge/?version=latest)](https://numcodecs-mask.readthedocs.io/en/latest/?badge=latest)
+
+# numcodecs-mask
+
+Masking codecs for the [`numcodecs`] buffer compression API.
+
+[`numcodecs`]: https://numcodecs.readthedocs.io/en/stable/
+
+## License
+
+Licensed under the Mozilla Public License, Version 2.0 ([LICENSE](LICENSE) or https://www.mozilla.org/en-US/MPL/2.0/).
+
+
+## Funding
+
+The `numcodecs-mask` package has been developed as part of [ESiWACE3](https://www.esiwace.eu), the third phase of the Centre of Excellence in Simulation of Weather and Climate in Europe.
+
+Funded by the European Union. This work has received funding from the European High Performance Computing Joint Undertaking (JU) under grant agreement No 101093054.

numcodecs_mask-0.1.0/docs/index.md

@@ -0,0 +1,15 @@
+[![image](https://img.shields.io/github/actions/workflow/status/juntyr/numcodecs-mask/ci.yml?branch=main)](https://github.com/juntyr/numcodecs-mask/actions/workflows/ci.yml?query=branch%3Amain)
+[![image](https://img.shields.io/pypi/v/numcodecs-mask.svg)](https://pypi.python.org/pypi/numcodecs-mask)
+[![image](https://img.shields.io/pypi/l/numcodecs-mask.svg)](https://github.com/juntyr/numcodecs-mask/blob/main/LICENSE)
+[![image](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fjuntyr%2Fnumcodecs-mask%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)](https://pypi.python.org/pypi/numcodecs-mask)
+[![image](https://readthedocs.org/projects/numcodecs-mask/badge/?version=latest)](https://numcodecs-mask.readthedocs.io/en/latest/?badge=latest)
+
+# numcodecs-mask
+
+Masking codecs for the [`numcodecs`][numcodecs] buffer compression API.
+
+## Funding
+
+The `numcodecs-mask` package has been developed as part of [ESiWACE3](https://www.esiwace.eu), the third phase of the Centre of Excellence in Simulation of Weather and Climate in Europe.
+
+Funded by the European Union. This work has received funding from the European High Performance Computing Joint Undertaking (JU) under grant agreement No 101093054.

numcodecs_mask-0.1.0/docs/requirements.txt

@@ -0,0 +1,8 @@
+mkdocs
+mkdocstrings[python]
+mkdocs-exclude
+mkdocstrings-python-generator==1.0.0rc1
+
+Pygments
+
+ruff

numcodecs_mask-0.1.0/properdocs.yml

@@ -0,0 +1,62 @@
+site_name: numcodecs-mask
+
+strict: true
+
+markdown_extensions:
+  - footnotes
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      use_pygments: true
+      noclasses: true
+
+theme:
+  name: readthedocs
+  highlightjs: false
+
+nav:
+  - Home: index.md
+  - Links:
+      - GitHub: https://github.com/juntyr/numcodecs-mask
+      - PyPI: https://pypi.org/project/numcodecs-mask/
+
+plugins:
+  - mkdocstrings-python-generator:
+      source_dirs:
+        - nav_heading: [Documentation]
+          base: src
+  - exclude:
+      glob:
+        - requirements.txt
+  - search
+  - mkdocstrings:
+      enable_inventory: true
+      handlers:
+        python:
+          options:
+            docstring_section_style: list
+            docstring_style: numpy
+            show_if_no_docstring: true
+            filters: ["!^_$", "!^_[^_]", "!^__", "__init__"]
+            members_order: source
+            group_by_category: false
+            show_source: false
+            separate_signature: true
+            show_signature_annotations: true
+            signature_crossrefs: true
+            relative_crossrefs: true
+            show_root_toc_entry: false
+            merge_init_into_class: true
+            summary:
+              attributes: false
+              classes: true
+              functions: true
+              modules: true
+          inventories:
+            - https://docs.python.org/3.12/objects.inv
+            - https://numpy.org/doc/2.2/objects.inv
+            - https://numcodecs.readthedocs.io/en/v0.16.0/objects.inv
+            - https://numcodecs-combinators.readthedocs.io/en/v0.2.15/objects.inv
+            - https://numcodecs-replace.readthedocs.io/en/0.1.2/objects.inv
+
+watch:
+  - src

numcodecs_mask-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "numcodecs-mask"
+version = "0.1.0"
+description = "Masking codecs for the `numcodecs` buffer compression API"
+readme = "README.md"
+license = "MPL-2.0"
+requires-python = ">=3.10"
+dependencies = [
+    "leb128~=1.0.8",
+    "numcodecs>=0.13.0,<0.17",
+    "numcodecs-combinators~=0.2.15",
+    "numpy~=2.0",
+    "typing-extensions~=4.6",
+]
+
+[dependency-groups]
+dev = ["mypy~=1.14", "pytest~=8.3"]
+docs = [
+    "mkdocstrings[python]~=1.0",
+    "mkdocstrings-python-generator==1.0.0rc1",
+    "mkdocs-exclude~=1.0",
+    "properdocs~=1.6.5",
+    "properdocs-theme-readthedocs~=1.6.5",
+    "Pygments~=2.19",
+    "ruff~=0.14",
+]
+
+[project.entry-points."numcodecs.codecs"]
+"mask.meta" = "numcodecs_mask:MaskMetaCodec"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"numcodecs_mask" = ["py.typed"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.pytest.ini_options]
+addopts = ["--import-mode=importlib"]
+xfail_strict = true
+
+[[tool.mypy.overrides]]
+module = ["numcodecs.*"]
+follow_untyped_imports = true

numcodecs_mask-0.1.0/src/numcodecs_mask/__init__.py

@@ -0,0 +1,297 @@
+"""
+Masking codecs for the [`numcodecs`][numcodecs] buffer compression API.
+"""
+
+__all__ = ["MaskMetaCodec"]
+
+from collections.abc import Callable
+from functools import reduce
+from io import BytesIO
+
+import leb128
+import numcodecs.compat
+import numcodecs.registry
+import numpy as np
+from numcodecs.abc import Codec
+from numcodecs_combinators.abc import CodecCombinatorMixin
+from typing_extensions import Buffer  # MSPV 3.12
+
+
+class MaskMetaCodec(Codec, CodecCombinatorMixin):
+    """
+    Meta-codec that masks a value during encoding and restores it during decoding.
+
+    The data is encoded with the `codec`, the [boolean][numpy.bool] mask of
+    where values need to be restored is encoded with the `bitmap_codec`.
+
+    Multiple [`MaskMetaCodec`][.]s can be nested to mask several values.
+    The masked value can be replaced with a fill value before further encoding
+    by including a
+    [`numcodecs_replace.ReplaceFilterCodec`][numcodecs_replace.ReplaceFilterCodec]
+    in the `codec`, e.g. by stacking using the
+    [`numcodecs-combinators`](https://numcodecs-combinators.readthedocs.io)
+    package.
+
+    Parameters
+    ----------
+    mask : int | float
+        The value to be masked.
+    codec : dict | Codec
+        The configuration or instantiated codec that encodes the data.
+    bitmap_codec : dict | Codec
+        The configuration or instantiated codec that encodes the
+        [boolean][numpy.bool] mask of where values need to be restored.
+
+        For instance, the [`numcodecs.PackBits`][numcodecs.packbits.PackBits]
+        codec can be used to pack the mask into a byte array.
+    """
+
+    __slots__: tuple[str, ...] = ("_mask", "_codec", "_bitmap_codec")
+    _mask: int | float
+    _codec: Codec
+    _bitmap_codec: Codec
+
+    codec_id: str = "mask.meta"  # type: ignore
+
+    def __init__(
+        self,
+        *,
+        mask: int | float,
+        codec: dict | Codec,
+        bitmap_codec: dict | Codec,
+    ) -> None:
+        self._mask = mask
+        self._codec = (
+            codec if isinstance(codec, Codec) else numcodecs.registry.get_codec(codec)
+        )
+        self._bitmap_codec = (
+            bitmap_codec
+            if isinstance(bitmap_codec, Codec)
+            else numcodecs.registry.get_codec(bitmap_codec)
+        )
+
+    def encode(self, buf: Buffer) -> Buffer:
+        """Encode the data in `buf`.
+
+        Parameters
+        ----------
+        buf : Buffer
+            Data to be encoded. May be any object supporting the new-style
+            buffer protocol.
+
+        Returns
+        -------
+        enc : Buffer
+            Encoded data. May be any object supporting the new-style buffer
+            protocol.
+        """
+
+        a = np.copy(numcodecs.compat.ensure_ndarray(buf))
+        dtype, shape = a.dtype, a.shape
+
+        if isinstance(self._mask, int) or not np.isnan(self._mask):
+            is_masked = a == self._mask
+        else:
+            is_masked = np.isnan(a)
+
+        # message: dtype shape encoded-dtype encoded-shape [padding] encoded
+        #          bitmap-dtype bitmap-shape [padding] bitmap
+        message: list[bytes | bytearray] = []
+
+        message.append(leb128.u.encode(len(dtype.str)))
+        message.append(dtype.str.encode("ascii"))
+
+        message.append(leb128.u.encode(len(shape)))
+        for s in shape:
+            message.append(leb128.u.encode(s))
+
+        encoded = self._codec.encode(a)
+        encoded = numcodecs.compat.ensure_ndarray(encoded)
+
+        message.append(leb128.u.encode(len(encoded.dtype.str)))
+        message.append(encoded.dtype.str.encode("ascii"))
+
+        message.append(leb128.u.encode(encoded.ndim))
+        for s in encoded.shape:
+            message.append(leb128.u.encode(s))
+
+        # insert padding to align with encoded itemsize
+        message.append(
+            b"\0"
+            * (
+                encoded.dtype.itemsize
+                - (sum(len(m) for m in message) % encoded.itemsize)
+            )
+        )
+
+        # ensure that the encoded values are encoded in little endian binary
+        message.append(encoded.astype(encoded.dtype.newbyteorder("<")).tobytes())
+
+        bitmap = self._bitmap_codec.encode(is_masked)
+        bitmap = numcodecs.compat.ensure_ndarray(bitmap)
+
+        message.append(leb128.u.encode(len(bitmap.dtype.str)))
+        message.append(bitmap.dtype.str.encode("ascii"))
+
+        message.append(leb128.u.encode(bitmap.ndim))
+        for s in bitmap.shape:
+            message.append(leb128.u.encode(s))
+
+        # insert padding to align with bitmap itemsize
+        message.append(
+            b"\0"
+            * (bitmap.dtype.itemsize - (sum(len(m) for m in message) % bitmap.itemsize))
+        )
+
+        # ensure that the bitmap values are encoded in little endian binary
+        message.append(bitmap.astype(bitmap.dtype.newbyteorder("<")).tobytes())
+
+        return b"".join(message)
+
+    def decode(self, buf: Buffer, out: None | Buffer = None) -> Buffer:
+        """
+        Decode the data in `buf`.
+
+        Parameters
+        ----------
+        buf : Buffer
+            Encoded data. May be any object supporting the new-style buffer
+            protocol.
+        out : Buffer, optional
+            Writeable buffer to store decoded data. N.B. if provided, this buffer must
+            be exactly the right size to store the decoded data.
+
+        Returns
+        -------
+        dec : Buffer
+            Decoded data. May be any object supporting the new-style buffer
+            protocol.
+        """
+
+        b = numcodecs.compat.ensure_bytes(buf)
+        b_io = BytesIO(b)
+
+        # message: dtype shape encoded-dtype encoded-shape [padding] encoded
+        #          bitmap-dtype bitmap-shape [padding] bitmap
+        dtype = np.dtype(b_io.read(leb128.u.decode_reader(b_io)[0]).decode("ascii"))
+        shape = tuple(
+            leb128.u.decode_reader(b_io)[0]
+            for _ in range(leb128.u.decode_reader(b_io)[0])
+        )
+
+        encoded_dtype = np.dtype(
+            b_io.read(leb128.u.decode_reader(b_io)[0]).decode("ascii")
+        )
+        encoded_shape = tuple(
+            leb128.u.decode_reader(b_io)[0]
+            for _ in range(leb128.u.decode_reader(b_io)[0])
+        )
+        encoded_size = reduce(lambda a, b: a * b, encoded_shape, 1)
+
+        # remove padding to align with encoded itemsize
+        b_io.read(encoded_dtype.itemsize - (b_io.tell() % encoded_dtype.itemsize))
+
+        encoded = (
+            np.frombuffer(
+                b_io.read(encoded_size * encoded_dtype.itemsize),
+                dtype=encoded_dtype.newbyteorder("<"),
+                count=encoded_size,
+            )
+            .astype(encoded_dtype)
+            .reshape(encoded_shape)
+        )
+
+        decoded = np.empty(shape, dtype=dtype)
+        self._codec.decode(encoded, out=decoded)
+
+        bitmap_dtype = np.dtype(
+            b_io.read(leb128.u.decode_reader(b_io)[0]).decode("ascii")
+        )
+        bitmap_shape = tuple(
+            leb128.u.decode_reader(b_io)[0]
+            for _ in range(leb128.u.decode_reader(b_io)[0])
+        )
+        bitmap_size = reduce(lambda a, b: a * b, bitmap_shape, 1)
+
+        # remove padding to align with bitmap itemsize
+        b_io.read(bitmap_dtype.itemsize - (b_io.tell() % bitmap_dtype.itemsize))
+
+        bitmap = (
+            np.frombuffer(
+                b_io.read(bitmap_size * bitmap_dtype.itemsize),
+                dtype=bitmap_dtype.newbyteorder("<"),
+                count=bitmap_size,
+            )
+            .astype(bitmap_dtype)
+            .reshape(bitmap_shape)
+        )
+
+        is_masked = np.empty(shape, dtype=np.bool)
+        self._bitmap_codec.decode(bitmap, out=is_masked)
+
+        decoded[is_masked] = self._mask
+
+        return numcodecs.compat.ndarray_copy(decoded, out)  # type: ignore
+
+    def get_config(self) -> dict:
+        """
+        Returns the configuration of this mask meta-codec.
+
+        [`numcodecs.registry.get_codec(config)`][numcodecs.registry.get_codec]
+        can be used to reconstruct this codec from the returned config.
+
+        Returns
+        -------
+        config : dict
+            Configuration of this mask meta-codec.
+        """
+
+        return dict(
+            id=type(self).codec_id,
+            mask=self._mask,
+            codec=self._codec.get_config(),
+            bitmap_codec=self._bitmap_codec.get_config(),
+        )
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(mask={self._mask!r}, codec={self._codec!r}, bitmap_codec={self._bitmap_codec!r})"
+
+    def map(self, mapper: Callable[[Codec], Codec]) -> "MaskMetaCodec":
+        """
+        Apply the `mapper` to this mask meta-codec.
+
+        In the returned [`MaskMetaCodec`][..], the `codec` and
+        `bitmap_codec` are replaced by their mapped codecs.
+
+        The `mapper` should recursively apply itself to any inner codecs that
+        also implement the
+        [`CodecCombinatorMixin`][numcodecs_combinators.abc.CodecCombinatorMixin]
+        mixin.
+
+        To automatically handle the recursive application as a caller, you can
+        use
+        ```python
+        numcodecs_combinators.map_codec(codec, mapper)
+        ```
+        instead.
+
+        Parameters
+        ----------
+        mapper : Callable[[Codec], Codec]
+            The callable that should be applied to the wrapped `codec` and
+            `bitmap_codec` to map over this mask meta-codec.
+
+        Returns
+        -------
+        mapped : MaskMetaCodec
+            The mapped mask meta-codec.
+        """
+
+        return MaskMetaCodec(
+            mask=self._mask,
+            codec=mapper(self._codec),
+            bitmap_codec=mapper(self._bitmap_codec),
+        )
+
+
+numcodecs.registry.register_codec(MaskMetaCodec)

numcodecs_mask-0.1.0/tests/test_mask.py

@@ -0,0 +1,115 @@
+import json
+from typing import ClassVar
+
+import numcodecs
+import numcodecs.compat
+import numcodecs.registry
+import numpy as np
+import pytest
+from numcodecs.abc import Codec
+
+
+def test_from_config():
+    config = dict(
+        id="mask.meta",
+        mask=np.nan,
+        codec=dict(id="zlib", level=1),
+        bitmap_codec=dict(id="packbits"),
+    )
+
+    codec = numcodecs.registry.get_codec(config)
+    assert codec.__class__.__name__ == "MaskMetaCodec"
+    assert codec.__class__.__module__ == "numcodecs_mask"
+
+    assert (
+        repr(codec)
+        == "MaskMetaCodec(mask=nan, codec=Zlib(level=1), bitmap_codec=PackBits())"
+    )
+
+    assert json.dumps(codec.get_config(), sort_keys=True) == json.dumps(
+        config, sort_keys=True
+    )
+
+
+def check_roundtrip(data: np.ndarray, mask: int | float):
+    config = dict(
+        id="mask.meta",
+        mask=mask,
+        codec=dict(id="noise", seed=42),
+        bitmap_codec=dict(id="packbits"),
+    )
+
+    codec = numcodecs.registry.get_codec(config)
+
+    assert (
+        repr(codec)
+        == f"MaskMetaCodec(mask={mask!r}, codec=NoiseCodec(seed=42), bitmap_codec=PackBits())"
+    )
+
+    assert json.dumps(codec.get_config(), sort_keys=True) == json.dumps(
+        config, sort_keys=True
+    )
+
+    encoded = codec.encode(data)
+    decoded = codec.decode(encoded)
+
+    assert decoded.dtype == data.dtype
+    assert decoded.shape == data.shape
+
+    if isinstance(mask, int) or not np.isnan(mask):
+        assert np.all((decoded == mask) | (data != mask))
+    else:
+        assert np.all(np.isnan(decoded) | ~np.isnan(data))
+
+
+@np.errstate(invalid="ignore")
+@pytest.mark.parametrize(
+    "mask", [0.0, -0.0, 1.0, -1.0, np.nan, -np.nan, np.inf, -np.inf, 4.2, -2.4]
+)
+def test_roundtrip(mask):
+    check_roundtrip(np.zeros(tuple()), mask=mask)
+    check_roundtrip(np.zeros((0,)), mask=mask)
+    if np.isfinite(mask):
+        check_roundtrip(np.arange(1000).reshape(10, 10, 10), mask=mask)
+    check_roundtrip(np.array([4.2, -2.4, np.nan, -np.nan, 0.0, -0.0]), mask=mask)
+    check_roundtrip(np.array([np.inf, -np.inf, np.nan, -np.nan, 0.0, -0.0]), mask=mask)
+    check_roundtrip(
+        np.array(
+            [np.inf, -np.inf, np.nan, -np.nan, 0.0, -0.0],
+            dtype=np.dtype(np.float64).newbyteorder("<"),
+        ),
+        mask=mask,
+    )
+    check_roundtrip(
+        np.array(
+            [np.inf, -np.inf, np.nan, -np.nan, 0.0, -0.0],
+            dtype=np.dtype(np.float64).newbyteorder(">"),
+        ),
+        mask=mask,
+    )
+
+
+class NoiseCodec(Codec):
+    __slots__: tuple[str, ...] = ("_seed",)
+    _seed: int
+
+    codec_id: ClassVar[str] = "noise"  # type: ignore
+
+    def __init__(self, *, seed: int):
+        self._seed = seed
+
+    def encode(self, buf):
+        rng = np.random.Generator(np.random.PCG64(seed=self._seed))
+        return buf + rng.normal(scale=0.1, size=buf.shape).astype(buf.dtype)
+
+    def decode(self, buf, out=None):
+        return numcodecs.compat.ndarray_copy(buf, out)
+
+    def get_config(self) -> dict:
+        return dict(id=type(self).codec_id, seed=self._seed)
+
+    def __repr__(self) -> str:
+        return f"NoiseCodec(seed={self._seed!r})"
+
+
+numcodecs.registry.register_codec(NoiseCodec)