Skip to content

Metadata

arkindex_worker.worker.metadata

ElementsWorker methods for metadata.

Attributes

Classes

MetaType

Bases: Enum

Type of a metadata.

Attributes
Text class-attribute instance-attribute
Text = 'text'

A regular string with no special interpretation.

HTML class-attribute instance-attribute
HTML = 'html'

A metadata with a string value that should be interpreted as HTML content. The allowed HTML tags are restricted for security reasons.

Date class-attribute instance-attribute
Date = 'date'

A metadata with a string value that should be interpreted as a date. The date should be formatted as an ISO 8601 date (YYYY-MM-DD).

Location class-attribute instance-attribute
Location = 'location'

A metadata with a string value that should be interpreted as a location.

Reference class-attribute instance-attribute
Reference = 'reference'

A metadata with a string value that should be interpreted as an external identifier to this element, for example to preserve a link to the original data before it was imported into Arkindex.

Numeric class-attribute instance-attribute
Numeric = 'numeric'

A metadata with a floating point value.

URL class-attribute instance-attribute
URL = 'url'

A metadata with a string value that should be interpreted as a URL. Only the http and https schemes are allowed.

MetaDataMixin

Functions
create_metadata
create_metadata(
    element: Element | CachedElement,
    type: MetaType,
    name: str,
    value: str,
    entity: str | None = None,
) -> str

Create a metadata on the given element through API.

Parameters:

Name Type Description Default
element Element | CachedElement

The element to create a metadata on.

required
type MetaType

Type of the metadata.

required
name str

Name of the metadata.

required
value str

Value of the metadata.

required
entity str | None

UUID of an entity this metadata is related to.

None

Returns:

Type Description
str

UUID of the created metadata.

Source code in arkindex_worker/worker/metadata.py
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
@unsupported_cache
def create_metadata(
    self,
    element: Element | CachedElement,
    type: MetaType,
    name: str,
    value: str,
    entity: str | None = None,
) -> str:
    """
    Create a metadata on the given element through API.

    :param element: The element to create a metadata on.
    :param type: Type of the metadata.
    :param name: Name of the metadata.
    :param value: Value of the metadata.
    :param entity: UUID of an entity this metadata is related to.
    :returns: UUID of the created metadata.
    """
    assert element and isinstance(
        element, Element | CachedElement
    ), "element shouldn't be null and should be of type Element or CachedElement"
    assert type and isinstance(
        type, MetaType
    ), "type shouldn't be null and should be of type MetaType"
    assert name and isinstance(
        name, str
    ), "name shouldn't be null and should be of type str"
    assert value and isinstance(
        value, str
    ), "value shouldn't be null and should be of type str"
    if entity:
        assert isinstance(entity, str), "entity should be of type str"
    if self.is_read_only:
        logger.warning("Cannot create metadata as this worker is in read-only mode")
        return

    metadata = self.api_client.request(
        "CreateMetaData",
        id=element.id,
        body={
            "type": type.value,
            "name": name,
            "value": value,
            "entity_id": entity,
            "worker_run_id": self.worker_run_id,
        },
    )

    return metadata["id"]
create_metadata_bulk
create_metadata_bulk(
    element: Element | CachedElement,
    metadata_list: list[
        dict[str, MetaType | str | int | float | None]
    ],
    batch_size: int = DEFAULT_BATCH_SIZE,
) -> list[dict[str, str]]

Create multiple metadata on an existing element. This method does not support cache.

Parameters:

Name Type Description Default
element Element | CachedElement

The element to create multiple metadata on.

required
metadata_list list[dict[str, MetaType | str | int | float | None]]

The list of dict whose keys are the following: - type: MetaType - name: str - value: str | int | float - entity_id: str | None

required
batch_size int

The size of each batch, which will be used to split the publication to avoid API errors.

DEFAULT_BATCH_SIZE

Returns:

Type Description
list[dict[str, str]]

A list of dicts as returned in the metadata_list field by the CreateMetaDataBulk API endpoint.

Source code in arkindex_worker/worker/metadata.py
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
@unsupported_cache
@batch_publication
def create_metadata_bulk(
    self,
    element: Element | CachedElement,
    metadata_list: list[dict[str, MetaType | str | int | float | None]],
    batch_size: int = DEFAULT_BATCH_SIZE,
) -> list[dict[str, str]]:
    """
    Create multiple metadata on an existing element.
    This method does not support cache.

    :param element: The element to create multiple metadata on.
    :param metadata_list: The list of dict whose keys are the following:
        - type: MetaType
        - name: str
        - value: str | int | float
        - entity_id: str | None
    :param batch_size: The size of each batch, which will be used to split the publication to avoid API errors.

    :returns: A list of dicts as returned in the ``metadata_list`` field by the ``CreateMetaDataBulk`` API endpoint.
    """
    assert element and isinstance(
        element, Element | CachedElement
    ), "element shouldn't be null and should be of type Element or CachedElement"

    assert metadata_list and isinstance(
        metadata_list, list
    ), "metadata_list shouldn't be null and should be of type list of dict"

    # Make a copy to avoid modifying the metadata_list argument
    metas = []
    for index, metadata in enumerate(metadata_list):
        assert isinstance(
            metadata, dict
        ), f"Element at index {index} in metadata_list: Should be of type dict"

        assert metadata.get("type") and isinstance(
            metadata.get("type"), MetaType
        ), "type shouldn't be null and should be of type MetaType"

        assert metadata.get("name") and isinstance(
            metadata.get("name"), str
        ), "name shouldn't be null and should be of type str"

        assert metadata.get("value") is not None and isinstance(
            metadata.get("value"), str | float | int
        ), "value shouldn't be null and should be of type (str or float or int)"

        assert metadata.get("entity_id") is None or isinstance(
            metadata.get("entity_id"), str
        ), "entity_id should be None or a str"

        metas.append(
            {
                "type": metadata.get("type").value,
                "name": metadata.get("name"),
                "value": metadata.get("value"),
                "entity_id": metadata.get("entity_id"),
            }
        )

    if self.is_read_only:
        logger.warning("Cannot create metadata as this worker is in read-only mode")
        return

    created_metadata_list = [
        created_metadata
        for batch in make_batches(metas, "metadata", batch_size)
        for created_metadata in self.api_client.request(
            "CreateMetaDataBulk",
            id=element.id,
            body={
                "worker_run_id": self.worker_run_id,
                "metadata_list": batch,
            },
        )["metadata_list"]
    ]

    return created_metadata_list
list_element_metadata
list_element_metadata(
    element: Element | CachedElement,
    load_parents: bool | None = None,
) -> list[dict[str, str]]

List all metadata linked to an element. This method does not support cache.

Parameters:

Name Type Description Default
element Element | CachedElement

The element to list metadata on.

required
load_parents bool | None

Also include all metadata from the element’s parents in the response.

None
Source code in arkindex_worker/worker/metadata.py
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
def list_element_metadata(
    self, element: Element | CachedElement, load_parents: bool | None = None
) -> list[dict[str, str]]:
    """
    List all metadata linked to an element.
    This method does not support cache.

    :param element: The element to list metadata on.
    :param load_parents: Also include all metadata from the element's parents in the response.
    """
    assert element and isinstance(
        element, Element | CachedElement
    ), "element shouldn't be null and should be of type Element or CachedElement"

    query_params = {}
    if load_parents is not None:
        assert isinstance(load_parents, bool), "load_parents should be of type bool"
        query_params["load_parents"] = load_parents

    return self.api_client.paginate(
        "ListElementMetaData", id=element.id, **query_params
    )

Functions