Reference

class vessel.Tool(...)

Bases: NamedTuple

Holds utilities for handling incoming data.

create: Callable[[list[TypeVar(_RootV)], TypeVar(_DataV)], TypeVar(_RootV)]

Used for converting the incoming data to the “root” form kept in cache.

identify: Callable[[list[TypeVar(_RootV)], TypeVar(_DataV)], Hashable]

Used for determining the incoming data’s unique key for cacheing.

update: Callable[[list[TypeVar(_RootV)], TypeVar(_RootV), TypeVar(_DataV)], TypeVar(_RootV)]

Used for updating existing “root”s found in cache with incoming data.

vessel.resolve(unit)

Get the root data for a unit.

class vessel.Unit(data: _DataV, /, *, unique=False)

Bases: Generic[_DataV]

For subclassing only.

class User(vessel.Unit, tool = ...):
    ...

user = User(data)

vessel.update(unit, data, **kwargs)

Update the unit’s root with new data.

Parameters:

• unit – The reference to the root data.

• data – The new data to update the root with.

class vessel.GetField(...)

Bases: NamedTuple

Holds information for fetching data specific to an attribute.

select: Callable[[TypeVar(_RootV)], TypeVar(_FieldValue)]

Used to fetch data from the internal root.

class vessel.SetField(...)

Bases: NamedTuple

Holds information for handling incoming data specific to a key.

create: Callable[[list[TypeVar(_RootV)], TypeVar(_FieldData)], TypeVar(_FieldRoot)]

Used to initially create data.

unique: bool

Whether it can be used to compose a keyify.

update: Callable[[list[TypeVar(_RootV)], TypeVar(_FieldRoot), TypeVar(_FieldData)], TypeVar(_FieldRoot)]

Used to update existing data.

vessel.unsafe(cls)

Context managers for raising AttributeError instead of returning :var:`.missing`.

class vessel.Object(data: _DataV, /, *, unique=False)

Bases: Unit[_DataV]

For subclassing only.

fields = {
    'id': vessel.SetField(
        create = lambda path, data: str(data),
        unique = True
    ),
    'name': vessel.SetField(
        create = lambda path, data: str(data)
    )
}

def identify(path, data):
    return str(data['id'])

class User(vessel.Unit, fields = fields, identify = identify):
    id: str = vessel.GetField(
        select = lambda root: root['id']
    )
    name: str = vessel.GetField(
        select = lambda root: root['name']
    )

data0 = {'id': 0, 'name': 'Zero'}
user0 = User(data0) # <User(id=0, name='Zero')>

data1 = {'id': 0, 'name': 'One'}
user1 = User(data1) # <User(id=0, name='One')>

user0 is user1 # True (identify matches)

vessel.keyify(cls, data)

Get the collection key of the incoming data for an Object class.

Parameters:

• cls (Object) – The class to use the keyify function of.

• data (TypeVar(_DataV)) – The data to use the keyify function on.

class vessel.List(data: _DataV, /, *, unique=False)

Bases: Unit[_DataV]

For subclassing only.

def create(path, data):
    return User(data)

class UserStore(List, create = create):
    pass

data = [{'id': 2, 'name': 'Two'}, {'id': 3, 'name': 'Three'}]

users = UserStore(data) # [<User(id=2, name='Two')>, <User(id=2, name='Three')>]

class vessel.Dict(data: _DataV, /, *, unique=False)

Bases: Unit[_DataV]

For subclassing only.

def create(path, data):
    return User(data)

def keyify(path, data):
    reutrn str(data['id'])

class UserStore(Dict, create = create, keyify = keyify):
    pass

data = [{'id': 4, 'name': 'Four'}, {'id': 5, 'name': 'Five'}]

users = UserStore(data) # {'4': <User(id=2, name='Two')>, '5': <User(id=2, name='Three')>}

vessel.add(unit, data)

Create, add and return using the data.

Return type:

Unit

vessel.pop(unit, key)

Remove and return using the key.

vessel.collect(cls, data, *, keyify=None, name=<function <lambda>>)

Creates a collection of Object`s based on whether keyification has been provided (either by setting :paramref:.SetField.unique` to True or using keyify).

Parameters:

• cls (TypeVar(_ObjectV)) – Used to create the create function.

• data (TypeVar(_DataV)) – Used for filling the collection with instances of cls.

• keyify (Callable[[list[list[TypeVar(_RootV)]], TypeVar(_DataV)], Hashable]) – Determines whether to use List or Dict as the collection base.

• name (Callable[[List | Dict], str]) – Used for fetching the name of the new collection.

Return type:

Sequence[TypeVar(_ObjectV)] | Mapping[Hashable, TypeVar(_ObjectV)]

Note

Using this with the same (cls, keyify, name) will re-use existing collection classes.

class vessel.Collection(Object: _ObjectV, *args, **kwargs)

Bases: Collection[_ObjectV]

Same as collect(), except can also be used as a typehint.

vessel.strip(unit)

Get the fully nested raw underlying data.