HedGroup¶

class HedGroup(hed_string='', startpos=None, endpos=None, contents=None)[source]: A single parenthesized HED string.

Methods

`HedGroup.__init__`([hed_string, startpos, ...])	Return an empty HedGroup object.
`HedGroup.append`(tag_or_group)	Add a tag or group to this group.
`HedGroup.casefold`()	Convenience function, equivalent to str(self).casefold().
`HedGroup.check_if_in_original`(tag_or_group)	Check if the tag or group in original string.
`HedGroup.copy`()	Return a deep copy of this group.
`HedGroup.find_def_tags`([recursive, ...])	Find def and def-expand tags.
`HedGroup.find_exact_tags`(exact_tags[, ...])	Find the given tags.
`HedGroup.find_placeholder_tag`()	Return a placeholder tag, if present in this group.
`HedGroup.find_tags`(search_tags[, recursive, ...])	Find the base tags and their containing groups.
`HedGroup.find_tags_with_term`(term[, ...])	Find any tags that contain the given term.
`HedGroup.find_wildcard_tags`(search_tags[, ...])	Find the tags and their containing groups.
`HedGroup.get_all_groups`([also_return_depth])	Return HedGroups, including descendants and self.
`HedGroup.get_all_tags`()	Return HedTags, including descendants.
`HedGroup.get_as_form`(tag_attribute)	Get the string corresponding to the specified form.
`HedGroup.get_as_indented`([tag_attribute])	Return the string as a multiline indented format.
`HedGroup.get_as_long`()	Return this HedGroup as a long tag string.
`HedGroup.get_as_short`()	Return this HedGroup as a short tag string.
`HedGroup.get_first_group`()	Return the first group in this HED string or group.
`HedGroup.get_original_hed_string`()	Get the original HED string.
`HedGroup.groups`()	Return the direct child groups of this group.
`HedGroup.lower`()	Convenience function, equivalent to str(self).lower().
`HedGroup.remove`(items_to_remove)	Remove any tags/groups in items_to_remove.
`HedGroup.replace`(item_to_replace, new_contents)	Replace an existing tag or group.
`HedGroup.sort`()	Sort the tags and groups in this HedString in a consistent order.
`HedGroup.sorted`()	Return a sorted copy of this HED group
`HedGroup.tags`()	Return the direct child tags of this group.

Attributes

`HedGroup.is_group`	True if this is a parenthesized group.
`HedGroup.span`	Return the source span.

HedGroup.__init__(hed_string='', startpos=None, endpos=None, contents=None)[source]¶

Return an empty HedGroup object.

Parameters:

hed_string (str or None) – Source HED string for this group.
startpos (int or None) – Starting index of group(including parentheses) in hed_string.
endpos (int or None) – Position after the end (including parentheses) in hed_string.
contents (list or None) – A list of HedTags and/or HedGroups that will be set as the contents of this group. Mostly used during definition expansion.

HedGroup.append(tag_or_group)[source]¶

Add a tag or group to this group.

Parameters:: tag_or_group (HedTag or HedGroup) – The new object to add to this group.

HedGroup.casefold()[source]¶: Convenience function, equivalent to str(self).casefold().

HedGroup.check_if_in_original(tag_or_group)[source]¶

Check if the tag or group in original string.

Parameters:: tag_or_group (HedTag or HedGroup) – The HedTag or HedGroup to be looked for in this group.
Returns:: True if in this group.
Return type:: bool

HedGroup.copy()[source]¶

Return a deep copy of this group.

Returns:: The copied group.
Return type:: HedGroup

HedGroup.find_def_tags(recursive=False, include_groups=3)[source]¶

Find def and def-expand tags.

Parameters:

recursive (bool) – If true, also check subgroups.
include_groups (int, 0, 1, 2, 3) – Options for return values. If 0: Return only def and def expand tags/. If 1: Return only def tags and def-expand groups. If 2: Return only groups containing defs, or def-expand groups. If 3 or any other value: Return all 3 as a tuple.

Returns:

A list of tuples. The contents depend on the values of the include_group.

Return type:

list

HedGroup.find_exact_tags(exact_tags, recursive=False, include_groups=1)[source]¶

Find the given tags. This will only find complete matches, any extension or value must also match.

Parameters:

exact_tags (list of HedTag) – A container of tags to locate.
recursive (bool) – If true, also check subgroups.
include_groups (bool) – 0, 1 or 2. If 0: Return only tags If 1: Return only groups If 2 or any other value: Return both

Returns:

A list of tuples. The contents depend on the values of the include_group.

Return type:

list

HedGroup.find_placeholder_tag()[source]¶

Return a placeholder tag, if present in this group.

Returns:: The placeholder tag if found.
Return type:: HedTag or None

Notes

Assumes a valid HedString with no erroneous “#” characters.

HedGroup.find_tags(search_tags, recursive=False, include_groups=2)[source]¶

