concrete.util.metadata module

exception concrete.util.metadata.MultipleAnnotationsError(*args, **kwargs)

Bases: Exception

Exception representing more than one annotations present in a concrete object when one (or zero) is expected.

exception concrete.util.metadata.ZeroAnnotationsError(*args, **kwargs)

Bases: Exception

Exception representing zero annotations present in a concrete object when one (or more) is expected.

concrete.util.metadata.datetime_to_timestamp(dt)

Given time-zone–unaware datetime object representing date and time in UTC, return corresponding Concrete timestamp.

Parameters:dt (datetime) – time-zone–unaware datetime object representing date and time (in UTC) to convert
Returns:concrete timestamp representing datetime dt

Source: http://stackoverflow.com/questions/6999726/how-can-i-convert-a-datetime-object-to-milliseconds-since-epoch-unix-time-in-p

concrete.util.metadata.filter_annotations(annotations, filter_fields=None, sort_field=None, sort_reverse=False, action_if_multiple='pass', action_if_zero='pass')

Return filtered and/or re-ordered list of annotations, that is, objects containing a metadata field of type AnnotationMetadata. The default behavior is to do no filtering (or re-ordering), returning an exact copy of annotations.

Parameters:
  • annotations (list) – original list of annotations (objects containing a metadata field of type metadata.ttypes.AnnotationMetadata). This list is not modified.
  • filter_fields (dict) – dict of fields and their desired values by which to filter annotations (keep annotations whose field FIELD equals VALUE for all FIELD: VALUE) entries). Default: keep all annotations. See get_annotation_field() for valid fields.
  • sort_field (str) – field by which to re-order annotations. Default: do not re-order annotations.
  • sort_reverse (bool) – True to reverse order of annotations (after sorting, if any).
  • action_if_multiple (str) – action to take if, after filtering, there is more than one annotation left. ‘pass’ to return all filtered and re-ordered annotations, ‘raise’ to raise an exception of type MultipleAnnotationsError, ‘first’ to return a list containing the first annotation after filtering and re-ordering, or ‘last’ to return a list containing the last annotation after filtering and re-ordering.
  • action_if_zero (str) – action to take if, after filtering, there are no annotations left. ‘pass’ to return an empty list, ‘raise’ to raise an exception of type ZeroAnnotationsError.
Returns:

filtered and/or re-ordered list of annotations
Raises:
  • ValueError – if the value of action_if_multiple or action_if_zero is not recognized
  • MultipleAnnotationsError – if the value of action_if_multiple is ‘raise’ and there are multiple annotations passing the filter
  • ZeroAnnotationsError – if the value of action_if_zero is ‘raise’ and there are no annotations passing the filter
concrete.util.metadata.filter_annotations_json(annotations, kwargs_json)

Call filter_annotations() on annotations, sending it keyword arguments from the JSON-encoded dictionary kwargs_json.

Parameters:
  • annotations (list) – original list of annotations (objects containing a metadata field of type metadata.ttypes.AnnotationMetadata). This list is not modified.
  • kwargs_json (str) – JSON-encoded dictionary of keyword arguments to be passed to filter_annotations().
Returns:

annotations filtered by filter_annotations() according to provided JSON-encoded keyword arguments.
Raises:
  • ValueError – if the value of ‘action_if_multiple’ or ‘action_if_zero’ is not recognized
  • MultipleAnnotationsError – if the value of ‘action_if_multiple’ is ‘raise’ and there are multiple annotations passing the filter
  • ZeroAnnotationsError – if the value of ‘action_if_zero’ is ‘raise’ and there are no annotations passing the filter
concrete.util.metadata.filter_unnone(annotation_filter)

If annotation_filter is None, return no-op filter.

Parameters:annotation_filter (func) – function that takes a list of annotations and returns a filtered (and/or re-ordered) list of annotations
Returns:function that takes a list of annotations and returns a filtered (and/or re-ordered) list of annotations.
concrete.util.metadata.get_annotation_field(annotation, field)

Return requested field of annotation metadata.

Parameters:
  • annotation (object) – object containing a metadata field of type metadata.ttypes.AnnotationMetadata.
  • field (str) – name of metadata field: kBest, timestamp, or tool.
Returns:

value of requested field in annotation metadata.
Raises:

ValueError – on unknown field name
concrete.util.metadata.get_index_of_tool(lst_of_conc, tool)

Return the index of the object in the provided list whose tool name matches tool.

If tool is None, return the first valid index into lst_of_conc.

This returns -1 if:
  • lst_of_conc is None, or
  • lst_of_conc has no entries, or
  • no object in lst_of_conc matches tool.
Parameters:
  • lst_of_conc (list) – list of Concrete objects, each of which has a .metadata field.
  • tool (str) – A tool name to match.
concrete.util.metadata.now_timestamp()

Return timestamp representing the current time.

Returns:concrete timestamp representing the current time
concrete.util.metadata.timestamp_to_datetime(timestamp)

Given Concrete timestamp, return corresponding time-zone–unaware datetime object representing date and time in UTC.

Parameters:timestamp (int) – Concrete timestamp (integer representing seconds since the epoch in UTC) representing date and time to convert
Returns:datetime representing timestamp dt

Source: https://stackoverflow.com/questions/3694487/initialize-a-datetime-object-with-seconds-since-epoch

concrete.util.metadata.tool_to_filter(tool, explicit_filter=None)

Given tool name (deprecated way to filter annotations) or None, and an explicit annotation filter function or None, return an annotation filter function representing whichever is not None (and raise ValueError if both are not None).

Parameters:
  • tool (str) – name of tool to filter by, or None
  • explicit_filter (func) – function taking a list of annotations as input and returning a sub-list (possibly re-ordered) as output, or None
Returns:

Function taking a list of annotations as input and either applying explicit_filter to them and returning its output or filtering them by tool tool and returning that filtered list. If both tool and explicit_filter are not None, raise ValueError.
Raises:

ValueError – if both tool and explicit_filter are not None