10.6.3. Base class for all API array objects

class pytan3.api_models.ApiList(*args, **kwargs)[source]

Bases: pytan3.api_models.ApiModel

Model for an array in the API.

API_ITEM_ATTR = None

str – Name of API_ITEM_CLS used in API calls.

API_ITEM_CLS = None

ApiItem – Item class this list class holds.

T_CLS_STR = '{obj.__class__.__name__}({attrs}) with {count} {item_cls} objects'

str – Template for class name and attrs in str.

__init__(*args, **kwargs)[source]

Constructor.

Parameters:
LIST = None

list of API_ITEM_CLS – List container for this class.

__str__()[source]

Show object info using ApiModel.api_attrs_str().

Returns:str
__repr__()[source]

Show object info using ApiModel.api_attrs_repr().

Returns:str
__len__()[source]

Return length of list container LIST.

Returns:int
__contains__(value)[source]

Support in operand.

Parameters:value (object) – Check if this value in LIST.

Notes

Will call api_coerce_item() to check value is of type defined in API_ITEM_CLS, but will return False if value is of wrong type and can not be coerced.

Returns:
Return type:bool
__add__(value)[source]

Support + operand.

Parameters:value (ApiList or list or tuple) – ApiList of this same type or a python list type to combine with this object.

Notes

This will use api_coerce_items() to perform type checking on each item in value.

Returns:A new instance with list items from this object combined with list items from value.
Return type:ApiList
__iadd__(value)[source]

Support += operand.

Parameters:value (ApiList or list or tuple) – ApiList of this same type or a python list type to combine with this object.

Notes

This will use api_coerce_items() to perform type checking on each item in value.

Returns:This object with list items from value appended.
Return type:ApiList
__getitem__(value)[source]

Support indexing of list container.

Parameters:value (int) – Index of item to retrieve from LIST.
Returns:The type of object this list contains.
Return type:API_ITEM_CLS
__setattr__(attr, value)[source]

Enforce type checking for attr and value.

Parameters:

Notes

If attr is either “LIST” or API_ITEM_ATTR, will use api_coerce_items() to perform type checking on each item in value.

If attr is same as API_ITEM_ATTR, the attr will be changed to “LIST”.

api_coerce_items(attr, value, op)[source]

Check that value is a list type and that all items value are the proper type.

Parameters:
  • attr (str) – Attribute being set on this object.
  • value (ApiList or list or tuple) – The list object holding items that should have type checking.
  • op (str) –

    Operation being performed that called this method.

    Used in exception messages.

Raises:

pytan3.api_models.exceptions.ListTypeError – If value is not a list or tuple or an ApiList that is the same type as this objects class.

Notes

Will call api_coerce_items_hook() before checking each item in value, which can be overridden by subclasses to modify value.

Will call api_coerce_item() to check each item in value is of type defined in API_ITEM_CLS.

Returns:The list of items with their values checked and coerced.
Return type:list
api_coerce_items_hook(attr, value, op)[source]

Check hook that allows subclasses to modify list items.

Parameters:
  • attr (str) – Attribute being set on this object.
  • value (ApiList or list or tuple) – The list object holding items.
  • op (str) – Operation being performed that called this method.

Notes

By default, this does nothing but return value unchanged.

Returns:The list of items modified or as is.
Return type:list
api_coerce_item(item, items, attr, op)[source]

Perform type checking of a list item.

Parameters:
  • item (object) – Item that is being checked.
  • items (ApiList or list or tuple) – The list object that item came from.
  • op (str) –

    Operation being performed that called this method.

    Used in exception messages.

Notes

Will coerce item into expected type if needed and possible.

Raises:pytan3.api_models.exceptions.ListItemTypeError – If item does not match the type from API_ITEM_CLS and it can not be coerced into the expected type.
Returns:object
classmethod api_attrs_desc()[source]

Get simple and complex attributes of an ApiModel object in string format.

Notes

Used by exceptions to add defined attributes to error messages.

Returns:list of str
classmethod api_item_cls_str()[source]

Get str of API_ITEM_CLS.

Returns:str
classmethod api_item_cls_is_complex()[source]

Check if API_ITEM_CLS is an ApiModel sub class.

Returns:bool
append(value)[source]

Support appending an item to list container.

Parameters:value (object) – Item to append to LIST.

Notes

