model

This submodule presents ndf entities in a form of easy(ish)-to-work structures.

Abstract Classes

class DeclListRow

Abstract class for rows of data in list-like structures of the model.

It serves as a foundation for any classes that are meant to store assigned items along with any related metadata (variable names, visibility modifiers, mapping keys etc.)

parent

List-like object to which this row belongs.

Type:

DeclarationsList[Self]

index

Index of this row in the parent object.

Type:

int, readonly

edit(_strict=True, **kwargs) → Self

Edit current row with multiple values (except parent and index).

This method allows to edit a bunch of values in the row at once. It also accepts properties’ aliases as well as easily unpacking an output of an ndf_parse.expression().

Note

You cannot pass mutually exclusive keys at once, for example, you cannot pass namespace=... along with n=... to ListRow.edit(), it will raise an error.

Parameters:

• kwargs (CellValue | None) – Properties to edit.

• _strict (bool, default=True) – If set to True and kwargs contain a key that doesn’t match any properties of this row then it will fail. If False then it will silently skip it.

Return type:

Self

Examples

>>> import ndf_parse as ndf
>>> source = ndf.convert(b"Test is TObject(Member1: int = 1)")
>>> obj = source[0].v  # `v` is an alias for `value`
>>> ndf.printer.print(obj)
TObject
(
    Member1: int = 1
)
>>> # note there was no "Test is", because we've printed only the value, not the row
>>> m1 = obj[0]
>>> print(m1)  # check the row
Object[0](member='Member1', type='int', visibility=None, namespace=None, value='1')
>>> expr = ndf.expression("MemberRenamed = Namespace is 2")
>>> print(expr)
{'value': '2', 'namespace': 'Namespace', 'member': 'MemberRenamed'}
>>> m1.edit(**expr)  # edit row via dict decomposition
Object[0](member='MemberRenamed', type='int', visibility=None, namespace='Namespace', value='2')
>>> ndf.printer.print(obj)
TObject
(
    MemberRenamed: int = Namespace is 2
)
>>> m1.edit(v='3', n='Ns', vis="export")  # edit using aliases
Object[0](member='MemberRenamed', type='int', visibility='export', namespace='Ns', value='3')
>>> m1.edit(nonexistent="4", _strict=False)  # silently ignores
Object[0](member='MemberRenamed', type='int', visibility='export', namespace='Ns', value='3')
>>> m1.edit(nonexistent="4")  # Raises an error
TypeError: Cannot set MemberRow.nonexistent, attribute does not exist.

as_dict()

Outputs given row in a form of a dict.

Warning

It does not perform copy for it’s value, so avoid using it to copy a row from one place to another. More on referencing restrictions.

class DeclarationsList

Bases: List[DeclListRow_co]

Abstract class for list-like objects of this model. It is used to store rows that are subclasses of DeclListRow.

parent

Parent of this object. All objects of this class and it’s subclasses are expected to have it NOT equal to None. Exceptions: root-level List and objects that are generated with ndf_parse.expression() and not yet added to some parent.

Type:

DeclarationsList | None

add(_strict=True, **kwargs) → DeclListRow

Builds and adds a new row from given arguments.

Parameters:

• kwargs (CellValue | None) – Properties to edit.

• _strict (bool, default=True) – If set to True and kwargs contain a key that doesn’t match any properties of this row then it will fail. If False then it will silently skip it.

Examples

>>> import ndf_parse as ndf
>>> source = ndf.model.List(is_root = True)
>>> source
[]  # all DeclarationLists in model derive from list hence the look
>>> # add an item
>>> source.add(namespace="Two", value="2")
List[0](visibility=None, namespace='Two', value='2')
>>> # use aliases
>>> source.add(vis='export', n="Text", v="'My text.'")
List[1](visibility='export', namespace='Text', value="'My text.'")
>>> # silently skip non-existent arguments
>>> source.add(n="Four", v="4", nonexistent='blah', _strict = False)
List[2](visibility=None, namespace='Four', value='4')
>>> # fail on non-existent arguments (default behaviour)
>>> source.add(n="Four", v="4", nonexistent='blah')
TypeError: Cannot set ListRow.nonexistent, attribute does not exist.
>>> ndf.printer.print(source)
Two is 2
export Text is 'My text.'
Four is 4

