linkahead.high_level_api module

A high level API for accessing LinkAhead entities from within python. This module is experimental, and may be changed or removed in the future.

This is refactored from apiutils.

class linkahead.high_level_api.CaosDBMultiProperty

Bases: object

This implements a multi property using a python list.

Bases: object

datatype: str | None = None

description: str | None = None

id: int | None = None

importance: str | None = None

unit: str | None = None

class linkahead.high_level_api.CaosDBPythonEntity

Bases: object

add_parent(parent: CaosDBPythonUnresolvedParent | CaosDBPythonRecordType | str)

Add a parent to this entity. Either using an unresolved parent or using a real record type.

Strings as argument for parent will automatically be converted to an unresolved parent. Likewise, integers as argument will be automatically converted to unresolved parents with just an id.

attribute_as_list(name: str)

This is a workaround for the problem that lists containing only one element are indistinguishable from simple types in this representation.

TODO: still relevant? seems to be only a problem if LIST types are not used.

property description: Getter for the description.

static deserialize(serialization: dict): Deserialize a yaml representation of an entity in high level API form.

property file: Getter for the file.

get_parents()

Returns all parents of this entity.

Use has_parent for checking for existence of parents and add_parent for adding parents to this entity.

get_properties(): Return the names of all properties.

get_property(name: str)

Return the value of the property with name name.

Raise an exception if the property does not exist.

get_property_metadata(prop_name: str) → CaosDBPropertyMetaData

Retrieve the property metadata for the property with name prop_name.

If the property with the given name does not exist or is forbidden, raise an exception. Else return the metadata associated with this property.

If no metadata does exist yet for the given property, a new object will be created and returned.

prop_name: str: Name of the property to retrieve metadata for.

has_parent(parent: CaosDBPythonUnresolvedParent | CaosDBPythonRecordType)

Check whether this parent already exists for this entity.

Strings as argument for parent will automatically be converted to an unresolved parent. Likewise, integers as argument will be automatically converted to unresolved parents with just an id.

property id: Getter for the id.

property name: Getter for the name.

property path: Getter for the path.

property_exists(prop_name: str): Check whether a property exists already.

resolve_references(deep: bool, references: Container, visited: Dict[str | int, CaosDBPythonEntity] | None = None)

Resolve this entity’s references. This affects unresolved properties as well as unresolved parents.

deep: bool: If True recursively resolve references also for all resolved references.
references: Optional[db.Container]: A container with references that might be resolved. If None is passed as the container, this function tries to resolve entities from a running LinkAhead instance directly.

serialize(without_metadata: bool | None = None, plain_json: bool = False, visited: dict | None = None) → dict

Serialize necessary information into a dict.

Parameters:

without_metadata (bool, optional) – If True don’t set the metadata field in order to increase readability. Not recommended if deserialization is needed.
plain_json (bool, optional) – If True, serialize to a plain dict without any additional information besides the property values, name and id. This should conform to the format as specified by the json schema generated by the advanced user tools. It also sets all properties as top level items of the resulting dict. This implies without_metadata = True.

Returns:

out –

A dict corresponding to this entity.: ``.

Return type:

dict

set_property(name: str, value: Any, overwrite: bool = False, datatype: str | None = None)

Set a property for this entity with a name and a value.

If this property is already set convert the value into a list and append the value. This behavior can be overwritten using the overwrite flag, which will just overwrite the existing value.

name: str: Name of the property.
value: Any: Value of the property.
overwrite: bool: Use this if you definitely only want one property with that name (set to True).

use_parameter(name, value)

property version: Getter for the version.

class linkahead.high_level_api.CaosDBPythonFile

Bases: CaosDBPythonEntity

download(target=None)

class linkahead.high_level_api.CaosDBPythonProperty: Bases: CaosDBPythonEntity

class linkahead.high_level_api.CaosDBPythonRecord: Bases: CaosDBPythonEntity

class linkahead.high_level_api.CaosDBPythonRecordType: Bases: CaosDBPythonEntity

class linkahead.high_level_api.CaosDBPythonUnresolved: Bases: object

class linkahead.high_level_api.CaosDBPythonUnresolvedParent(id: int | None = None, name: str | None = None)

Bases: CaosDBPythonUnresolved

Parents can be either given by name or by ID.

When resolved, both fields should be set.

id: int | None = None

name: str | None = None

class linkahead.high_level_api.CaosDBPythonUnresolvedReference(id=None): Bases: CaosDBPythonUnresolved

linkahead.high_level_api.clean_json(data: dict | list, no_remove_id: bool = False, no_id_name: bool = False, no_remove_none: bool = False) → dict | list

Clean up a json object.

This function does the following on each child element of data (and not on data itself). Each step can be switched off by given the corresponding no_<step> option:

Turn id-name dicts into simple name strings: {"id": 123, "name": "foo"} -> "foo". This only happens if there are no other keys except for id and name.
Remove “id” keys from dicts.
Remove none-valued entries from dicts.

Parameters:

data (Union[dict, list]) – The data to be cleaned up.
no_remove_id (bool = False) – Do not remove id keys.
no_id_name (bool = False) – Do not turn id-name dicts into simple name strings.
no_remove_none (bool = False) – Do not remove None entries from dicts.

Returns:

out – The input object, but cleaned. This function works in place.

Return type:

Union[dict, list]

linkahead.high_level_api.convert_to_entity(python_object)

linkahead.high_level_api.convert_to_python_object(entity: Container | Entity, references: Container | None = None, visited: Dict[int, CaosDBPythonEntity] | None = None, resolve_references: bool | None = False)

Convert either a container of CaosDB entities or a single CaosDB entity into the high level representation.

The optional references parameter can be used to resolve references that occur in the converted entities and resolve them to their correct representations. (Entities that are not found remain as CaosDBPythonUnresolvedReferences, unless resolve_references is given and True.)

linkahead.high_level_api.create_entity_container(record: CaosDBPythonEntity): Convert this record into an entity container in standard format that can be used to insert or update entities in a running CaosDB instance.

linkahead.high_level_api.create_record(rtname: str, name: str | None = None, **kwargs)

Create a new record based on the name of a record type. The new record is returned.

rtname: str: The name of the record type.
name: str: This is optional. A name for the new record.
kwargs:: Additional arguments are used to set attributes of the new record.

linkahead.high_level_api.high_level_type_for_role(role: str)

linkahead.high_level_api.high_level_type_for_standard_type(standard_record: Entity)

linkahead.high_level_api.load_external_record(record_name: str): Retrieve a record by name and convert it to the high level API format.

linkahead.high_level_api.new_high_level_entity(entity: RecordType, importance_level: str, name: str | None = None)

Create an new record in high level format based on a record type in standard format.

entity: db.RecordType: The record type to initialize the new record from.
importance_level: str: None, obligatory, recommended or suggested Initialize new properties up to this level. Properties in the record type with no importance will be added regardless of the importance_level.
name: str: Name of the new record.

linkahead.high_level_api.query(query: str, resolve_references: bool | None = True, references: Container | None = None)

linkahead.high_level_api.sort_json(data: T) → T

Recursively create new object from data, where all dicts are sorted.

If data is neither a dict or list, return it unchanged.

linkahead.high_level_api.standard_type_for_high_level_type(high_level_record: CaosDBPythonEntity, return_string: bool = False): For a given CaosDBPythonEntity either return the corresponding class in the standard CaosDB API or - if return_string is True - return the role as a string.