filip.models.ngsi_v2 package

This package contains models for FIWAREs NGSI-LD APIs

Submodules

filip.models.ngsi_v2.base module

Shared models that are used by multiple submodules

class filip.models.ngsi_v2.base.AttrsFormat(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Allowed options for attribute formats

KEY_VALUES = 'keyValues'
NORMALIZED = 'normalized'
VALUES = 'values'
pydantic model filip.models.ngsi_v2.base.BaseAttribute[source]

Bases: BaseModel

Model for an attribute is represented by a JSON object with the following syntax:

The attribute NGSI type is specified by the type property, whose value is a string containing the NGSI type.

The attribute metadata is specified by the metadata property. Its value is another JSON object which contains a property per metadata element defined (the name of the property is the name of the metadata element). Each metadata element, in turn, is represented by a JSON object containing the following properties:

Values of entity attributes. For adding it you need to nest it into a dict in order to give it a name.

Example

>>> data = {"type": <...>,
            "metadata": <...>}
>>> attr = BaseAttribute(**data)
Config:

  • validate_assignment: bool = True

Fields:
Validators:
field metadata: Dict[str, Metadata] | NamedMetadata | List[NamedMetadata] | Dict[str, Dict[str, str]] | None = {}

optional metadata describing properties of the attribute value like e.g. accuracy, provider, or a timestamp

Validated by:
field type: DataType | str = DataType.TEXT

The attribute type represents the NGSI value type of the attribute value. Note that FIWARE NGSI has its own type system for attribute values, so NGSI value types are not the same as JSON types. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

validator validate_metadata_type  »  metadata[source]

validator for field ‘metadata’

pydantic model filip.models.ngsi_v2.base.BaseNameAttribute[source]

Bases: BaseModel

Model to add the name property to an BaseAttribute Model. The attribute name describes what kind of property the attribute value represents of the entity

Fields:
Validators:
field name: str [Required]

The attribute name describes what kind of property the attribute value represents of the entity, for example current_speed. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

pydantic model filip.models.ngsi_v2.base.BaseValueAttribute[source]

Bases: BaseModel

Model to add the value property to an BaseAttribute Model. The Model is represented by a JSON object with the following syntax:

The attribute value is specified by the value property, whose value may be any JSON datatype.

Fields:
Validators:
field type: DataType | str = DataType.TEXT

The attribute type represents the NGSI value type of the attribute value. Note that FIWARE NGSI has its own type system for attribute values, so NGSI value types are not the same as JSON types. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field value: Any | None = None

the actual data

Validated by:
validator validate_value_type  »  value[source]

Validator for field ‘value’ The validator will try autocast the value based on the given type. If DataType.STRUCTUREDVALUE is used for type it will also serialize pydantic models. With latter operation all additional features of the original pydantic model will be dumped. If the type is unknown it will check json-serializable.

pydantic model filip.models.ngsi_v2.base.EntityPattern[source]

Bases: BaseModel

Entity pattern used to create subscriptions or registrations

Fields:
Validators:
field id: str | None = None
Constraints:

  • pattern = w

Validated by:
field idPattern: Pattern | None = None
Validated by:
field type: str | None = None
Constraints:

  • pattern = w

Validated by:
field typePattern: Pattern | None = None
Validated by:
validator validate_conditions  »  all fields[source]
pydantic model filip.models.ngsi_v2.base.Expression[source]

Bases: BaseModel

By means of a filtering expression, allows to express what is the scope of the data provided. https://telefonicaid.github.io/fiware-orion/api/v2/stable

Config:

  • arbitrary_types_allowed: bool = True

Fields:
Validators:
field coords: str | QueryString | None = None

String representation of coordinates as specified by the Geoqueries section of the specification.

field geometry: str | QueryString | None = None

Any of the supported geometries as specified by the Geoqueries section of this specification.

field georel: str | QueryString | None = None

Any of the geographical relationships as specified by the Geoqueries section of this specification.

field mq: str | QueryString | None = None

If filtering by metadata (i.e. the expression is used in a mq query), the second token represents a metadata name associated to the target NGSI attribute, target metadata, and the rest of tokens (if present) represent the path to a sub-property of the target metadata value (which should be a JSON object). Such sub-property is defined as the target property.

Validated by:
field q: str | QueryString | None = None

If filtering by attribute value (i.e. the expression is used in a q query), the rest of tokens (if present) represent the path to a sub-property of the target NGSI attribute value (which should be a JSON object). Such sub-property is defined as the target property.

Validated by:
serialize(serializer: Any, info: SerializationInfo)[source]
validator validate_expressions  »  q, mq[source]
pydantic model filip.models.ngsi_v2.base.Http[source]

Bases: BaseModel

Model for notification and registrations sent or retrieved via HTTP

Fields:
field url: Url [Required]

URL referencing the service to be invoked when a notification is generated. An NGSIv2 compliant server must support the http URL schema. Other schemas could also be supported.

Constraints:

  • allowed_schemes = [‘http’, ‘https’]

pydantic model filip.models.ngsi_v2.base.Metadata[source]

Bases: BaseModel

Context metadata is used in FIWARE NGSI in several places, one of them being an optional part of the attribute value as described above. Similar to attributes, each piece of metadata has.

Note

In NGSI it is not foreseen that metadata may contain nested metadata.

Fields:
Validators:
field type: DataType | str | None = None

a metadata type, describing the NGSI value type of the metadata value Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field value: Any | None = None

a metadata value containing the actual metadata

Validated by:
validator validate_value  »  value[source]
pydantic model filip.models.ngsi_v2.base.NamedMetadata[source]

Bases: Metadata

Model for metadata including a name

Fields:
Validators:
field name: str [Required]

a metadata name, describing the role of the metadata in the place where it occurs; for example, the metadata name accuracy indicates that the metadata value describes how accurate a given attribute value is. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:
field type: DataType | str | None = None

a metadata type, describing the NGSI value type of the metadata value Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:
field value: Any | None = None

a metadata value containing the actual metadata

Validated by:
to_context_metadata()[source]
validator validate_data  »  all fields[source]
class filip.models.ngsi_v2.base.Status(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Current status of a subscription or registrations

ACTIVE = 'active'
EXPIRED = 'expired'
FAILED = 'failed'
INACTIVE = 'inactive'

filip.models.ngsi_v2.context module

NGSIv2 models for context broker interaction

class filip.models.ngsi_v2.context.ActionType(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Options for queries

APPEND = 'append'
APPEND_STRICT = 'appendStrict'
DELETE = 'delete'
REPLACE = 'replace'
UPDATE = 'update'
pydantic model filip.models.ngsi_v2.context.Command[source]

Bases: BaseModel

Class for sending commands to IoT Devices. Note that the command must be registered via an IoT-Agent. Internally FIWARE uses its registration mechanism in order to connect the command with an IoT-Device

Fields:
Validators:
field type: DataType = DataType.COMMAND

Command must have the type command

field value: Any [Required]

Any json serializable command that will be forwarded to the connected IoT device

Validated by:
validator check_value  »  value[source]

Check if value is json serializable :param value: value field

Returns:

value

pydantic model filip.models.ngsi_v2.context.ContextAttribute[source]

Bases: BaseAttribute, BaseValueAttribute

Model for an attribute is represented by a JSON object with the following syntax:

The attribute value is specified by the value property, whose value may be any JSON datatype.

The attribute NGSI type is specified by the type property, whose value is a string containing the NGSI type.

The attribute metadata is specified by the metadata property. Its value is another JSON object which contains a property per metadata element defined (the name of the property is the name of the metadata element). Each metadata element, in turn, is represented by a JSON object containing the following properties:

Values of entity attributes. For adding it you need to nest it into a dict in order to give it a name.

Example

>>> data = {"value": <...>,
            "type": <...>,
            "metadata": <...>}
>>> attr = ContextAttribute(**data)
Config:

  • validate_assignment: bool = True

Fields:
Validators:
field metadata: Dict[str, Metadata] | NamedMetadata | List[NamedMetadata] | Dict[str, Dict[str, str]] | None = {}

optional metadata describing properties of the attribute value like e.g. accuracy, provider, or a timestamp

Validated by:
field type: DataType | str = DataType.TEXT

The attribute type represents the NGSI value type of the attribute value. Note that FIWARE NGSI has its own type system for attribute values, so NGSI value types are not the same as JSON types. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field value: Any | None = None

the actual data

Validated by:
pydantic model filip.models.ngsi_v2.context.ContextEntity[source]

Bases: ContextEntityKeyValues

Context entities, or simply entities, are the center of gravity in the FIWARE NGSI information model. An entity represents a thing, i.e., any physical or logical object (e.g., a sensor, a person, a room, an issue in a ticketing system, etc.). Each entity has an entity id. Furthermore, the type system of FIWARE NGSI enables entities to have an entity type. Entity types are semantic types; they are intended to describe the type of thing represented by the entity. For example, a context entity #with id sensor-365 could have the type temperatureSensor.

Each entity is uniquely identified by the combination of its id and type.

The entity id is specified by the object’s id property, whose value is a string containing the entity id.

The entity type is specified by the object’s type property, whose value is a string containing the entity’s type name.

Entity attributes are specified by additional properties, whose names are the name of the attribute and whose representation is described by the “ContextAttribute”-model. Obviously, id and type are not allowed as attribute names.

Example:

>>> data = {'id': 'MyId',
            'type': 'MyType',
            'my_attr': {'value': 20, 'type': 'Number'}}

>>> entity = ContextEntity(**data)
Config:

  • extra: str = allow

  • validate_default: bool = True

  • validate_assignment: bool = True

Fields:
Validators:
field id: str [Required]

Id of an entity in an NGSI context broker. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:
field type: str | Enum [Required]

Id of an entity in an NGSI context broker. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:
add_attributes(attrs: Dict[str, ContextAttribute] | List[NamedContextAttribute]) → None[source]

Add attributes (properties, relationships) to entity

Parameters:

attrs – Dict[str, ContextAttribute]: {NAME for attr : Attribute} or List[NamedContextAttribute]

Returns:

None

validator check_attributes  »  all fields[source]

Check whether all model fields are of subtype of ContextAttribute to ensure full functionality.

validator check_attributes_after  »  all fields[source]
delete_attributes(attrs: Dict[str, ContextAttribute] | List[NamedContextAttribute] | List[str])[source]

Delete the given attributes from the entity

Parameters:

attrs –

  • Dict {name: ContextAttribute}

  • List[NamedContextAttribute]

  • List[str] -> names of attributes

Raises:

Exception – if one of the given attrs does not represent an existing argument

get_attribute(attribute_name: str) → NamedContextAttribute[source]

Get the attribute of the entity with the given name

Parameters:

attribute_name (str) – Name of attribute

Raises:

KeyError, if no attribute with given name exists –

Returns:

NamedContextAttribute

get_attribute_names() → Set[str][source]

Returns a set with all attribute names of this entity

Returns:

Set[str]

get_attributes(whitelisted_attribute_types: List[DataType] | None = None, blacklisted_attribute_types: List[DataType] | None = None, response_format: str | PropertyFormat = PropertyFormat.LIST, strict_data_type: bool = True) → List[NamedContextAttribute] | Dict[str, ContextAttribute][source]

Get attributes or a subset from the entity.

Parameters:

  • whitelisted_attribute_types – Optional list, if given only attributes matching one of the types are returned

  • blacklisted_attribute_types – Optional list, if given all attributes are returned that do not match a list entry

  • response_format – Wanted result format, List -> list of NamedContextAttributes Dict -> dict of {name: ContextAttribute}

  • strict_data_type – whether to restrict the data type to pre-defined types, True by default. True -> Only return the attributes with pre-defined types, False -> Do not restrict the data type.

Raises:

AssertionError, if both a white and a black list is given –

Returns:

List[NamedContextAttribute] or Dict[str, ContextAttribute]

get_command_triple(command_attribute_name: str) → Tuple[NamedContextAttribute, NamedContextAttribute, NamedContextAttribute][source]

Returns for a given command attribute name all three corresponding attributes as triple

Parameters:

command_attribute_name – Name of the command attribute

Raises:

KeyError, if the given name does not belong to a command attribute –

Returns:

(Command, Command_status, Command_info)

get_commands(response_format: str | PropertyFormat = PropertyFormat.LIST) → List[NamedContextAttribute] | Dict[str, ContextAttribute][source]

Get all commands of the context entity. Only works if the commands were autogenerated by Fiware from an Device.

Parameters:

response_format – Wanted result format, List -> list of NamedContextAttributes Dict -> dict of {name: ContextAttribute}

Returns:

ContextAttribute}

Return type:

[NamedContextAttribute] or {name

get_properties(response_format: str | PropertyFormat = PropertyFormat.LIST) → List[NamedContextAttribute] | Dict[str, ContextAttribute][source]

Returns all attributes of the entity that are not of type Relationship, and are not auto generated command attributes

Parameters:

response_format – Wanted result format, List -> list of NamedContextAttributes Dict -> dict of {name: ContextAttribute}

Returns:

ContextAttribute}

Return type:

[NamedContextAttribute] or {name

get_relationships(response_format: str | PropertyFormat = PropertyFormat.LIST) → List[NamedContextAttribute] | Dict[str, ContextAttribute][source]

Get all relationships of the context entity

Parameters:

response_format – Wanted result format, List -> list of NamedContextAttributes Dict -> dict of {name: ContextAttribute}

Returns:

ContextAttribute}

Return type:

[NamedContextAttribute] or {name

update_attribute(attrs: Dict[str, ContextAttribute] | List[NamedContextAttribute]) → None[source]

Update attributes of an entity. Overwrite the current held value for the attribute with the value contained in the corresponding given attribute

Parameters:

attrs – List of NamedContextAttributes, Dict of {attribute_name: ContextAttribute}

Raises:

NameError, if the attribute does not currently exist in the entity –

Returns:

None

pydantic model filip.models.ngsi_v2.context.ContextEntityKeyValues[source]

Bases: BaseModel

Base Model for an entity is represented by a JSON object with the following syntax.

The entity id is specified by the object’s id property, whose value is a string containing the entity id.

The entity type is specified by the object’s type property, whose value is a string containing the entity’s type name.

Config:

  • extra: str = allow

  • validate_default: bool = True

  • validate_assignment: bool = True

Fields:
Validators:

  • wrapper » id

  • wrapper » type

field id: str [Required]

Id of an entity in an NGSI context broker. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field type: str | Enum [Required]

Id of an entity in an NGSI context broker. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

get_attributes() → dict[source]

Get the attribute of the entity with the given name in dict format

Returns:

dict

class filip.models.ngsi_v2.context.GetEntitiesOptions(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Options for queries

KEY_VALUES = 'keyValues'
NORMALIZED = 'normalized'
UNIQUE = 'unique'
VALUES = 'values'
pydantic model filip.models.ngsi_v2.context.NamedCommand[source]

Bases: Command

Class for sending command to IoT-Device. Extend :class: Command with command Name

Fields:
Validators:
field name: str [Required]

Name of the command

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field type: DataType = DataType.COMMAND

Command must have the type command

field value: Any [Required]

Any json serializable command that will be forwarded to the connected IoT device

Validated by:
pydantic model filip.models.ngsi_v2.context.NamedContextAttribute[source]

Bases: ContextAttribute, BaseNameAttribute

Context attributes are properties of context entities. For example, the current speed of a car could be modeled as attribute current_speed of entity car-104.

In the NGSI data model, attributes have an attribute name, an attribute type an attribute value and metadata.

Config:

  • validate_assignment: bool = True

Fields:
Validators:
field metadata: Dict[str, Metadata] | NamedMetadata | List[NamedMetadata] | Dict[str, Dict[str, str]] | None = {}

optional metadata describing properties of the attribute value like e.g. accuracy, provider, or a timestamp

Validated by:
field name: str [Required]

The attribute name describes what kind of property the attribute value represents of the entity, for example current_speed. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field type: DataType | str = DataType.TEXT

The attribute type represents the NGSI value type of the attribute value. Note that FIWARE NGSI has its own type system for attribute values, so NGSI value types are not the same as JSON types. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field value: Any | None = None

the actual data

Validated by:
class filip.models.ngsi_v2.context.PropertyFormat(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Format to decide if properties of ContextEntity class are returned as List of NamedContextAttributes or as Dict of ContextAttributes.

DICT = 'dict'
LIST = 'list'
pydantic model filip.models.ngsi_v2.context.Query[source]

Bases: BaseModel

Model for queries

Fields:
field attrs: List[str] | None = None

List of attributes to be provided (if not specified, all attributes).

field entities: List[EntityPattern] [Required]

a list of entities to search for. Each element is represented by a JSON object

field expression: Expression | None = None

An expression composed of q, mq, georel, geometry and coords

field metadata: List[str] | None = None

a list of metadata names to include in the response. See “Filtering out attributes and metadata” section for more detail.

pydantic model filip.models.ngsi_v2.context.Update[source]

Bases: BaseModel

Model for update action

Fields:
Validators:
field action_type: ActionType | str [Required] (alias 'actionType')

actionType, to specify the kind of update action to do: either append, appendStrict, update, delete, or replace.

Validated by:
field entities: List[ContextEntity | ContextEntityKeyValues] [Required]

an array of entities, each entity specified using the JSON entity representation format

validator check_action_type  »  action_type[source]

validates action_type :param action: field action_type

Returns:

action_type

filip.models.ngsi_v2.iot module

Module contains models for accessing and interaction with FIWARE’s IoT-Agents.

pydantic model filip.models.ngsi_v2.iot.Device[source]

Bases: DeviceSettings

Model for iot devices. https://iotagent-node-lib.readthedocs.io/en/latest/api/index.html#device-api

Config:

  • validate_assignment: bool = True

  • validate_default: bool = True

Fields:
Validators:
field apikey: str | None = None

Optional Apikey key string to use instead of group apikey

Validated by:
field attributes: List[DeviceAttribute] = []

List of active attributes of the device

Validated by:
field commands: List[DeviceCommand] = []
Validated by:
field device_id: str [Required]

Device ID that will be used to identify the device

Validated by:
field endpoint: AnyHttpUrl | None = None

Endpoint where the device is going to receive commands, if any.

Validated by:
field entity_name: str [Required]

Name of the entity representing the device in the Context Broker Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:
field entity_type: str [Required]

Type of the entity in the Context Broker. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:
field explicitAttrs: bool | None = False

optional boolean value, to support selective ignore of measures so that IOTA does not progress. If not specified default is false.

Validated by:
field expressionLanguage: ExpressionLanguage | None = ExpressionLanguage.JEXL

optional boolean value, to set expression language used to compute expressions, possible values are: legacy or jexl, but legacy is deprecated. If it is set None, jexl is used.

Validated by:
field internal_attributes: List[Dict[str, Any]] | None = []

List of internal attributes with free format for specific IoT Agent configuration

Validated by:
field lazy: List[LazyDeviceAttribute] = []

List of lazy attributes of the device

Validated by:
field ngsiVersion: NgsiVersion = NgsiVersion.v2

optional string value used in mixed mode to switch between NGSI-v2 and NGSI-LD payloads. Possible values are: v2 or ld. The default is v2. When not running in mixed mode, this field is ignored.

Validated by:
field protocol: PayloadProtocol | str | None = None

Name of the device protocol, for its use with an IoT Manager.

Validated by:
field service: str | None = None

Name of the service the device belongs to (will be used in the fiware-service header).

Constraints:

  • max_length = 50

Validated by:
field service_path: str | None = '/'

Name of the subservice the device belongs to (used in the fiware-servicepath header).

Constraints:

  • max_length = 51

  • pattern = ^/

Validated by:
field static_attributes: List[StaticDeviceAttribute] | None = []

List of static attributes to append to the entity. All the updateContext requests to the CB will have this set of attributes appended.

Validated by:
field timestamp: bool | None = None

Optional flag about whether or not to add the TimeInstant attribute to the device entity created, as well as a TimeInstant metadata to each attribute, with the current timestamp. With NGSI-LD, the Standard observedAt property-of-a-property is created instead.

Validated by:
field timezone: str | None = 'Europe/London'

Time zone of the sensor if it has any

Validated by:
field transport: TransportProtocol | str | None = None

Name of the device transport protocol, for the IoT Agents with multiple transport protocols.

Validated by:
add_attribute(attribute: DeviceAttribute | LazyDeviceAttribute | StaticDeviceAttribute | DeviceCommand, update: bool = False) → None[source]
Parameters:

  • attribute –

  • update (bool) – If ‘True’ and attribute does already exists tries to update the attribute if not

Returns:

None

add_command(command: DeviceCommand, update: bool = False)[source]

Short for self.add_attribute :param command: :type command: DeviceCommand :param update: Update command if it already exists :type update: bool

Returns:

delete_attribute(attribute: DeviceAttribute | LazyDeviceAttribute | StaticDeviceAttribute | DeviceCommand)[source]

Deletes attribute from device :param attribute: ()

Returns:

delete_command(command: DeviceCommand)[source]

Short for self.delete_attribute :param command:

Returns:

None

get_attribute(attribute_name: str) → DeviceAttribute | LazyDeviceAttribute | StaticDeviceAttribute | DeviceCommand[source]
Parameters:

attribute_name –

Returns:

get_command(command_name: str)[source]

Short for self.get_attributes :param command_name: :type command_name: str

Returns:

update_attribute(attribute: DeviceAttribute | LazyDeviceAttribute | StaticDeviceAttribute | DeviceCommand, append: bool = False) → None[source]

Updates existing device attribute

Parameters:

  • attribute – Attribute to add to device configuration

  • append (bool) – Adds attribute if not exist

Returns:

None

update_command(command: DeviceCommand, append: bool = False)[source]

Short for self.update_attribute :param command: :param append:

Returns:

validator validate_device_attributes_expression  »  all fields[source]

Validates device attributes expressions based on the expression language (JEXL or Legacy, where Legacy is deprecated).

Parameters:

self – The Device instance.

Returns:

The Device instance after validation.

validator validate_device_attributes_name_object_id  »  all fields[source]

Validate the device regarding the behavior with devices attributes. According to https://iotagent-node-lib.readthedocs.io/en/latest/api.html and based on our best practice, following rules are checked

  • name is required, but not necessarily unique

  • object_id is not required, if given must be unique, i.e. not equal to any

    existing object_id and name

Parameters:

self – dict of Device instance.

Returns:

The dict of Device instance after validation.

validator validate_duplicated_device_attributes  »  all fields[source]

Check whether device has identical attributes :param self: dict of Device instance.

Returns:

The dict of Device instance after validation.

validator validate_timezone  »  timezone[source]

validate timezone :returns: timezone

pydantic model filip.models.ngsi_v2.iot.DeviceAttribute[source]

Bases: IoTABaseAttribute

Model for active device attributes

Config:

  • validate_assignment: bool = True

Fields:
Validators:
field entity_name: str | None = None

entity_name: the presence of this attribute indicates that the value will not be stored in the original device entity but in a new entity with an ID given by this attribute. The type of this additional entity can be configured with the entity_type attribute. If no type is configured, the device entity type is used instead. Entity names can be defined as expressions, using the Expression Language definition (https://iotagent-node-lib.readthedocs.io/en/latest/api.html#expression-language-support). Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field entity_type: str | None = None

configures the type of an alternative entity. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field expression: str | None = None

indicates that the value of the target attribute will not be the plain value or the measurement, but an expression based on a combination of the reported values. See the Expression Language definition for details (https://iotagent-node-lib.readthedocs.io/en/latest/api.html#expression-language-support)

field metadata: Dict[str, Metadata] | NamedMetadata | List[NamedMetadata] | Dict[str, Dict[str, str]] | None = {}

optional metadata describing properties of the attribute value like e.g. accuracy, provider, or a timestamp

Validated by:
field name: str [Required]

The attribute name describes what kind of property the attribute value represents of the entity, for example current_speed. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field object_id: str | None = None

name of the attribute as coming from the device.

field reverse: str | None = None

add bidirectionality expressions to the attribute. See the bidirectionality transformation plugin in the Data Mapping Plugins section for details. (https://iotagent-node-lib.readthedocs.io/en/latest/api/index.html#data-mapping-plugins)

field type: DataType | str = DataType.TEXT

The attribute type represents the NGSI value type of the attribute value. Note that FIWARE NGSI has its own type system for attribute values, so NGSI value types are not the same as JSON types. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

pydantic model filip.models.ngsi_v2.iot.DeviceCommand[source]

Bases: BaseModel

Model for commands

Fields:
Validators:
field name: str [Required]

ID of the attribute in the target entity in the Context Broker. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field type: DataType | str = DataType.COMMAND

name of the type of the attribute in the target entity.

pydantic model filip.models.ngsi_v2.iot.DeviceSettings[source]

Bases: BaseModel

Model for iot device settings

Config:

  • validate_assignment: bool = True

Fields:
Validators:
field apikey: str | None = None

Optional Apikey key string to use instead of group apikey

field endpoint: AnyHttpUrl | None = None

Endpoint where the device is going to receive commands, if any.

field explicitAttrs: bool | None = False

optional boolean value, to support selective ignore of measures so that IOTA does not progress. If not specified default is false.

field expressionLanguage: ExpressionLanguage | None = ExpressionLanguage.JEXL

optional boolean value, to set expression language used to compute expressions, possible values are: legacy or jexl, but legacy is deprecated. If it is set None, jexl is used.

Validated by:
field protocol: PayloadProtocol | str | None = None

Name of the device protocol, for its use with an IoT Manager.

field timestamp: bool | None = None

Optional flag about whether or not to add the TimeInstant attribute to the device entity created, as well as a TimeInstant metadata to each attribute, with the current timestamp. With NGSI-LD, the Standard observedAt property-of-a-property is created instead.

field timezone: str | None = 'Europe/London'

Time zone of the sensor if it has any

field transport: TransportProtocol | str | None = None

Name of the device transport protocol, for the IoT Agents with multiple transport protocols.

classmethod valid_expressionLanguage(expressionLanguage)
class filip.models.ngsi_v2.iot.ExpressionLanguage(value)[source]

Bases: str, Enum

Options for expression language

JEXL = 'jexl'
LEGACY = 'legacy'
pydantic model filip.models.ngsi_v2.iot.IoTABaseAttribute[source]

Bases: BaseAttribute, BaseNameAttribute

Base model for device attributes

Config:

  • validate_assignment: bool = True

Fields:
Validators:
field entity_name: str | None = None

entity_name: the presence of this attribute indicates that the value will not be stored in the original device entity but in a new entity with an ID given by this attribute. The type of this additional entity can be configured with the entity_type attribute. If no type is configured, the device entity type is used instead. Entity names can be defined as expressions, using the Expression Language definition (https://iotagent-node-lib.readthedocs.io/en/latest/api.html#expression-language-support). Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field entity_type: str | None = None

configures the type of an alternative entity. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field expression: str | None = None

indicates that the value of the target attribute will not be the plain value or the measurement, but an expression based on a combination of the reported values. See the Expression Language definition for details (https://iotagent-node-lib.readthedocs.io/en/latest/api.html#expression-language-support)

field metadata: Dict[str, Metadata] | NamedMetadata | List[NamedMetadata] | Dict[str, Dict[str, str]] | None = {}

optional metadata describing properties of the attribute value like e.g. accuracy, provider, or a timestamp

Validated by:
field name: str [Required]

The attribute name describes what kind of property the attribute value represents of the entity, for example current_speed. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field reverse: str | None = None

add bidirectionality expressions to the attribute. See the bidirectionality transformation plugin in the Data Mapping Plugins section for details. (https://iotagent-node-lib.readthedocs.io/en/latest/api/index.html#data-mapping-plugins)

field type: DataType | str = DataType.TEXT

The attribute type represents the NGSI value type of the attribute value. Note that FIWARE NGSI has its own type system for attribute values, so NGSI value types are not the same as JSON types. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

pydantic model filip.models.ngsi_v2.iot.LazyDeviceAttribute[source]

Bases: BaseNameAttribute

Model for lazy device attributes

Fields:
Validators:
field name: str [Required]

The attribute name describes what kind of property the attribute value represents of the entity, for example current_speed. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field type: DataType | str = DataType.TEXT

The attribute type represents the NGSI value type of the attribute value. Note that FIWARE NGSI has its own type system for attribute values, so NGSI value types are not the same as JSON types. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

class filip.models.ngsi_v2.iot.PayloadProtocol(value)[source]

Bases: str, Enum

Options for payload protocols

IOTA_JSON = 'IoTA-JSON'
IOTA_UL = 'PDI-IoTA-UltraLight'
LORAWAN = 'LoRaWAN'
pydantic model filip.models.ngsi_v2.iot.ServiceGroup[source]

Bases: BaseModel

Model for device service group. https://iotagent-node-lib.readthedocs.io/en/latest/api/index.html#service-group-api

Fields:
Validators:
field apikey: str [Required]

API Key string. It is a key used for devices belonging to this service_group. If , service_group does not use apikey, but it must be specified.

field attributes: List[DeviceAttribute] | None = []

list of common commands attributes of the device. For each attribute, its name and type must be provided, additional metadata is optional.

field autoprovision: bool | None = True

optional boolean: If false, autoprovisioned devices (i.e. devices that are not created with an explicit provision operation but when the first measure arrives) are not allowed in this group. Default (in the case of omitting the field) is true.

field cbHost: AnyHttpUrl | None = None

Context Broker connection information. This options can be used to override the global ones for specific types of devices.

Validated by:
field commands: List[DeviceCommand] | None = []
field defaultEntityNameConjunction: str | None = None

optional string value to set default conjunction string used to compose a default entity_name when is not provided at device provisioning time.

field entity_type: str | None = None

name of the Entity type to assign to the group. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field explicitAttrs: bool | None = False

optional boolean value, to support selective ignore of measures so that IOTA does not progress. If not specified default is false.

field expressionLanguage: ExpressionLanguage | None = ExpressionLanguage.JEXL

optional boolean value, to set expression language used to compute expressions, possible values are: legacy or jexl, but legacy is deprecated. If it is set None, jexl is used.

Validated by:
field internal_attributes: List[Dict[str, Any]] | None = []

optional section with free format, to allow specific IoT Agents to store information along with the devices in the Device Registry.

field lazy: List[LazyDeviceAttribute] | None = []
field ngsiVersion: NgsiVersion | None = 'v2'

optional string value used in mixed mode to switch between NGSI-v2 and NGSI-LD payloads. Possible values are: v2 or ld. The default is v2. When not running in mixed mode, this field is ignored.

field resource: str [Required]

string representing the Southbound resource that will be used to assign a type to a device (e.g.: pathname in the southbound port).

field service: str | None = None

ServiceGroup of the devices of this type

field static_attributes: List[StaticDeviceAttribute] | None = []

this attributes will be added to all the entities of this group ‘as is’, additional metadata is optional.

field subservice: str | None = None

Subservice of the devices of this type.

Constraints:

  • pattern = ^/

field timestamp: bool | None = None

Optional flag about whether or not to add the TimeInstant attribute to the device entity created, as well as a TimeInstant metadata to each attribute, with the current timestamp. With NGSI-LD, the Standard observedAt property-of-a-property is created instead.

field trust: str | None = None

trust token to use for secured access to the Context Broker for this type of devices (optional; only needed for secured scenarios).

classmethod valid_expressionLanguage(expressionLanguage)
validator validate_cbHost  »  cbHost[source]

convert cbHost to str :returns: timezone

pydantic model filip.models.ngsi_v2.iot.StaticDeviceAttribute[source]

Bases: IoTABaseAttribute, BaseValueAttribute

Model for static device attributes

Config:

  • validate_assignment: bool = True

Fields:
Validators:
field entity_name: str | None = None

entity_name: the presence of this attribute indicates that the value will not be stored in the original device entity but in a new entity with an ID given by this attribute. The type of this additional entity can be configured with the entity_type attribute. If no type is configured, the device entity type is used instead. Entity names can be defined as expressions, using the Expression Language definition (https://iotagent-node-lib.readthedocs.io/en/latest/api.html#expression-language-support). Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field entity_type: str | None = None

configures the type of an alternative entity. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field expression: str | None = None

indicates that the value of the target attribute will not be the plain value or the measurement, but an expression based on a combination of the reported values. See the Expression Language definition for details (https://iotagent-node-lib.readthedocs.io/en/latest/api.html#expression-language-support)

field metadata: Dict[str, Metadata] | NamedMetadata | List[NamedMetadata] | Dict[str, Dict[str, str]] | None = {}

optional metadata describing properties of the attribute value like e.g. accuracy, provider, or a timestamp

Validated by:
field name: str [Required]

The attribute name describes what kind of property the attribute value represents of the entity, for example current_speed. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field reverse: str | None = None

add bidirectionality expressions to the attribute. See the bidirectionality transformation plugin in the Data Mapping Plugins section for details. (https://iotagent-node-lib.readthedocs.io/en/latest/api/index.html#data-mapping-plugins)

field type: DataType | str = DataType.TEXT

The attribute type represents the NGSI value type of the attribute value. Note that FIWARE NGSI has its own type system for attribute values, so NGSI value types are not the same as JSON types. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

Validated by:

  • wrapper

field value: Any | None = None

the actual data

Validated by:
class filip.models.ngsi_v2.iot.TransportProtocol(value)[source]

Bases: str, Enum

Options for transport protocols

AMQP = 'AMQP'
HTTP = 'HTTP'
MQTT = 'MQTT'

filip.models.ngsi_v2.registrations module

This module contains NGSIv2 models for context registrations in the context broker.

pydantic model filip.models.ngsi_v2.registrations.DataProvided[source]

Bases: BaseModel

Model for provided data

Fields:
field attrs: List[str] | None = None

List of attributes to be provided (if not specified, all attributes)

field entities: List[EntityPattern] [Required]

A list of objects, each one composed by an entity object

field expression: str | Expression | None = None

By means of a filtering expression, allows to express what is the scope of the data provided. Currently only geographical scopes are supported

pydantic model filip.models.ngsi_v2.registrations.ForwardingInformation[source]

Bases: BaseModel

Config:

  • frozen: bool = True

Fields:
field lastFailure: datetime | None = None

(not editable, only present in GET operations): Last failure timestamp in ISO8601 format. Not present if registration has never had a problem with forwarding.

field lastForwarding: datetime [Required]

(not editable, only present in GET operations): Last forwarding timestamp in ISO8601 format.

field lastSuccess: datetime | None = None

(not editable, only present in GET operations): Timestamp in ISO8601 format for last successful request forwarding. Not present if registration has never had a successful notification.

field timesSent: int [Required]

(not editable, only present in GET operations): Number of forwarding requests sent due to this registration.

class filip.models.ngsi_v2.registrations.ForwardingMode(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

An enumeration.

ALL = 'all'
NONE = 'none'
QUERY = 'query'
UPDATE = 'update'
pydantic model filip.models.ngsi_v2.registrations.Provider[source]

Bases: BaseModel

Fields:
field http: Http [Required]

It is used to convey parameters for providers that deliver information through the HTTP protocol. (Only protocol supported nowadays). It must contain a subfield named url with the URL that serves as the endpoint that offers the providing interface. The endpoint must not include the protocol specific part (for instance /v2/entities).

field supportedForwardingMode: ForwardingMode = ForwardingMode.ALL

It is used to convey the forwarding mode supported by this context provider. By default all.

pydantic model filip.models.ngsi_v2.registrations.Registration[source]

Bases: BaseModel

A Context Registration allows to bind external context information sources so that they can play the role of providers of certain subsets (entities, attributes) of the context information space, including those located at specific geographical areas.

Fields:
field dataProvided: DataProvided [Required]

Object that describes the data provided by this source

field description: str | None = None

A free text used by the client to describe the registration.

field expires: datetime | None = None

Registration expiration date in ISO8601 format. Permanent registrations must omit this field.

field forwardingInformation: ForwardingInformation | None = None

Information related to the forwarding operations made against the provider. Automatically provided by the implementation, in the case such implementation supports forwarding capabilities.

field id: str | None = None

Unique identifier assigned to the registration. Automatically generated at creation time.

field provider: Provider [Required]

Object that describes the context source registered.

field status: Status | None = Status.ACTIVE

Either active (for active registration) or inactive (for inactive registration). If this field is not provided at registration creation time, new registration are created with the active status, which can be changed by clients afterwards. For expired registration, this attribute is set to expired (no matter if the client updates it to active/inactive). Also, for subscriptions experiencing problems with notifications, the status is set to failed. As soon as the notifications start working again, the status is changed back to active.

filip.models.ngsi_v2.subscriptions module

This module contains NGSIv2 models for context subscription in the context broker.

pydantic model filip.models.ngsi_v2.subscriptions.Condition[source]

Bases: BaseModel

Notification rules are as follow: If attrs and expression are used, a notification is sent whenever one of the attributes in the attrs list changes and at the same time expression matches. If attrs is used and expression is not used, a notification is sent whenever any of the attributes in the attrs list changes. If attrs is not used and expression is used, a notification is sent whenever any of the attributes of the entity changes and at the same time expression matches. If neither attrs nor expression are used, a notification is sent whenever any of the attributes of the entity changes. alterationTypes: for more information about this field, see https://github.com/telefonicaid/fiware-orion/blob/3.8.0/doc/manuals/orion-api.md#subscriptions-based-in-alteration-type

Fields:
Validators:
field alterationTypes: List[str] | None = None

list of alteration types triggering the subscription

Validated by:
field attrs: str | List[str] | None = None

array of attribute names

Validated by:
field expression: str | Expression | None = None

an expression composed of q, mq, georel, geometry and coords (see “List entities” operation above about this field).

validator check_alteration_types  »  alterationTypes[source]
validator check_attrs  »  attrs[source]
pydantic model filip.models.ngsi_v2.subscriptions.HttpCustom[source]

Bases: Http

Model for custom notification patterns sent via HTTP

Fields:
Validators:
field headers: Dict[str, str | Json] | None = None

a key-map of HTTP headers that are included in notification messages.

Validated by:
field method: str = HttpMethods.POST

the method to use when sending the notification (default is POST). Only valid HTTP methods are allowed. On specifying an invalid HTTP method, a 400 Bad Request error is returned.

Validated by:
field ngsi: NgsiPayload | None = None

get an NGSI-v2 normalized entity as notification.If omitted, the default payload (see “Notification Messages” sections) is used.

Validated by:
field payload: str | None = None

the payload to be used in notifications. If omitted, the default payload (see “Notification Messages” sections) is used.

Validated by:
field qs: Dict[str, str | Json] | None = None

a key-map of URL query parameters that are included in notification messages.

Validated by:
field timeout: int | None = None

Maximum time (in milliseconds) the subscription waits for the response. The maximum value allowed for this parameter is 1800000 (30 minutes). If timeout is defined to 0 or omitted, then the value passed as -httpTimeout CLI parameter is used. See section in the ‘Command line options’ for more details.

Validated by:
field url: AnyHttpUrl [Required]

URL referencing the service to be invoked when a notification is generated. An NGSIv2 compliant server must support the http URL schema. Other schemas could also be supported.

Constraints:

  • allowed_schemes = [‘http’, ‘https’]

Validated by:
validator validate_notification_payloads  »  all fields[source]
class filip.models.ngsi_v2.subscriptions.HttpMethods(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

An enumeration.

PATCH = 'PATCH'
POST = 'POST'
PUT = 'PUT'
pydantic model filip.models.ngsi_v2.subscriptions.Message[source]

Bases: BaseModel

Model for a notification message, when sent to other NGSIv2-APIs

Fields:
field data: List[ContextEntity] [Required]

is an array with the notification data itself which includes the entity and all concerned attributes. Each element in the array corresponds to a different entity. By default, the entities are represented in normalized mode. However, using the attrsFormat modifier, a simplified representation mode can be requested.

field subscriptionId: str | None = None

Id of the subscription the notification comes from

pydantic model filip.models.ngsi_v2.subscriptions.Mqtt[source]

Bases: BaseModel

Model for notifications sent via MQTT https://fiware-orion.readthedocs.io/en/3.8.0/user/mqtt_notifications/index.html

Fields:
Validators:
field passwd: str | None = None

password if required

field qos: int | None = 0

to specify the MQTT QoS value to use in the notifications associated to the subscription (0, 1 or 2). This is an optional field, if omitted then QoS 0 is used.

Constraints:

  • ge = 0

  • le = 2

field topic: str [Required]

to specify the MQTT topic to use

Validated by:

  • wrapper

field url: Url | str [Required]

to specify the MQTT broker endpoint to use. URL must start with mqtt:// and never contains a path (i.e. it only includes host and port)

Validated by:
field user: str | None = None

username if required

validator check_url  »  url[source]

Check if url has a valid structure :param value: url to validate

Returns:

validated url

pydantic model filip.models.ngsi_v2.subscriptions.MqttCustom[source]

Bases: Mqtt

Model for custom notification patterns sent via MQTT https://fiware-orion.readthedocs.io/en/3.8.0/user/mqtt_notifications/index.html

Fields:
Validators:
field ngsi: NgsiPayload | None = None

get an NGSI-v2 normalized entity as notification.If omitted, the default payload (see “Notification Messages” sections) is used.

Validated by:
field passwd: str | None = None

password if required

Validated by:
field payload: str | None = None

the payload to be used in notifications. If omitted, the default payload (see “Notification Messages” sections) is used.

Validated by:
field qos: int | None = 0

to specify the MQTT QoS value to use in the notifications associated to the subscription (0, 1 or 2). This is an optional field, if omitted then QoS 0 is used.

Constraints:

  • ge = 0

  • le = 2

Validated by:
field topic: str [Required]

to specify the MQTT topic to use

Validated by:
field url: AnyMqttUrl | str [Required]

to specify the MQTT broker endpoint to use. URL must start with mqtt:// and never contains a path (i.e. it only includes host and port)

Validated by:
field user: str | None = None

username if required

Validated by:
validator validate_payload_type  »  all fields[source]
pydantic model filip.models.ngsi_v2.subscriptions.NgsiPayload[source]

Bases: BaseModel

Model for NGSI V2 type payload in httpCustom/mqttCustom notifications. Differences between this model and the usual Context entity models include:

  • id and type are not mandatory

  • an attribute metadata field is not allowed

Config:

  • extra: str = allow

  • validate_default: bool = True

Fields:
Validators:
field id: str | None = None
Constraints:

  • min_length = 1

  • max_length = 256

Validated by:
field type: str | Enum | None = None
Constraints:

  • min_length = 1

  • max_length = 256

Validated by:
validator validate_notification_attrs  »  all fields[source]
pydantic model filip.models.ngsi_v2.subscriptions.NgsiPayloadAttr[source]

Bases: BaseModel

Model for NGSI V2 type payload in httpCustom/mqttCustom notifications. The difference between this model and the usual BaseValueAttribute model is that a metadata field is not allowed. In the absence of type/value in some attribute field, one should resort to partial representations ( as specified in the orion api manual), done by the BaseValueAttr. model.

Config:

  • extra: str = forbid

Fields:
field type: DataType | str = DataType.TEXT

The attribute type represents the NGSI value type of the attribute value. Note that FIWARE NGSI has its own type system for attribute values, so NGSI value types are not the same as JSON types. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

field value: Any | None = None

the actual data

pydantic model filip.models.ngsi_v2.subscriptions.Notification[source]

Bases: BaseModel

If the notification attributes are left empty, all attributes will be included in the notifications. Otherwise, only the specified ones will be included.

Config:

  • validate_assignment: bool = True

Fields:
Validators:
field attrs: List[str] | None = None

List of attributes to be included in notification messages. It also defines the order in which attributes must appear in notifications when attrsFormat value is used (see “Notification Messages” section). An empty list means that all attributes are to be included in notifications. See “Filtering out attributes and metadata” section for more detail.

Validated by:
field attrsFormat: AttrsFormat | None = AttrsFormat.NORMALIZED

specifies how the entities are represented in notifications. Accepted values are normalized (default), keyValues or values. If attrsFormat takes any value different than those, an error is raised. See detail in “Notification Messages” section.

Validated by:
field covered: bool | None = False

A flag to decide whether to include not existing attribute in notifications. It can be useful for those notification endpoints that are not flexible enough for a variable set of attributes and needs always the same set of incoming attributes in every received notification https://fiware-orion.readthedocs.io/en/master/orion-api.html#covered-subscriptions

Validated by:
field exceptAttrs: List[str] | None = None

List of attributes to be excluded from the notification message, i.e. a notification message includes all entity attributes except the ones listed in this field.

Validated by:
field http: Http | None = None

It is used to convey parameters for notifications delivered through the HTTP protocol. Cannot be used together with “httpCustom, mqtt, mqttCustom”

Validated by:
field httpCustom: HttpCustom | None = None

It is used to convey parameters for notifications delivered through the HTTP protocol. Cannot be used together with “http”

Validated by:
field metadata: Any | None = None

List of metadata to be included in notification messages. See “Filtering out attributes and metadata” section for more detail.

Validated by:
field mqtt: Mqtt | None = None

It is used to convey parameters for notifications delivered through the MQTT protocol. Cannot be used together with “http, httpCustom, mqttCustom”

Validated by:
field mqttCustom: MqttCustom | None = None

It is used to convey parameters for notifications delivered through the MQTT protocol. Cannot be used together with “http, httpCustom, mqtt”

Validated by:
field onlyChangedAttrs: bool | None = False

Only supported by Orion Context Broker!If set to true then notifications associated to the subscription include only attributes that changed in the triggering update request, in combination with the attrs or exceptAttrs field. For instance, if attrs is [A=1, B=2, C=3] and A=0 is updated. In case onlyChangedAttrs=false, CB notifies [A=0, B=2, C=3].In case onlyChangedAttrs=true, CB notifies [A=0, B=null, C=null]. This

Validated by:
field timesSent: Any | None = None

Not editable, only present in GET operations. Number of notifications sent due to this subscription.

Validated by:
validator validate_attr  »  all fields[source]
validator validate_covered_attrs  »  all fields[source]
validator validate_endpoints  »  all fields[source]
validator validate_http  »  all fields[source]
pydantic model filip.models.ngsi_v2.subscriptions.Response[source]

Bases: Notification

Server response model for notifications

Config:

  • validate_assignment: bool = True

Fields:
Validators:

field attrs: List[str] | None = None

List of attributes to be included in notification messages. It also defines the order in which attributes must appear in notifications when attrsFormat value is used (see “Notification Messages” section). An empty list means that all attributes are to be included in notifications. See “Filtering out attributes and metadata” section for more detail.

Validated by:
field attrsFormat: AttrsFormat | None = AttrsFormat.NORMALIZED

specifies how the entities are represented in notifications. Accepted values are normalized (default), keyValues or values. If attrsFormat takes any value different than those, an error is raised. See detail in “Notification Messages” section.

Validated by:
field covered: bool | None = False

A flag to decide whether to include not existing attribute in notifications. It can be useful for those notification endpoints that are not flexible enough for a variable set of attributes and needs always the same set of incoming attributes in every received notification https://fiware-orion.readthedocs.io/en/master/orion-api.html#covered-subscriptions

Validated by:
field exceptAttrs: List[str] | None = None

List of attributes to be excluded from the notification message, i.e. a notification message includes all entity attributes except the ones listed in this field.

Validated by:
field http: Http | None = None

It is used to convey parameters for notifications delivered through the HTTP protocol. Cannot be used together with “httpCustom, mqtt, mqttCustom”

Validated by:
field httpCustom: HttpCustom | None = None

It is used to convey parameters for notifications delivered through the HTTP protocol. Cannot be used together with “http”

Validated by:
field lastFailure: datetime | None = None

(not editable, only present in GET operations): Last failure timestamp in ISO8601 format. Not present if subscription has never had a problem with notifications.

Validated by:
field lastNotification: datetime [Required]

(not editable, only present in GET operations): Last notification timestamp in ISO8601 format.

Validated by:
field lastSuccess: datetime | None = None

(not editable, only present in GET operations): Timestamp in ISO8601 format for last successful notification. Not present if subscription has never had a successful notification.

Validated by:
field metadata: Any | None = None

List of metadata to be included in notification messages. See “Filtering out attributes and metadata” section for more detail.

Validated by:
field mqtt: Mqtt | None = None

It is used to convey parameters for notifications delivered through the MQTT protocol. Cannot be used together with “http, httpCustom, mqttCustom”

Validated by:
field mqttCustom: MqttCustom | None = None

It is used to convey parameters for notifications delivered through the MQTT protocol. Cannot be used together with “http, httpCustom, mqtt”

Validated by:
field onlyChangedAttrs: bool | None = False

Only supported by Orion Context Broker!If set to true then notifications associated to the subscription include only attributes that changed in the triggering update request, in combination with the attrs or exceptAttrs field. For instance, if attrs is [A=1, B=2, C=3] and A=0 is updated. In case onlyChangedAttrs=false, CB notifies [A=0, B=2, C=3].In case onlyChangedAttrs=true, CB notifies [A=0, B=null, C=null]. This

Validated by:
field timesSent: int [Required]

(not editable, only present in GET operations): Number of notifications sent due to this subscription.

Validated by:
pydantic model filip.models.ngsi_v2.subscriptions.Subject[source]

Bases: BaseModel

Model for subscription subject

Fields:
field condition: Condition | None = None
field entities: List[EntityPattern] [Required]

A list of objects, each one composed of by an Entity Object:

pydantic model filip.models.ngsi_v2.subscriptions.Subscription[source]

Bases: BaseModel

Subscription payload validations https://fiware-orion.readthedocs.io/en/master/user/ngsiv2_implementation_notes/index.html#subscription-payload-validations

Config:

  • validate_assignment: bool = True

Fields:
field description: str | None = None

A free text used by the client to describe the subscription.

field expires: datetime | None = None

Subscription expiration date in ISO8601 format. Permanent subscriptions must omit this field.

field id: str | None = None

Subscription unique identifier. Automatically created at creation time.

field notification: Notification [Required]

An object that describes the notification to send when the subscription is triggered.

field status: Status | None = Status.ACTIVE

Either active (for active subscriptions) or inactive (for inactive subscriptions). If this field is not provided at subscription creation time, new subscriptions are created with the active status, which can be changed by clients afterwards. For expired subscriptions, this attribute is set to expired (no matter if the client updates it to active/inactive). Also, for subscriptions experiencing problems with notifications, the status is set to failed. As soon as the notifications start working again, the status is changed back to active.

field subject: Subject [Required]

An object that describes the subject of the subscription.

field throttling: int | None = None

Minimal period of time in seconds which must elapse between two consecutive notifications. It is optional.

Constraints:

  • strict = True

filip.models.ngsi_v2.timeseries module

Data models for interacting with FIWARE’s time series-api (aka QuantumLeap)

class filip.models.ngsi_v2.timeseries.AggrMethod(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Aggregation Methods

AVG = 'avg'
COUNT = 'count'
MAX = 'max'
MIN = 'min'
SUM = 'sum'
class filip.models.ngsi_v2.timeseries.AggrPeriod(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Aggregation Periods

DAY = 'day'
HOUR = 'hour'
MINUTE = 'minute'
MONTH = 'month'
SECOND = 'second'
YEAR = 'year'
class filip.models.ngsi_v2.timeseries.AggrScope(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Aggregation Periods When the query results cover historical data for multiple entities instances, you can define the aggregation method to be applied for each entity instance [entity] or across them [global].

ENTITY = 'entity'
GLOBAL = 'global'
pydantic model filip.models.ngsi_v2.timeseries.AttributeValues[source]

Bases: IndexedValues

Model for indexed values that contain attribute name

Fields:
field attrName: str [Required]
field values: List[Any] = None

Array of values of the selected attribute, in the same corresponding order of the ‘index’ array. When using aggregation options, the format of this remains the same, only the semantics will change. For example, if aggrPeriod is day, each value of course may not correspond to original measurements but rather the aggregate of measurements in each day.

pydantic model filip.models.ngsi_v2.timeseries.IndexedValues[source]

Bases: BaseModel

Model for time indexed values

Fields:
field values: List[Any] = None

Array of values of the selected attribute, in the same corresponding order of the ‘index’ array. When using aggregation options, the format of this remains the same, only the semantics will change. For example, if aggrPeriod is day, each value of course may not correspond to original measurements but rather the aggregate of measurements in each day.

pydantic model filip.models.ngsi_v2.timeseries.TimeSeries[source]

Bases: TimeSeriesHeader

Model for time series data

Config:

  • populate_by_name: bool = True

Fields:
field attributes: List[AttributeValues] = None
field entityId: str = None (alias 'id')

The entity id the time series api.If the id is unique among all entity types, this could be used to uniquely identify the entity instance. Otherwise, you will have to use the entityType attribute to resolve ambiguity.

field entityType: str = None (alias 'type')

The type of an entity

field index: List[datetime] | datetime = None

Array of the timestamps which are indexes of the response for the requested data. It’s a parallel array to ‘values’. The timestamp will be in the ISO8601 format (e.g. 2010-10-10T07:09:00.792) or in milliseconds since epoch whichever format was used in the input (notification), but ALWAYS in UTC. When using aggregation options, the format of this remains the same, only the semantics will change. For example, if aggrPeriod is day, each index will be a valid timestamp of a moment in the corresponding day.

extend(other: TimeSeries) → None[source]

Extends the current TimeSeries object with an other TimeSeries object. With the same format.

Parameters:

other – TimeSeries Object that will be added to the original object

Returns:

None

Raises:

Assertion Error – if header fields do not fit or if index is not rising

to_pandas() → DataFrame[source]

Converts time series data to pandas dataframe :returns: pandas.DataFrame

pydantic model filip.models.ngsi_v2.timeseries.TimeSeriesBase[source]

Bases: BaseModel

Base model for other time series api models

Fields:
field index: List[datetime] | datetime = None

Array of the timestamps which are indexes of the response for the requested data. It’s a parallel array to ‘values’. The timestamp will be in the ISO8601 format (e.g. 2010-10-10T07:09:00.792) or in milliseconds since epoch whichever format was used in the input (notification), but ALWAYS in UTC. When using aggregation options, the format of this remains the same, only the semantics will change. For example, if aggrPeriod is day, each index will be a valid timestamp of a moment in the corresponding day.

pydantic model filip.models.ngsi_v2.timeseries.TimeSeriesHeader[source]

Bases: TimeSeriesBase

Model to describe an available entity in the time series api

Config:

  • populate_by_name: bool = True

Fields:
field entityId: str = None (alias 'id')

The entity id the time series api.If the id is unique among all entity types, this could be used to uniquely identify the entity instance. Otherwise, you will have to use the entityType attribute to resolve ambiguity.

field entityType: str = None (alias 'type')

The type of an entity

field index: List[datetime] | datetime = None

Array of the timestamps which are indexes of the response for the requested data. It’s a parallel array to ‘values’. The timestamp will be in the ISO8601 format (e.g. 2010-10-10T07:09:00.792) or in milliseconds since epoch whichever format was used in the input (notification), but ALWAYS in UTC. When using aggregation options, the format of this remains the same, only the semantics will change. For example, if aggrPeriod is day, each index will be a valid timestamp of a moment in the corresponding day.

filip.models.ngsi_v2.units module

Implementation of UN/CEFACT units

We creating the data set of UNECE units from here. “https://github.com/datasets/unece-units-of-measure” It downloads the data and stores it in external resources if not already present. For additional information on UNECE an the current state of tables visit this website: https://unece.org/trade/cefact/UNLOCODE-Download https://unece.org/trade/uncefact/cl-recommendations

pydantic model filip.models.ngsi_v2.units.Unit[source]

Bases: BaseModel

Model for a unit definition

Config:

  • extra: str = ignore

  • populate_by_name: bool = True

Fields:
Validators:
field code: str | UnitCode | None = None (alias 'unitCode')

The unit of measurement given using the UN/CEFACT Common Code (3 characters)

Validated by:
field conversion_factor: str | None = None (alias 'unitConversionFactor')

The value used to convert units to the equivalent SI unit when applicable.

Validated by:
field description: str | None = None (alias 'unitDescription')

Verbose description of unit

Constraints:

  • max_length = 350

Validated by:
field name: str | UnitText | None = None (alias 'unitText')

A string or text indicating the unit of measurement

Validated by:
field symbol: str | None = None (alias 'unitSymbol')

The symbol used to represent the unit of measure as in ISO 31 / 80000.

Validated by:
validator check_consistency  »  all fields[source]

Validate and auto complete unit data based on the UN/CEFACT data :param values: Values of a all data fields :type values: dict

Returns:

Validated data

Return type:

values (dict)

model_post_init(__context: Any) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

  • self – The BaseModel instance.

  • __context – The context.

pydantic model filip.models.ngsi_v2.units.UnitCode[source]

Bases: BaseModel

The unit of measurement given using the UN/CEFACT Common Code (3 characters) or a URL. Other codes than the UN/CEFACT Common Code may be used with a prefix followed by a colon. https://schema.org/unitCode

Note

Currently we only support the UN/CEFACT Common Codes

Fields:
Validators:
field type: DataType = DataType.TEXT

Data type

field value: str [Required]

UN/CEFACT Common Code (3 characters)

Constraints:

  • min_length = 2

  • max_length = 3

Validated by:
validator validate_code  »  value[source]
pydantic model filip.models.ngsi_v2.units.UnitText[source]

Bases: BaseModel

A string or text indicating the unit of measurement. Useful if you cannot provide a standard unit code for unitCode. https://schema.org/unitText

Note

We use the names of units of measurements from UN/CEFACT for validation

Fields:
Validators:
field type: DataType = DataType.TEXT

Data type

field value: str [Required]

Verbose name of a unit using British spelling in singular form, e.g. ‘newton second per metre’

Validated by:
validator validate_text  »  value[source]
class filip.models.ngsi_v2.units.Units[source]

Bases: object

Class for easy accessing the data set of UNECE units from here. “https://github.com/datasets/unece-units-of-measure”

property codes: List[str]

Returns list of all unit codes

Returns:

List[str] containing the codes

get(item: str, default: Any | None = None)[source]

Get unit by name or by code

Parameters:

  • item (str) – name or code of unit

  • default (Any) – Default value to return if unit does not exist.

Returns:

Unit

classmethod keys(by_code: bool = False) → List[str][source]

Returns list of all unit names or codes

Parameters:

by_code (bool) – if ‘True’ the keys will contain the unit codes instead of their names.

Returns:

List[str] containing the names or list

property names: List[str]

Returns list of all unit names

Returns:

List[str] containing the names or list

property quantities

Get list of units ordered by measured quantities :returns: list of units ordered by measured quantities

units = Status CommonCode  ... Symbol ConversionFactor 3       nan         10  ...    nan              nan 4       nan         11  ...    nan              nan 5       nan         13  ...    nan              nan 6       nan         14  ...    nan              nan 7       nan         15  ...    nan              nan ...     ...        ...  ...    ...              ... 2103    nan        YDQ  ...    yd³     0,764 555 m³ 2105    nan        YRD  ...     yd        0,914 4 m 2108    nan        Z11  ...    nan              nan 2115    nan         ZP  ...    nan              nan 2116    nan         ZZ  ...    nan              nan  [1737 rows x 7 columns]
values() → List[Unit][source]

Get list of all units

Returns:

List[Unit] containing all units

filip.models.ngsi_v2.units.load_units() → DataFrame[source]

Loads data package from public repo if not already downloaded. This function will be cached for fast accessing the data set. :returns: Cleaned dataset containing all unit data

filip.models.ngsi_v2.units.validate_unit_data(data: Dict) → Dict[source]

Validator for unit objects :param data: Dictionary containing the metadata of an object :type data: Dict

Returns:

Validated dictionary of metadata