nvalues 1.0.0b2

Manages n-dimensional volumes of data

NValues

NValues is a Python package for working with n-dimensional volumes of data.

Installation

NValues requires Python 3.9 or later and can be installed via PyPI:

pip install nvalues

Usage

For example, to create a spreadsheet-like grid of float values with alphabetic x keys and integer y keys:

from nvalues import Volume

grid = Volume[tuple[str, int], float]()
grid["A", 0] = 1.2
grid["B", 1] = 1.4
grid["C", 2] = 1.6

print(grid["A", 0])
# 1.2

See the Volume class for more detail, or if you don't need more than five dimensions then see the Line, Grid, Cube, Tesseract or Penteract wrapper classes for an easier life.

The Volume class

The Volume class represents a strongly-typed n-dimensional volume of values.

Construction

Volume requires two generic types:

1. Tuple of key types
2. Value type

For example:

from nvalues import Volume

# A dictionary with integer keys and string values:
volume = Volume[tuple[int], str]()

# A grid with integer coordinates and string values:
volume = Volume[tuple[int, int], str]()

# A spreadsheet of floats with horizontal alphabetic keys and
# vertical integer keys:
volume = Volume[tuple[str, int], float]()

# A cube of booleans with integer x, string y and float z keys:
volume = Volume[tuple[int, str, float], bool]()

Default value

An optional default value can be specified in the initialiser:

volume = Volume[tuple[int, int], str](default_value="")

If you request a key that doesn't exist then this default value will be returned. If you request a key that doesn't exist without a default value set then the volume will raise nvalues.exceptions.NKeyError.

A default value can be set after construction via the default property and cleared by calling clear_default().

Getting and setting values

Values are read and set via their keys. For example:

from nvalues import Volume

volume = Volume[tuple[int, int], str]()
volume[0, 0] = "zero"
print(volume[0, 0])
# "zero"

Iterating values

Volume natively supports iteration and will yield the key and value for every item it holds.

from nvalues import Volume

volume = Volume[tuple[int, int], str]()

volume[0, 0] = "zero-zero"
volume[4, 0] = "four-zero"
volume[0, 4] = "zero-four"

for item in volume:
    print(f"Found {item.value} at {item.key}")

# Found zero-zero at (0, 0)
# Found zero-four at (0, 4)
# Found four-zero at (4, 0)

The Line class

The Line class is a wrapper around the Volume class to simplify the creation of one-dimensional volumes.

All the base functionality, such as default values, key accessors and iteration, is inherited by Line.

Construction

Line requires two generic types:

1. Key type
2. Value type

For example, to create a Line with integer keys and string values:

from nvalues import Line

line = Line[int, str]()

Reading and setting values

Values can be read and set via their keys as described in the base Volume class, but Line also provides get() and set() helper functions:

from nvalues import Line

line = Line[int, str]()
line.set(0, "zero")
print(line.get(0))
# "zero"

The Grid class

The Grid class is a wrapper around the Volume class to simplify the creation of two-dimensional volumes.

All the base functionality, such as default values, key accessors and iteration, is inherited by Grid.

Construction

Grid requires three generic types:

1. x key type
2. y key type
3. Value type

For example, to create a Grid with x string keys, y integer keys and boolean values:

from nvalues import Grid

grid = Grid[str, int, bool]()

Reading and setting values

Values can be read and set via their keys as described in the base Volume class, but Grid also provides get() and set() helper functions:

from nvalues import Grid

grid = Grid[str, int, bool]()
grid.set("A", 0, True)
print(grid.get("A", 0))
# True

The Cube class

The Cube class is a wrapper around the Volume class to simplify the creation of three-dimensional volumes.

All the base functionality, such as default values, key accessors and iteration, is inherited by Cube.

Construction

Cube requires four generic types:

1. x key type
2. y key type
3. z key type
4. Value type

For example, to create a Cube with x string keys, y integer keys, z float keys and boolean values:

from nvalues import Cube

cube = Cube[str, int, float, bool]()

Reading and setting values

Values can be read and set via their keys as described in the base Volume class, but Cube also provides get() and set() helper functions:

from nvalues import Cube

cube = Cube[str, int, float, bool]()
cube.set("A", 0, 1.2, True)
print(cube.get("A", 0, 1.2))
# True

The Tesseract class

The Tesseract class is a wrapper around the Volume class to simplify the creation of four-dimensional volumes.

All the base functionality, such as default values, key accessors and iteration, is inherited by Tesseract.

Construction

Tesseract requires five generic types:

1. w key type
2. x key type
3. y key type
4. z key type
5. Value type

For example, to create a Tesseract with w string keys, x string keys, y int keys, z float keys and boolean values:

from nvalues import Tesseract

tesseract = Tesseract[str, str, int, float, bool]()

Reading and setting values

Values can be read and set via their keys as described in the base Volume class, but Tesseract also provides get() and set() helper functions:

from nvalues import Tesseract

tesseract = Tesseract[str, str, int, float, bool]()
tesseract.set("A", "B", 0, 1.2, True)
print(tesseract.get("A", "B", 0, 1.2))
# True

The Penteract class

The Penteract class is a wrapper around the Volume class to simplify the creation of five-dimensional volumes.

All the base functionality, such as default values, key accessors and iteration, is inherited by Penteract.

Construction

Penteract requires six generic types:

1. v key type
2. w key type
3. x key type
4. y key type
5. z key type
6. Value type

For example, to create a Tesseract with v integer keys, w string keys, x string keys, y int keys, z float keys and boolean values:

from nvalues import Penteract

penteract = Penteract[int, str, str, int, float, bool]()

Reading and setting values

Values can be read and set via their keys as described in the base Volume class, but Penteract also provides get() and set() helper functions:

from nvalues import Penteract

penteract = Penteract[int, str, str, int, float, bool]()
penteract.set(3, "A", "B", 0, 1.2, True)
print(penteract.get(3, "A", "B", 0, 1.2))
# True

Support

Please raise bugs, feature requests and ask questions at cariad/nvalues/issues.

The Project

NValues is © 2022 Cariad Eccleston and released under the MIT License at cariad/nvalues.

The Author

Hello! 👋 I'm Cariad Eccleston and I'm a freelance backend and infrastructure engineer in the United Kingdom. You can find me at cariad.earth, github/cariad, linkedin/cariad and on Mastodon at @[e-mail].