Will call api_coerce_item() to check value is of type defined in API_ITEM_CLS.

remove(value)[source]

Support removing an item from list container.

Parameters:value (object) – Item to remove from LIST.
pop(value=-1)[source]

Support pop of an item from list container.

Parameters:value (object, optional) –

Item to pop from LIST.

Defaults to: -1.

reverse()[source]

Support reverse on list container.

get_item_by_attr(value, attr='name', regex_value=False)[source]

Support getting an item from list container by attr value.

Parameters:
  • value (object) – Value to check against the attr value of each item in LIST.
  • attr (str, optional) –

    Attribute to check if value matches.

    Defaults to: “name”.

  • regex_value (bool, optional) –

    Treat value as a regex pattern instead of comparing equality of value to attr value.

    Defaults to: False.

Raises:

pytan3.api_models.exceptions.GetSingleItemError – If number of items in LIST whose attr value matches value is either 0 or more than 1.

Returns:

The object from LIST whose attr value matches value.

Return type:

object

get_items_by_attr(value, attr='name', regex_value=False, new_list=False)[source]

Support getting items from list container by attr value.

Parameters:
  • value (object) – Value to check against the attr value of each item in LIST.
  • attr (str, optional) –

    Attribute to check if value matches.

    Defaults to: “name”.

  • regex_value (bool, optional) –

    Treat value as a regex pattern instead of comparing equality of value to attr value.

    Defaults to: False.

  • new_list (bool, optional) –

    Return a new class of this objects type with matching items instead of a regular python list type.

    Defaults to: False.

Returns:

All objects from LIST whose attr value matches value.

Return type:

list of object

pop_item_by_attr(value, attr='name', regex_value=False)[source]

Support popping an item from list container by attr value.

Parameters:
  • value (object) – Value to check against the attr value of each item in LIST.
  • attr (str, optional) –

    Attribute to check if value matches.

    Defaults to: “name”.

  • regex_value (bool, optional) –

    Treat value as a regex pattern instead of comparing equality of value to attr value.

    Defaults to: False.

Raises:

pytan3.api_models.exceptions.GetSingleItemError – If number of items in LIST whose attr value matches value is either 0 or more than 1.

Returns:

The object popped from LIST whose attr value matches value.

Return type:

object

pop_items_by_attr(value, attr='name', regex_value=False, new_list=False)[source]

Support popping items from list container by attr value.

Parameters:
  • value (object) – Value to check against the attr value of each item in LIST.
  • attr (str, optional) –

    Attribute to check if value matches.

    Defaults to: “name”.

  • regex_value (bool, optional) –

    Treat value as a regex pattern instead of comparing equality of value to attr value.

    Defaults to: False.

  • new_list (bool, optional) –

    Return a new class of this objects type with matching items instead of a regular python list type.

    Defaults to: False.

Returns:

All objects popped from LIST whose attr value matches value.

Return type:

list of object

sort(key=operator.attrgetter('id'), reverse=False)[source]

Support sorting items in list container in place.

Parameters:
  • key (object, optional) –

    Key to sort items in LIST on.

    Defaults to: operator.attrgetter(“id”).

  • reverse (bool, optional) –

    Reverse the sort mechanism.

    Defaults to: False.

serialize(empty=False, list_attrs=False, exclude_attrs=None, only_attrs=None, wrap_name=True, wrap_item_attr=True)[source]

Serialize this object into a dict.

Parameters:
  • empty (bool, optional) –

    Include attrs that have a value of None when serializing.

    Defaults to: False.

  • list_attrs (bool, optional) –

    Include simple attrs of ApiList when serializing.

    Defaults to: False.

  • exclude_attrs (list of str, optional) –

    Exclude these attrs when serializing.

    Defaults to: None.

  • only_attrs (list of str, optional) –

    Include only these attrs when serializing.

    Defaults to: None.

  • wrap_name (bool, optional) –

    Wrap return in a dict with key of ApiModel.API_NAME and value of return.

    Defaults to: True.

  • wrap_item_attr (bool, optional) –

    Wrap return in a dict with key of ApiList.API_ITEM_ATTR and value of return.

    Only used when serializing items of type ApiList.

    Defaults to: True.

Notes

All child objects will get wrap_name=False.

If wrap_name and wrap_item_attr are both False, return will be list of dict, otherwise return will be a dict.

Returns:list of object or dict