Skip to content

hdx.data.vocabulary

module hdx.data.vocabulary

Vocabulary class containing all logic for creating, checking, and updating vocabularies.

Classes

  • ChainRuleError

  • Vocabulary — Vocabulary class containing all logic for creating, checking, and updating vocabularies.

class ChainRuleError()

Bases : Exception

class Vocabulary(initial_data: dict | None = None, name: str = None, tags: list | None = None, configuration: Configuration | None = None)

Bases : HDXObject

Vocabulary class containing all logic for creating, checking, and updating vocabularies.

Parameters

  • initial_data : dict | None — Initial dataset metadata dictionary. Defaults to None.

  • name : str — Name of vocabulary

  • tags : list | None — Initial list of tags. Defaults to None.

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

Methods

staticmethod Vocabulary.actions() → dict[str, str]

Dictionary of actions that can be performed on object

Returns

  • dict[str, str] — Dictionary of actions that can be performed on object

method Vocabulary.update_from_yaml(path: Path | str = Path('config', 'hdx_vocabulary_static.yaml')) → None

Update vocabulary metadata with static metadata from YAML file

Parameters

  • path : Path | str — Path to YAML dataset metadata. Defaults to config/hdx_vocabulary_static.yaml.

Returns

  • None — None

method Vocabulary.update_from_json(path: Path | str = Path('config', 'hdx_vocabulary_static.json')) → None

Update vocabulary metadata with static metadata from JSON file

Parameters

  • path : Path | str — Path to JSON dataset metadata. Defaults to config/hdx_vocabulary_static.json.

Returns

  • None — None

classmethod Vocabulary.read_from_hdx(identifier: str, configuration: Configuration | None = None) → Optional['Vocabulary']

Reads the vocabulary given by identifier from HDX and returns Vocabulary object

Parameters

  • identifier : str — Identifier of vocabulary

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

Returns

  • Optional['Vocabulary'] — Vocabulary object if successful read, None if not

staticmethod Vocabulary.get_all_vocabularies(configuration: Configuration | None = None) → list['Vocabulary']

Get all vocabulary names in HDX

Parameters

  • identifier — Identifier of resource

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

Returns

  • list['Vocabulary'] — List of Vocabulary objects

method Vocabulary.check_required_fields(ignore_fields: Sequence[str] = ()) → None

Check that metadata for vocabulary is complete. The parameter ignore_fields should be set if required to any fields that should be ignored for the particular operation.

Parameters

  • ignore_fields : Sequence[str] — Fields to ignore. Default is ().

Returns

  • None — None

method Vocabulary.update_in_hdx(**kwargs: Any) → None

Check if vocabulary exists in HDX and if so, update vocabulary

Returns

  • None — None

method Vocabulary.create_in_hdx(**kwargs: Any) → None

Check if vocabulary exists in HDX and if so, update it, otherwise create vocabulary

Returns

  • None — None

method Vocabulary.delete_from_hdx(empty: bool = True) → None

Deletes a vocabulary from HDX. First tags are removed then vocabulary is deleted.

Parameters

  • empty : bool — Remove all tags and update before deleting. Defaults to True.

Returns

  • None — None

method Vocabulary.get_tags() → list[str]

Lists tags in vocabulary

Returns

  • list[str] — List of tags in vocabulary

method Vocabulary.add_tag(tag: str) → bool

Add a tag

Parameters

  • tag : str — Tag to add

Returns

  • bool — True if tag added or False if tag already present

method Vocabulary.add_tags(tags: Sequence[str]) → list[str]

Add a list of tags

Parameters

  • tags : Sequence[str] — list of tags to add

Returns

  • list[str] — Tags that were successfully added

method Vocabulary.remove_tag(tag: str) → bool

Remove a tag

Parameters

  • tag : str — Tag to remove

Returns

  • bool — True if tag removed or False if not

classmethod Vocabulary.get_approved_vocabulary(configuration: Configuration | None = None) → Vocabulary

Get the HDX approved vocabulary

Parameters

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

Returns

classmethod Vocabulary.create_approved_vocabulary(url: str | None = None, configuration: Configuration | None = None) → Vocabulary

Create the HDX approved vocabulary

Parameters

  • url : str | None — Tag to check. Defaults to None (url in internal configuration).

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

Returns

classmethod Vocabulary.update_approved_vocabulary(url: str | None = None, configuration: Configuration | None = None, replace: bool = True) → Vocabulary

Update the HDX approved vocabulary