Find the base tags and their containing groups. This searches by short_base_tag, ignoring any ancestors or extensions/values.

Parameters:

search_tags (container) – A container of short_base_tags to locate.
recursive (bool) – If true, also check subgroups.
include_groups (0, 1 or 2) – Specify return values. If 0: return a list of the HedTags. If 1: return a list of the HedGroups containing the HedTags. If 2: return a list of tuples (HedTag, HedGroup) for the found tags.

Returns:

The contents of the list depends on the value of include_groups.

Return type:

list

HedGroup.find_tags_with_term(term, recursive=False, include_groups=2)[source]¶

Find any tags that contain the given term.

Note: This can only find identified tags.

Parameters:

term (str) – A single term to search for.
recursive (bool) – If true, recursively check subgroups.
include_groups (0, 1 or 2) – Controls return values If 0: Return only tags. If 1: Return only groups. If 2 or any other value: Return both.

Return type:

list

HedGroup.find_wildcard_tags(search_tags, recursive=False, include_groups=2)[source]¶

Find the tags and their containing groups.

This searches tag.short_tag.casefold(), with an implicit wildcard on the end.

e.g. “Eve” will find Event, but not Sensory-event.

Parameters:

search_tags (container) – A container of the starts of short tags to search.
recursive (bool) – If True, also check subgroups.
include_groups (0, 1 or 2) – Specify return values. If 0: return a list of the HedTags. If 1: return a list of the HedGroups containing the HedTags. If 2: return a list of tuples (HedTag, HedGroup) for the found tags.

Returns:

The contents of the list depends on the value of include_groups.

Return type:

list

HedGroup.get_all_groups(also_return_depth=False)[source]¶

Return HedGroups, including descendants and self.

Parameters:: also_return_depth (bool) – If True, yield tuples (group, depth) rather than just groups.
Returns:: The list of all HedGroups in this group, including descendants and self.
Return type:: list

HedGroup.get_all_tags()[source]¶

Return HedTags, including descendants.

Returns:: A list of all the tags in this group including descendants.
Return type:: list

HedGroup.get_as_form(tag_attribute)[source]¶

Get the string corresponding to the specified form.

Parameters:: tag_attribute (str) – The hed_tag property to use to construct the string (usually short_tag or long_tag).
Returns:: The constructed string after transformation.
Return type:: str

HedGroup.get_as_indented(tag_attribute='short_tag')[source]¶

Return the string as a multiline indented format.

Parameters:: tag_attribute (str) – The hed_tag property to use to construct the string (usually short_tag or long_tag).
Returns:: The indented string.
Return type:: formatted_hed (str)

HedGroup.get_as_long()[source]¶

Return this HedGroup as a long tag string.

Returns:: The group as a string with all tags as long tags.
Return type:: str

HedGroup.get_as_short()[source]¶

Return this HedGroup as a short tag string.

Returns:: The group as a string with all tags as short tags.
Return type:: str

HedGroup.get_first_group()[source]¶

Return the first group in this HED string or group.

Useful for things like Def-expand where they only have a single group.

Raises a ValueError if there are no groups.

Returns:: The first group.
Return type:: HedGroup

HedGroup.get_original_hed_string()[source]¶

Get the original HED string.

Returns:: The original string with no modification.
Return type:: str

HedGroup.groups()[source]¶

Return the direct child groups of this group.

Returns:: All groups directly in this group, filtering out HedTag children.
Return type:: list

HedGroup.lower()[source]¶: Convenience function, equivalent to str(self).lower().

HedGroup.remove(items_to_remove: Iterable[Union[HedTag, HedGroup]])[source]¶

Remove any tags/groups in items_to_remove.

Parameters:: items_to_remove (list) – List of HedGroups and/or HedTags to remove by identity.

Notes

Any groups that become empty will also be pruned.
If you pass a child and parent group, the child will also be removed from the parent.

static HedGroup.replace(item_to_replace, new_contents)[source]¶

Replace an existing tag or group.

Note: This is a static method that relies on the parent attribute of item_to_replace.

Parameters:

item_to_replace (HedTag or HedGroup) – The item to replace must exist or this will raise an error.
new_contents (HedTag or HedGroup) – Replacement contents.

Raises:

KeyError –
- item_to_replace does not exist.
AttributeError –
- item_to_replace has no parent set.

HedGroup.sort()[source]¶: Sort the tags and groups in this HedString in a consistent order.

HedGroup.sorted()[source]¶

Return a sorted copy of this HED group

Returns:: The sorted copy.
Return type:: sorted_copy (HedGroup)

HedGroup.tags()[source]¶

Return the direct child tags of this group.

Returns:: All tags directly in this group, filtering out HedGroup children.
Return type:: list

HedGroup.is_group¶: True if this is a parenthesized group.

HedGroup.span¶

Return the source span.

Returns:: start index of the group (including parentheses) from the source string. int: end index of the group (including parentheses) from the source string.
Return type:: int