Metadata-Version: 2.4
Name: ndshapecheck
Version: 0.2.3
Summary: A library for checking the shapes of multidimensional arrays.
Author-email: Joseph Agrane <josephagrane@gmail.com>
License: Copyright 2025 Joseph Agrane
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# ndshapecheck

ndshapecheck is a simple library for checking the shape of numpy arrays. To get started, see
the examples below. For more information, please visit the
[documentation](https://mrjoe3012.github.io/ndshapecheck).

Contributions are welcome! Please read the [contribution guide](https://mrjoe3012.github.io/ndshapecheck/contributing.html) for more information.

# Quickstart

## Requirements

-   Python 3.10 or newer

## Installation

Install the library with:

``` bash
pip install ndshapecheck
```

## Basic Usage

Import the library:

``` python
from ndshapecheck import ShapeCheck
```

Create a `ShapeCheck` instance and verify shapes:

``` python
import numpy as np
sc = ShapeCheck()

assert sc('A,B,3').check(np.zeros(10, 10, 3)), sc.why # A = 10, B = 10
assert sc('A,C*,3').check(np.zeros(10, 3, 2, 3, 3)), sc.why # C*=3, 2, 3
```

## Notes

-   **Symbol Binding:** `ShapeCheck` objects *remember*
    symbol values between checks.

    In the example above, the first call sets `A=10` and
    `B=10`. Subsequent checks using these symbols will fail
    if a value other than `10` is found within the shape.

-   **Shape Rules:** Shape rules are **comma-separated** strings. Each
    element is either:

    -   A non-negative integer (e.g. `3`, `5`)
    -   A case-sensitive symbolic name (e.g. `A`,
        `B1`, `my_dim`)

-   **Quantifiers:** You can append standard regular expression
    quantifiers to symbols:

    -   `*` : zero or more dimensions
    -   `+` : one or more dimensions
    -   `?` : optional dimension

-   **Important:** `A`, `A*`, `A?`
    and `A+` are treated as **separate symbols**. Example:

    ``` python
    sc('A*,A').check(np.zeros((5, 10, 10)))
    # Assigns A* = (5,10) and A = 10 separately
    ```

-   **Important:** If an optional symbol is omitted, it must also be
    omitted in future checks. Example:

    ``` python
    sc('optional_batch?,n_features').check((12,))  # no batch dimension
    sc('optional_batch?,n_labels').check((10, 3))  # fails. batch dimension should be omitted
    ```

-   **Error Messages:** If a shape check fails, `sc.why`
contains a message string explaining why.
