4. The namedtuplex API

The namedtuplex API covers a variety of interfaces for the processing of resource path addresses, and the search of resources. The initial set of interfaces forcusses on filesystem resources in a basic distributed environment. This covers in particular a basic set of call parameters, which are common for a subset of the call interfaces.

The following table displays the standard parameters supported by the interfaces.

interface

factories

classes

collections.namedtuple

namedtupledefs.namedtuple

NamedTupleXABCMeta

AppClass

parameter

[namedtuple]

[namedtupledefs]

NamedTupleXABC

fields

c

c

m+c

m

fielddefaults (1)

–

c

m+c

m

merge

–

–

m+c

m

module (2) (3)

c

c

m+c

m

rename (3)

c

c

m+c

m

tuplefactory

–

–

m+c

m

typename

c

c

s

s

verbose (3)

c

c

m+c

m
m:

Parameter as class member variable, which is processed byt the metaclass for class creation and/or instance creation. In case of member variable these are prefixed by an underscore ‘_’. For example the members _fields and _fielddefaults:

class MyClassNonABC(namedtuplex.abc.NamedTupleXABC):
   _fields = ('a', 'b',)                      # processed during class creation
   _fielddefaults = (('a', 11), ('b', 22))        # processed during class creation and/or instance creation
s:

Parameter by standard class definition, e.g. the mixin MyMixinClass:

class MyClassNonABC(MyMixinClass, namedtuplex.abc.NamedTupleXABC):
   _fields = ('a', 'b',)

c:

Parameter as call parameters, either for methods, or functions. The method interfaces provide here parameters to be interpreted by the methods of static defined class members, while the function interface provide parameters for the dynamic creation of the assembled classes.

For example the parameters rename and fielddefaults are used by the factory namedtuplex.abc.namedtuplex() for the creation of the extended tuple class template as well as for the creation of the class. E.g.:

namedtuplex.abc.namedtuplex(
   'MyClass',                              # passed to collections.namedtuple
   ('a', 'b',),                            # processed and passed to collections.namedtuple
   rename=True,                            # processed and passed to collections.namedtuple
   fielddefaults=(('a', 11), ('b', 22),)   # processed by __new__ for class and instance creation
)
(c):

Call parameters provided by the system interface, e.g. for the __new__ call.

(1):

Depends on the actual tuplefactory.

(2):

Depends on the implementation, Python3.6+.

(3):

Optional parameters, these are venetually not available in all cases.

The inheritance of the special class members _fields and _fielddefaults is based on two behaviour patterns controlled by the member _merge. When the value of _merge is True, the values of _fileds and _fielddefaults are merged by right-hand concatenation to the values from the parent class. In case of mixin the values are merged by from-left-to-right concatenation to the values defined by the derived class. The values of _fielddefaults are merged by the required compliance to the behaviour of function defauls [PYFUNC]. Thus with a resulting right-hand side continous tuple of default values.

The following table depicts the inheritance behaviour and the possiblity of control by _merge.

class member

inherited

merge-ctrl

default

_fields

y

y

None

_fielddefaults

y

y

None

_merge

y

n

True

_module

y

n

None

_rename

y

n

False

_tuplefactory

n

n

namedtupledefs.namedtuple

_typename

n

n

classname

_verbose

y

n

False

The _fields and _fielddefaults members are merged by default, this could be prohibited by _merge=False. The default behaviour seems to be appropriate due to the nature of tuples and the most possible intention of inheritance for the extension of a previously defined base pattern. For example in order to extend the header of a protocol message with a message body. This makes sense, even though tuples are commonly not intended for inheritance.

4.1. Parameters

4.1.1. fields and _fields

Symbolic names of fields with identical semantics as the standard library collections.namedtuple. When used in combination with the parameter fielddefaults the semantics changes to the behaviour of function parameters with default values, see [PYFUNC].