insert(index, _strict=True, **kwargs) → DeclListRow

Builds and inserts a new row from given arguments into a given place.

Same logic applies as in add() method, just with addition of an index as first positional argument.

Parameters:

• index (int) – Where to insert a new row.

• kwargs (Optional[CellValue]) – Properties to edit.

• _strict (bool, default=True) – If set to True and kwargs contain a key that doesn’t match any properties of this row then it will fail. If False then it will silently skip it.

Model Classes

Row Classes

class ListRow(parent, value, visibility=None, namespace=None)

Bases: DeclListRow

Row of data from a List object.

parent

List-like object to which this row belongs.

Type:

List

index

Index of this row in the parent object.

Type:

int, readonly

value

Value of this row.

Type:

CellValue | str

visibility

Visibility modifier of the assignment. Should be one of these: 'unnamed' | 'export' | 'private' | 'public' Keep in mind that it won’t protect from 'unnamed' actually having a name or appearing multiple times the List, see notes on checking strictness.

Type:

str | None

namespace

Namespace name of the assignment.

Type:

str | None

vis

An alias for visibility.

n

An alias for namespace.

v

An alias for value.

class MapRow(parent, key, value)

Bases: DeclListRow

Row of data from a Params object.

parent

List-like object to which this row belongs.

Type:

MapRow

index

Index of this row in the parent object.

Type:

int, readonly

key

Key of this pair.

Type:

str

value

Value of this pair.

Type:

CellValue | str

k

An alias for key.

v

An alias for value.

class MemberRow(parent, value, member=None, type=None, visibility=None, namespace=None)

Bases: DeclListRow

Row of data from Object and Template objects.

parent

List-like object to which this row belongs.

Type:

Object | Template

index

Index of this row in the parent object.

Type:

int, readonly

member

Member name of the object.

Type:

str | None

type

Typing data for this object. Keep in mind, not all types are stored here.

Type:

str | None

value

Value of this row.

Type:

CellValue | str

visibility

Visibility modifier of the assignment. Should be one of these: 'export' | 'private' | 'public'

Type:

str | None

namespace

Namespace name of the assignment.

Type:

str | None

vis

An alias for visibility.

m

An alias for member.

t

An alias for type.

n

An alias for namespace.

v

An alias for value.

class ParamRow(parent, param=None, type=None, value=None)

Bases: DeclListRow

Row of data from a Params object.

parent

List-like object to which this row belongs.

Type:

Params

index

Index of this row in the parent object.

Type:

int, readonly

param

Generic parameter’s name.

Type:

str

type

Typing data for this parameter. Keep in mind, not all types are stored here.

Type:

str | None

value

Value of this parameter.

Type:

CellValue | str | None

p

An alias for param.

t

An alias for type.

v

An alias for value.

List-like Classes

class List(is_root: bool = False, type: str | None = None)

Bases: DeclarationsList[ListRow]

List represents ndf lists ([]), vector types (typename[]) and a collection of root level statements (source root).

is_root

Indicates whether this is a source root or any other nested item. Needed for printer format them differently.

Type:

bool, default=False

type

Stores type for vector types (like RGBA[0, 0, 0, 1]). See Typing Ambiguity in main documentation for more info.

Type:

str | None, default=None

by_n(namespace: str) → ListRow

by_n(namespace: str, strict: bool) → ListRow | None

by_name(namespace: str) → ListRow

by_name(namespace: str, strict: bool) → ListRow | None

by_namespace(namespace: str) → ListRow

by_namespace(namespace: str, strict: bool) → ListRow | None

Find row by it’s namespace. Returns first match that is found. If none found and strict is True then raises an error. If False then returns None. If strict is not set then it’s True by default.

rm_n(namespace: str)

remove_by_name(namespace: str)

remove_by_namespace(namespace: str)

Find and remove row by it’s namespace. Removes first occurence if found. Raises error if nothing found.

class Object

Bases: DeclarationsList[MemberRow]

Object represents ndf objects as a list of members.

