Package: nvalues
NValuesNValuesis a Python package for working withn-dimensional volumes of data.Full documentation is online atnvalues.dev.InstallationNValuesrequires Python 3.9 or later and can be installed viaPyPI:pip install nvaluesTheVolumeclassTheVolumeclassrepresents a strongly-typedn-dimensional volume of values.ConstructionYou must pass two generic types on construction:Tuple of any number of key typesValue typefromnvaluesimportVolume# A spreadsheet-like grid of floats with string x and integer y 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 valuesBy default, volumes will raisenvalues.exceptions.NKeyErrorif you try to read a key that doesn't exist.To return a default value instead, you can either:Pass the default value as thedefaultargument:fromnvaluesimportVolumevolume=Volume[tuple[int,int],str](default="default")print(volume[0,0])# "default"Pass a function that generates a default value as thedefault_makerargument:fromnvaluesimportVolumedefmake_default(key:tuple[int,int])->str:returnf"default for{key}"volume=Volume[tuple[int,int],str](default_maker=make_default)print(volume[0,0])# "default for (0, 0)"Default values generated at runtime will be added to the volume, while static defaults will not.Reading, setting and deleting valuesValues are read, set and deleted via their keys.fromnvaluesimportVolumevolume=Volume[tuple[str,int],float](default=0)volume["A",0]=1.2print(volume["A",0])# 1.2delvolume["A",0]print(volume["A",0])# 0Key validationAVolumecan be configured to reject invalid keys if a validator is passed in the initialiser or set on thekey_validatorproperty.If set, the key validator is a function that examines the key and raises any exception if it's invalid. Any attempts to access an invalid key will result inInvalidKeybeing raised.fromnvaluesimportVolumefromnvalues.exceptionsimportInvalidKeymax_x=3max_y=4defcheck_key_range(key:tuple[int,int])->None:x=key[0]ifx<0orx>max_x:raiseValueError(f"x{x}must be 0-{max_x}inclusive")y=key[1]ify<0ory>max_y:raiseValueError(f"y{y}must be 0-{max_y}inclusive")volume=Volume[tuple[int,int],str](key_validator=check_key_range)try:volume[0,17]="foo"exceptInvalidKeyasex:print(ex)# Key (0, 17) failed validation (y 17 must be 0-4 inclusive)Iterating valuesNative iteration yields the key and value for each item in the volume.fromnvaluesimportVolumevolume=Volume[tuple[int,int],str]()volume[0,0]="zero-zero"volume[4,0]="four-zero"volume[0,4]="zero-four"foriteminvolume: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)Other classesTheLine,Grid,Cube,TesseractandPenteractclasses wrap and simplify theVolumeclass if you don't need more than five dimensions.SupportPlease raise bugs, feature requests and ask questions atcariad/nvalues/issues.The ProjectNValuesis © 2022 Cariad Eccleston and released under theMIT Licenseatcariad/nvalues.The AuthorHello! 👋 I'mCariad Ecclestonand I'm a freelance backend and infrastructure engineer in the United Kingdom. You can find me atcariad.earth,github/cariad,linkedin/cariadand on Mastodon at@cariad@tech.lgbt.