fields := '(' <field-name> [, <fields>] ')'
field-name := <valid-character-one>[<field-name-tail>]
field-name-tail := <valid-character>[<field-name-tail>]
valid-character-one := [a-zA-Z]
valid-character := [a-zA-Z_0-9]

See also usage of parameters, design _fields, and [namedtuple].

4.1.2. fielddefaults and _fielddefaults

Optional support for default values of fields. A list of key-value pairs. Same semantics as the function call interfaces [PYFUNC],

fielddefaults := '(' <item-default> [, <fielddefaults>] ')'
item-default := '(' <key>, <value> ')'
key := (<item-index> | <item-name>)
value := <default-value>

See also usage of parameters, and design _fields.

4.1.3. merge and _merge

Sets the behaviour for the metaclass how to proceed with multiple base classes provided as mixin. The default behaviour is to merge the _fields and the _fielddefaults attributes. The merge requires the following prerequisites:

  1. The fieldnames must be valid.

  2. The merged fielddefaults has to comply to the Python function default options syntax [PYFUNC]. This in particular requires right-hand non-scattered values for the merged tuples.

    For example:

    class A:
    _fields = ('a', 'b', 'c',)
    _fielddefaults = (33,)

class B:
    _fields = ('d', 'e', 'f',)
    _fielddefaults = (66,)

class Merged(A, B):
    _merge = True

    This will not work, because the defaults for ‘d’ and ‘e’ are not determined:

    class Merged(A, B):
    _merge = True

# The meged fields:
#    _fields = ('a', 'b', 'c', 'd', 'e', 'f',)
#    _fielddefaults = (33, ?, ?, 66,)      # causes an error
                                           # c=33, d=?, e=?, f=66

    While the following will work:

    class A:
    _fields = ('a', 'b', 'c',)
    _fielddefaults = (33,)

class B:
    _fields = ('d', 'e', 'f',)
    _fielddefaults = (44, 55, 66,)

class Merged(A, B):
    _merge = True

    Resulting in:

    # The meged fields:
#    _fields = ('a', 'b', 'c', 'd', 'e', 'f',)
#    _fielddefaults = (33, 44, 55, 66,)    # this works
                                           # c=33, d=44, e=55, f=66

A typical example for this is to use it for protocol data units, e.g. assemble the message header and body. Another example is to assemble a tuple for log entries with a line-prefix concatenated with the logged message.

default := True

See also usage of parameters, and Class Interface Parameters NamedTupleX.

4.1.4. module and _module

Sets ‘__module__’ of the created class definition. Available beginning with Python-3.6.

See also usage of parameters, design module, and [namedtuple].

4.1.5. rename and _rename

If True replaces silently invalid field names by ‘_<item-index>’. Available beginning with Python-2.7, in Python3 beginning with Python-3.1 - so not in Python-3.0.

See also usage of parameters, design rename, and [namedtuple].

4.1.6. typename

Name of returned class of type namedtuple. The actual registered top-level base class is NamedTupleXABC - underneath object of course.

See also usage of parameters, and [namedtuple].

4.1.7. tuplefactory and _tuplefactory

The tuplefactory provides an alternative factory for the creation of a named tuple. The API has to support the identical interface, but is free to support more. The keyword parameters are passed through transparently after removing the template class specific options. Current available standard factories are:

tuplefactory := (
   namedtupledefs.namedtuple   # patched version of collections.namedtuple with fielddefaults
   collections.namedtuple      # standard library - no fielddefaults
)

default := namedtupledefs.namedtuple

See also usage of parameters, and design tuplefactory.

4.1.8. verbose and _verbose

Prints created class definition.

See also usage of parameters, design verbose, and [namedtuple].

The call interface provides for groups of functions and classes with a set of common parameters and additional context specific modifications.

The provided function sets comprise the categories:

  • Filesystem Positions and Navigation

  • Canonical Node Address

Various common options are supported, which may not be available for each interface.

4.2. Resources