Metadata-Version: 2.4
Name: pyarrlib
Version: 1.0.0b0
Summary: this module can help you work with arrays
Author: Sasha Yuvko
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

# pyarrlib

A small Python utility library for working with arrays and nested array structures.

This project provides simple helper functions for reversing arrays, computing numeric aggregates, counting nested leaves, flattening nested structures, sorting, filtering, and solving small systems of linear equations. It also includes utilities for working with dictionaries.

## Features

### Array Functions
- `reverse_arr(array)` — reverse a one-dimensional sequence
- `sum_arr(array)` — compute the sum of numeric values
- `multiplication_arr(array)` — compute the product of numeric values
- `min(array)` — find the smallest numeric value in a sequence
- `max(array)` — find the largest numeric value in a sequence
- `arifmetic_mean(array)` — compute the arithmetic mean of numeric values
- `sort(array)` — sort the array in-place
- `same(array1, array2)` — find common elements between two arrays
- `step_filter(array, step, first_num=0)` — filter array with step
- `type_filter(array, type_filt)` — filter elements by type
- `range_arr(array, first, last)` — filter numbers within range (first < x < last)
- `range_other(array, first, last)` — filter numbers outside range
- `chunk(array, size)` — create chunks of repeated elements
- `mv(array, i1, i2)` — move element from index i1 to i2
- `hw_times(array, key)` — count occurrences of key
- `not_same(array, array2)` — find elements not common between arrays

### Nested Array Functions
- `leafs(array)` — flatten nested integer arrays
- `num_of_leafs(array)` — count integer leaf nodes in nested arrays
- `len_arr(array)` — count all scalar leaves in nested arrays
- `equation_system(full_matrix)` — solve 2×2 or 3×3 linear systems using determinants
- `flatten(array)` — flatten nested structures (supports int, str, float, bool, tuples)

### Dictionary Functions
- `max(d)` — find the maximum value in dictionary values
- `min(d)` — find the minimum value in dictionary values
- `is_key_value_in_dict(d, key, value)` — check if key-value pair exists
- `key_sum(d)` — sum numeric values in dictionary
- `key_multiplication(d)` — multiply numeric values in dictionary
- `same_keys(d1, d2)` — find common keys between dictionaries
- `same_values(d1, d2)` — find common values between dictionaries

## Installation

From the repository root, install in editable mode:

```bash
python -m pip install -e .
```

If you prefer not to install, you can run code directly from this project by ensuring the repository root is on `PYTHONPATH`.

## Usage

```python
from pyarrlib import (
    ArrayTypeError,
    IsNotArrayError,
    arifmetic_mean,
    chunk,
    equation_system,
    flatten,
    hw_times,
    is_key_value_in_dict,
    key_sum,
    leafs,
    len_arr,
    max,
    min,
    multiplication_arr,
    mv,
    not_same,
    num_of_leafs,
    range_arr,
    reverse_arr,
    same,
    sort,
    step_filter,
    sum_arr,
    type_filter,
)

print(reverse_arr([1, 'hello', 3, True]))
# [True, 3, 'hello', 1]

print(sum_arr([1, 5, 4, 3, 8]))
# 21

print(multiplication_arr([4, 1, 2, 5, 7]))
# 280

print(min([1, 3, 6, -3, 2]))
# -3

print(arifmetic_mean([2, 4, 6]))
# 4.0

nested = [[1, 2, [3]], [4, [5, 6]]]
print(leafs(nested))
# [1, 2, 3, 4, 5, 6]
print(num_of_leafs(nested))
# 6
print(len_arr(nested))
# 6

system = [
    [2, -1, 1],
    [1, 1, 1],
    [1, 2, -1],
]
print(equation_system([row + [value] for row, value in zip(system, [1, 2, 3])]))

# Additional examples
arr = [1, 2, 3, 4, 5]
sort(arr)
print(arr)  # [1, 2, 3, 4, 5]

print(chunk([1, 2], 3))  # [[1, 1, 1], [2, 2, 2]]

print(hw_times([1, 2, 2, 3], 2))  # 2

print(type_filter([1, 'a', 2.0, True], int))  # [1, True]

d = {'a': 1, 'b': 2}
print(key_sum(d))  # 3
print(is_key_value_in_dict(d, 'a', 1))  # True
```

## API Reference

### Exceptions

- `ArrayTypeError` — raised when array contains unsupported element types for numeric operations
- `IsNotArrayError` — raised when input is not an array-like structure

### Array Functions

- `reverse_arr(array)` — Return a new sequence with the elements in reverse order.
- `sum_arr(array)` — Return the sum of numeric values in the array. Returns `ArrayTypeError` if non-numeric elements present.
- `multiplication_arr(array)` — Return the product of numeric values in the array. Returns `ArrayTypeError` if non-numeric elements present.
- `min(array)` — Return the smallest value from a one-dimensional sequence. Raises `ArrayTypeError` for non-numeric.
- `max(array)` — Return the largest value from a one-dimensional sequence. Raises `ArrayTypeError` for non-numeric.
- `arifmetic_mean(array)` — Return the arithmetic mean of numeric values in the array.
- `sort(array)` — Sort the array in-place.
- `same(array1, array2)` — Return common elements between two arrays.
- `step_filter(array, step, first_num=0)` — Return sliced array with given step.
- `type_filter(array, type_filt)` — Return elements of specified type.
- `range_arr(array, first, last)` — Return numeric elements within the range (first < x < last).
- `range_other(array, first, last)` — Return numeric elements outside the range.
- `chunk(array, size)` — Create list of lists where each element is repeated 'size' times.
- `mv(array, i1, i2)` — Move element from index i1 to i2 in-place.
- `hw_times(array, key)` — Count occurrences of key in array.
- `not_same(array, array2)` — Return elements not common between the arrays.

### Nested Array Functions

- `leafs(array)` — Return a flat list containing all integer leaf values from a nested array structure.
- `num_of_leafs(array)` — Count integer leaf nodes recursively in a nested array structure.
- `len_arr(array)` — Count all scalar leaf values in a nested array structure. Supported scalar types include `int`, `str`, `float`, and `bool`.
- `equation_system(full_matrix)` — Solve a 2×2 or 3×3 system of linear equations supplied as an augmented matrix. Returns a list of solution values or the string `"has no solution"` when the determinant is zero.
- `flatten(array)` — Return a flattened list of all scalar elements, preserving nested structures as lists.

### Dictionary Functions

- `dict_max(d)` — Return the maximum value from dictionary values.
- `dict_min(d)` — Return the minimum value from dictionary values.
- `is_key_value_in_dict(d, key, value)` — Return True if the key-value pair exists in the dictionary.
- `key_sum(d)` — Return the sum of numeric values in the dictionary.
- `key_multiplication(d)` — Return the product of numeric values in the dictionary.
- `same_keys(d1, d2)` — Return list of common keys between two dictionaries.
- `same_values(d1, d2)` — Return list of common values between two dictionaries.

## Running the included checks

The repository includes a simple assertion-based test file.

```bash
python tests/test.py
```

## Project structure

- `setup.py` — package metadata and build configuration
- `README.md` — project documentation
- `src/pyarrlib/arrpy.py` — array utility functions
- `src/pyarrlib/multidim_arr.py` — nested array traversal functions
- `src/pyarrlib/dict.py` — dictionary utility functions
- `src/pyarrlib/_checks.py` — validation and error classes
- `src/pyarrlib/__init__.py` — package initialization
- `tests/test.py` — example assertions covering core behavior

## License

This project is licensed under MIT.