type

Stores object’s type (for TObject( ... ) it’s type will be equal to TObject). See Typing Ambiguity in main documentation for more info.

Type:

str | None, default=None

by_n(namespace: str) → MemberRow

by_n(namespace: str, strict: bool) → MemberRow | None

by_name(namespace: str) → MemberRow

by_name(namespace: str, strict: bool) → MemberRow | None

by_namespace(namespace: str) → MemberRow

by_namespace(namespace: str, strict: bool) → MemberRow | None

Find row by it’s namespace. Returns first match that is found. If none found and strict is True then raises an error. If False then returns None. If strict is not set then it’s True by default.

rm_n(namespace: str)

remove_by_name(namespace: str)

remove_by_namespace(namespace: str)

Find and remove row by it’s namespace. Removes first occurence if found. Raises error if nothing found.

by_m(member: str) → MemberRow

by_m(member: str, strict: bool) → MemberRow | None

by_member(member: str) → MemberRow

by_member(member: str, strict: bool) → MemberRow | None

Returns first match that is found. If none found and strict is True then raises an error. If False then returns None. If strict is not set then it’s True by default.

rm_m(member: str)

remove_by_member(member: str)

Find and remove row by it’s member. Removes first occurence if found. Raises error if nothing found.

class Template

Bases: Object

Template represents ndf templates as a list of members and template params.

type

Stores template’s type (for template [ ... ] Ns is TObject( ... ) it’s type will be equal TObject). See Typing Ambiguity in main documentation for more info.

Type:

str | None, default=None

params

Attribute that holds template parameters.

Type:

Params

by_n(namespace: str) → MemberRow

by_n(namespace: str, strict: bool) → MemberRow | None

by_name(namespace: str) → MemberRow

by_name(namespace: str, strict: bool) → MemberRow | None

by_namespace(namespace: str, strict: bool = True) → MemberRow | None

Find row by it’s namespace. Returns first match that is found. If none found and strict is True then raises an error. If False then returns None. If strict is not set then it’s True by default.

rm_n(namespace: str)

remove_by_name(namespace: str)

remove_by_namespace(namespace: str)

Find and remove row by it’s namespace. Removes first occurence if found. Raises error if nothing found.

by_m(member: str) → MemberRow

by_m(member: str, strict: bool) → MemberRow | None

by_member(member: str, strict: bool = True) → MemberRow | None

Returns first match that is found. If none found and strict is True then raises an error. If False then returns None. If strict is not set then it’s True by default.

rm_m(member: str)

remove_by_member(member: str)

Find and remove row by it’s member. Removes first occurence if found. Raises error if nothing found.

class Params

Bases: DeclarationsList[ParamRow]

Params represents a list of generic parameters to be used in a template.

by_p(self, param: str) → ParamRow

by_p(self, param: str, strict: bool) → ParamRow | None

by_param(param: str) → ParamRow

by_param(param: str, strict: bool) → ParamRow | None

Find row by it’s namespace. Returns first match that is found. If none found and strict is True then raises an error. If False then returns None. If strict is not set then it’s True by default.

rm_p(param: str)

remove_by_param(param: str)

Find and remove row by it’s param. Removes first occurence if found. Raises error if nothing found.

class Map

Bases: DeclarationsList[MapRow]

Map represents ndf maps as a list of pairs represented as a MapRow. It supports checking if key is inside of it in pythonic way:

>>> pairs = Map()
>>> pairs.add('test', 'some_value')
>>> 'test' in pairs
True
>>> 'test2' in pairs
False
>>> 'some_value' in pairs  # checks only keys, not values!
False

by_k(self, key: str) → MapRow

by_k(self, key: str, strict: bool) → MapRow | None

by_key(key: str) → MapRow

by_key(key: str, strict: bool) → MapRow | None

Find row by it’s key. Returns first match or None if not found. If none found and strict is True then raises an error. If False then returns None. If strict is not set then it’s True by default.

rm_k(key: str)

remove_by_key(key: str)

Find and remove row by it’s key. Removes first occurence if found. Raises error if nothing found.

Typing

CellValue: type alias

List | Object | Template | Map | str