Parameters

  • url : str | None — Tag to check. Defaults to None (url in internal configuration).

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

  • replace : bool — True to replace existing tags, False to append. Defaults to True.

Returns

classmethod Vocabulary.delete_approved_vocabulary(configuration: Configuration | None = None) → None

Delete the approved vocabulary

Parameters

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

Returns

  • None — None

classmethod Vocabulary.approved_tags(configuration: Configuration | None = None) → list[str]

Return list of approved tags

Parameters

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

Returns

  • list[str] — List of approved tags

classmethod Vocabulary.is_approved(tag: str, configuration: Configuration | None = None) → bool

Return if tag is an approved one or not

Parameters

  • tag : str — Tag to check

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

Returns

  • bool — True if tag is approved, False if not

classmethod Vocabulary.read_tags_mappings(configuration: Configuration | None = None, url: str | None = None, keycolumn: int = 1, failchained: bool = True) → dict

Read tag mappings and setup tags cleanup dictionaries

Parameters

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

  • url : str | None — Url of tags cleanup spreadsheet. Defaults to None (internal configuration parameter).

  • keycolumn : int — Column number of tag column in spreadsheet. Defaults to 1.

  • failchained : bool — Fail if chained rules found. Defaults to True.

Returns

  • dict — Returns Tags dictionary

Raises

classmethod Vocabulary.set_tagsdict(tags_dict: dict) → None

Set tags dictionary

Parameters

  • tags_dict : dict — Tags dictionary

Returns

  • None — None

classmethod Vocabulary.get_mapped_tag(tag: str, log_deleted: bool = True, configuration: Configuration | None = None) → tuple[list[str], list[str]]

Given a tag, return a list of tag(s) to which it maps and any deleted tags

Parameters

  • tag : str — Tag to map

  • log_deleted : bool — Whether to log informational messages about deleted tags. Defaults to True.

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

Returns

  • tuple[list[str], list[str]] — Tuple containing list of mapped tag(s) and list of deleted tags

classmethod Vocabulary.get_mapped_tags(tags: Sequence[str], log_deleted: bool = True, configuration: Configuration | None = None) → tuple[list[str], list[str]]

Given a list of tags, return a list of tags to which they map and any deleted tags

Parameters

  • tags : Sequence[str] — List of tags to map

  • log_deleted : bool — Whether to log informational messages about deleted tags. Defaults to True.

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

Returns

  • tuple[list[str], list[str]] — Tuple containing list of mapped tags and list of deleted tags

classmethod Vocabulary.add_mapped_tag(hdxobject: HDXObject, tag: str, log_deleted: bool = True) → tuple[list[str], list[str]]

Add a tag to an HDX object that has tags

Parameters

  • hdxobject : HDXObject — HDX object such as dataset

  • tag : str — Tag to add

  • log_deleted : bool — Whether to log informational messages about deleted tags. Defaults to True.

Returns

  • tuple[list[str], list[str]] — Tuple containing list of added tags and list of deleted tags and tags not added

classmethod Vocabulary.add_mapped_tags(hdxobject: HDXObject, tags: Sequence[str], log_deleted: bool = True) → tuple[list[str], list[str]]

Add a list of tag to an HDX object that has tags

Parameters

  • hdxobject : HDXObject — HDX object such as dataset

  • tags : Sequence[str] — List of tags to add

  • log_deleted : bool — Whether to log informational messages about deleted tags. Defaults to True.

Returns

  • tuple[list[str], list[str]] — Tuple containing list of added tags and list of deleted tags and tags not added

classmethod Vocabulary.clean_tags(hdxobject: HDXObject, log_deleted: bool = True) → tuple[list[str], list[str]]

Clean tags in an HDX object according to tags cleanup spreadsheet

Parameters

  • hdxobject : HDXObject — HDX object such as dataset

  • log_deleted : bool — Whether to log informational messages about deleted tags. Defaults to True.

Returns

  • tuple[list[str], list[str]] — Tuple containing list of mapped tags and list of deleted tags and tags not added

classmethod Vocabulary.autocomplete(name: str, limit: int = 20, configuration: Configuration | None = None, **kwargs: Any) → list

Autocomplete a tag name and return matches

Parameters

  • name : str — Name to autocomplete

  • limit : int — Maximum number of matches to return

  • configuration : Configuration | None — HDX configuration. Defaults to global configuration.

  • **kwargs : Any

  • offset — The offset to start returning tags from.

Returns

  • list — Autocomplete matches