Metadata-Version: 2.4
Name: matrixcore-tool
Version: 0.1.0
Summary: A simple, extensible and efficient Python framework for manipulating 2D matrices.
License-Expression: MIT
Keywords: matrix,grid,2d,data-structures,algorithms
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# MatrixCore

MatrixCore is a small, general-purpose Python library for creating and
manipulating two-dimensional matrices. It is suitable for grids, tilemaps,
simulations, spatial data, and other applications that need an ordinary 2D
data structure. It is not a graphics or game engine and does not aim to replace
NumPy.

## Installation

```console
python -m pip install matrixcore
```

MatrixCore supports Python 3.10 and newer, uses only the standard library at
runtime, and runs on Windows, macOS, and Linux.

## Quick start

```python
from matrixcore import Matrix

matrix = Matrix.from_list([
    [1, 2, 3],
    [4, 5, 6],
])

matrix[1, 0] = 20
area = matrix.region(0, 0, 2, 2)
area.fill(0)
print(matrix.to_list())
print(matrix.rotated().shape)
```

Coordinates are always `(x, y)`, where `x` is the column, `y` is the row, and
`(0, 0)` is the top-left cell. Matrix shape is `(width, height)`. Zero-sized
dimensions are supported; negative dimensions are rejected.

## Features

- List, text, and factory-based construction, with checked tuple indexing.
- Auto, fixed-width numeric, and Python-object storage.
- Live rectangular regions, copying, filling, and replacement.
- Rotation, reflection, transpose, resize, and translation.
- Search, neighbors, functional mapping, and shape-checked combination.
- Iterative flood fill, BFS/DFS, connected components, pathfinding, boundaries,
  and rectangular pattern matching.
- Change events, event batching, rollback transactions, and opt-in undo/redo.
- Ordered matrix layers with explicit transparency values.
- Explicitly installed plugins that cannot replace native methods.
- Versioned `.matrix`, JSON, CSV, and plain-text import/export.

## Storage

`storage="auto"` selects compact `array.array` numeric storage when the values
fit a supported type, and promotes to list-backed object storage when a write
cannot be represented. Fixed `dtype` choices are `int8`, `int16`, `int32`,
`int64`, `float32`, and `float64`; integer bounds and array widths are checked.
Floating point values follow the precision of the chosen array format. Object
storage accepts arbitrary Python values. `memory_usage()` is an estimate and
excludes the Matrix instance and referenced object graphs.

## Examples and documentation

Executable examples are in `examples/`. Detailed guides are in `docs/`:

- [Installation](docs/installation.md)
- [Quickstart](docs/quickstart.md)
- [API](docs/api.md)
- [Storage](docs/storage.md)
- [Plugins](docs/plugins.md)
- [Examples](docs/examples.md)

## Development and tests

```console
python -m pip install -e ".[dev]"
python -m pytest -v
python -m pytest --cov=matrixcore --cov-report=term-missing
```

## Build and publish

To prepare a release locally:

```console
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```

The upload command publishes the distributions and is intentionally not run by
this project setup. Review the files and configure your PyPI credentials before
running it yourself.

## License

MatrixCore is distributed under the MIT License. See [LICENSE](LICENSE).

Contributions are described in [CONTRIBUTING.md](CONTRIBUTING.md).
