Manages n-dimensional volumes of data
Project description
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:
- Tuple of key types
- 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:
- Key type
- 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:
x
key typey
key type- 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:
x
key typey
key typez
key type- 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:
w
key typex
key typey
key typez
key type- 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:
v
key typew
key typex
key typey
key typez
key type- 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 @cariad@tech.lgbt.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for nvalues-1.0.0b3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1f7592bb71e84393f75c87427400c54b61879acab67a6fd8bc236ad9a2a2fb2a |
|
MD5 | 3333fd4d778c6a615da608950dc7eff7 |
|
BLAKE2b-256 | 478d8eb1abcc25007b788c3f74c273c1627fe7a4daff21e68c613ab092228f26 |