dtypes

general

The dtype is the type of the elements in a buffer. Thanks to the ddtype system, it is very easy to create new dtypes on top of pretty much everything.

Definitions:

type:

a python type object (typically a class or a builtin type)

dtype:

data dtype, meaning the type of the elements in an array, it can be a type, but more generally anything that define a data format.

ddtype:

declaration of data type, meaning a packet of things decribing how to pack/unpack that dtype from/to an array

a ddtype always inherits from base class DDType which content is implemented at C level.

class DDType

base class for a declaration of data type (ddtype) DO NOT INSTANTIATE THIS CLASS FROM PYTHON, use on of its specialization instead

dsize

byte size of the dtype when packed

Type:: int

layout

layout of the packed data such as defined in module struct, or None if not defined

Type:: bytes

key: the python dtype itself if this DDType is declared, None if not declared

declare(dtype, ddtype): declare a new dtype

declared(key): return the content of the declaration for the givne dtype

specialized dtypes

class DDTypeFunctions(dsize, pack, unpack, layout=None)

create a dtype from pure python pack and unpack functions

Example

>>> enum_pack = {'apple':b'a', 'orange':b'o', 'cake':b'c'}
>>> enum_unpack = {v:k   for k,v in enum_direct.items()}
>>> enum_dtype = DDTypeFunctions(
...                     dsize=1,                         # 1 byte storage
...                     pack=enum_pack.__getitem__,      # this takes the python object and gives a bytes to dump
...                     unpack=enum_unpack.__getitem__,  # this takes the bytes and return a python object
...                     )
...
>>> a = typedlist(dtype=enum_dtype)             # declaration is not necessary

class DDTypeClass(type)

Create a dtype from a python class (can be a pure python class)

the given type must have the following attributes:

frombytes or from_bytes or from_buffer

static method that initialize the type from bytes

__bytes__ or tobytes or to_bytes

method that converts to bytes, the returned byte must always be of the same size

__packlayout__ (optional) string or bytes giving binary format returned by __bytes__, it must follow the specifications of module struct

__packsize__ (optional) defines the byte size returned by __bytes__, optional if __packlayout__ is provided

Example

>>> class test_class:
...     __packlayout__ = 'ff'
...     _struct = struct.Struct(__packlayout__)
...
...     def __init__(self, x, y):
...             self.x = x
...             self.y = y
...
...     def __bytes__(self):
...             return self._struct.pack(self.x, self.y)
...     @classmethod
...     def frombytes(cls, b):
...             return cls(*cls._struct.unpack(b))
...
...     def __repr__(self):
...             return '(x={}, y={})'.format(self.x, self.y)
...
>>> a = typedlist(dtype=test_class)    # no declaration needed

class DDTypeStruct(struct)

create a dtype from a Struct object from module struct

Example

>>> a = typedlist(dtype='fxBh')   # no declaration needed

class DDTypeCType(type)

Create a dtype from a ctype

Example

>>> class test_structure(ctypes.Structure):
...     _fields_ = [
...             ('x', ctypes.c_int),
...             ('y', ctypes.c_float),
...             ]
...     def __repr__(self):
...             return '(x={}, y={})'.format(self.x, self.y)
...
>>> a = typedlist(dtype=test_structure)

class DDTypeExtension

DDTypeTypeExtension(type, layout=None, constructor=None)

Create a dtype for a C extension type.

This is the most efficient kind of dtype in term of access/assignation time.

In order to put an extension object into an array, it satisfy the following conditions:

have fixed size known at the time of dtype creation (so any array element has the same)
contain only byte copiable data (so nothing particular is done when copying/destroying the objects)

Warning

These conditions MUST be ensured by the user when declaring an extension type as a dtype, or it will result in memory corruption and crash of the program

Example

>>> arrex.declare(vec3, DDTypeExtension(vec3, 'fff', vec3))