ahvn.ukf.ukf_utils module¶

ahvn.ukf.ukf_utils.valid_tag(tag)[source]¶

Parameters:: tag (str)

ahvn.ukf.ukf_utils.tag_s(tag)[source]¶

Return the slot (key) from a tag string.

A tag is expected to be in the format "[slot:value]". This helper extracts and returns the slot portion.

Parameters:: tag (str) – Tag in the format "[slot:value]".
Returns:: The slot part (text before the first ":").
Return type:: str

ahvn.ukf.ukf_utils.tag_v(tag)[source]¶

Return the value part from a tag string.

Parameters:: tag (str) – Tag in the format "[slot:value]".
Returns:: The value part (text after the first ":").
Return type:: str

ahvn.ukf.ukf_utils.tag_t(tag)[source]¶

Split a tag string into (slot, value).

Parameters:: tag (str) – Tag in the format "[slot:value]".
Returns:: A sequence of two strings: [slot, value].
Return type:: List[str]

ahvn.ukf.ukf_utils.ptags(**kwargs)[source]¶

Create formatted tag strings from keyword arguments.

Values may be scalars or iterables; iterables are expanded into multiple tags; None values are skipped.

Parameters:: **kwargs – Keys will be used as tag slots, values provide the tag values. Example: TYPE=['doc','text'], LANG='en'.
Returns:: A set of tag strings in the format "[SLOT:value]".
Return type:: Set[str]

ahvn.ukf.ukf_utils.gtags(tags, **kwargs)[source]¶

Group tags by slot name and collect values.

This converts a flat list/set of tag strings into a mapping from slot to set of values. Additional tags can be provided via the same keyword interface accepted by ptags().

Parameters:

tags (Iterable[str]) – Iterable of tag strings like "[slot:value]".
**kwargs – Extra tags passed to ptags().

Returns:

Mapping from lowercase slot name to a set of values.

Return type:

Dict[str, Set[str]]

ahvn.ukf.ukf_utils.has_tag(tags, slot, operator='ANY_OF', value=None)[source]¶

Check whether a collection of tags satisfies a condition for a slot.

The function supports a variety of operators to express membership and set-based conditions. See the implementation for the full list of supported operators; common ones include ANY_OF, ALL_OF, and unary tests like HAS_NONE.

Parameters:

tags (Iterable[str]) – Iterable of tag strings, e.g. "[type:doc]".
slot (str) – Slot name to check (the left-hand part of a tag).
operator (TagOperator) – Operator describing the condition. Can be a textual operator (see module-level TagOperator) or a numeric requirement (int or float are treated specially).
value (Optional[Union[Iterable, str, Any]]) – Value(s) to compare against. Required for non-unary operators.

Operators:: “EXACT” or “==”: Slot values exactly match the provided values (sets equal). “NONE_OF”: No slot values match the provided values. “ANY_OF”: At least one slot value matches the provided values. “ANY_IF_EXISTS”: If the slot exists, at least one provided value matches; if slot missing, returns True. “ONE_OF”: Exactly one slot value matches the provided values. “MANY_OF”: At least two slot values match the provided values. “ALL_OF”: All provided values are present in the slot values. “ALL_IN” or “IN”: All slot values are included in the provided values. “HAS_NONE”: Unary — slot has no values. “HAS_ANY”: Unary — slot has at least one value. “HAS_ONE”: Unary — slot has exactly one value. “HAS_MANY”: Unary — slot has at least two values. int: Numeric operator meaning “at least N matching values”. float: Jaccard similarity threshold (intersection/union >= threshold).

Returns:

True when the condition holds for the provided tags, otherwise False.

Return type:

bool

Raises:

ValueError – If an unary operator is given a non-None value or when an unsupported operator is provided.

Parameters:

tags (Iterable[str])
slot (str)
operator (Literal['EXACT', 'NONE_OF', 'ANY_OF', 'ANY_IF_EXISTS', 'ONE_OF', 'MANY_OF', 'ALL_OF', 'ALL_IN', 'HAS_NONE', 'HAS_ANY', 'HAS_ONE', 'HAS_MANY'] | int | float)
value (Iterable | str | Any | None)

ahvn.ukf.ukf_utils.has_related(related, subject_id=None, relation=None, object_id=None, relation_id=None, related_to_id=None)[source]¶

Return True when the given related tuples contain a matching relation.

Each relation tuple is expected to be in the form (subject_id, relation, object_id, relation_id?, relation_resources?).

Parameters:

related (Iterable[Tuple[int, str, int, Optional[int], Optional[Dict]]]) – Iterable of relation tuples to search.
subject_id (Optional[Union[int, Iterable[int]]]) – Filter for subject id(s).
relation (Optional[Union[str, Iterable[str]]]) – Filter for relation name(s).
object_id (Optional[Union[int, Iterable[int]]]) – Filter for object id(s).
relation_id (Optional[Union[int, Iterable[int]]]) – Filter for relation id(s).
related_to_id (Optional[Union[int, Iterable[int]]]) – If provided, the function matches relations where either the subject or object id is in this set.

Returns:

True if at least one relation satisfies all provided filters.

Return type:

bool

ahvn.ukf.ukf_utils.next_ver(version)[source]¶

Return the next version string by incrementing the last numeric part.

If the last component of version is numeric it will be incremented by one. Otherwise a new numeric component "1" will be appended.

Parameters:

version (str) – Current version string (for example "v1.2.3" or "v1.2.beta").

Returns:

New version string with the final numeric component incremented or: appended.

Return type:

str

Examples

>>> next_ver('v1.2.3')
'v1.2.4'
>>> next_ver('v1.2.beta')
'v1.2.beta.1'