lionel/batdetect2
1
0
Fork 0
mirror of https://github.com/macaodha/batdetect2.git synced 2025-06-29 22:51:58 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

Modify to numpydoc style

Browse Source
This commit is contained in:
mbsantiago 2025-04-12 18:05:02 +01:00
parent b93d4c65c2
commit 26a2c5c851
1 changed files with 144 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

223
batdetect2/targets/terms.py
View File

@ -79,22 +79,29 @@ class TermRegistry:
def __init__(self, terms: Optional[Dict[str, data.Term]] = None): def __init__(self, terms: Optional[Dict[str, data.Term]] = None):
"""Initializes the TermRegistry. """Initializes the TermRegistry.
Args: Parameters
terms: An optional dictionary of initial key-to-Term mappings ----------
to populate the registry with. Defaults to an empty registry. terms : dict[str, soundevent.data.Term], optional
An optional dictionary of initial key-to-Term mappings
to populate the registry with. Defaults to an empty registry.
""" """
self._terms = terms or {} self._terms = terms or {}
def add_term(self, key: str, term: data.Term) -> None: def add_term(self, key: str, term: data.Term) -> None:
"""Adds a Term object to the registry with the specified key. """Adds a Term object to the registry with the specified key.
Args: Parameters
key: The unique string key to associate with the term. ----------
term: The soundevent.data.Term object to register. key : str
The unique string key to associate with the term.
term : soundevent.data.Term
The soundevent.data.Term object to register.
Raises: Raises
KeyError: If a term with the provided key already exists in the ------
registry. KeyError
If a term with the provided key already exists in the
registry.
""" """
if key in self._terms: if key in self._terms:
raise KeyError("A term with the provided key already exists.") raise KeyError("A term with the provided key already exists.")
@ -104,15 +111,21 @@ class TermRegistry:
def get_term(self, key: str) -> data.Term: def get_term(self, key: str) -> data.Term:
"""Retrieves a registered term by its unique key. """Retrieves a registered term by its unique key.
Args: Parameters
key: The unique string key of the term to retrieve. ----------
key : str
The unique string key of the term to retrieve.
Returns: Returns
-------
soundevent.data.Term
The corresponding soundevent.data.Term object. The corresponding soundevent.data.Term object.
Raises: Raises
KeyError: If no term with the specified key is found, with a ------
helpful message suggesting listing available keys. KeyError
If no term with the specified key is found, with a
helpful message suggesting listing available keys.
""" """
try: try:
return self._terms[key] return self._terms[key]
@ -140,18 +153,28 @@ class TermRegistry:
reasonable defaults are used (`key` for name/label, "Unknown" for reasonable defaults are used (`key` for name/label, "Unknown" for
definition). definition).
Args: Parameters
key: The unique string key for the new term. ----------
name: The name for the new term (defaults to `key`). key : str
uri: The URI for the new term (optional). The unique string key for the new term.
label: The display label for the new term (defaults to `key`). name : str, optional
definition: The definition for the new term (defaults to "Unknown"). The name for the new term (defaults to `key`).
uri : str, optional
The URI for the new term (optional).
label : str, optional
The display label for the new term (defaults to `key`).
definition : str, optional
The definition for the new term (defaults to "Unknown").
Returns: Returns
-------
soundevent.data.Term
The newly created and registered soundevent.data.Term object. The newly created and registered soundevent.data.Term object.
Raises: Raises
KeyError: If a term with the provided key already exists. ------
KeyError
If a term with the provided key already exists.
""" """
term = data.Term( term = data.Term(
name=name or key, name=name or key,
@ -165,7 +188,9 @@ class TermRegistry:
def get_keys(self) -> List[str]: def get_keys(self) -> List[str]:
"""Returns a list of all keys currently registered. """Returns a list of all keys currently registered.
Returns: Returns
-------
list[str]
A list of strings representing the keys of all registered terms. A list of strings representing the keys of all registered terms.
""" """
return list(self._terms.keys()) return list(self._terms.keys())
@ -199,16 +224,23 @@ def get_term_from_key(
Uses the global default registry unless a specific `term_registry` Uses the global default registry unless a specific `term_registry`
instance is provided. instance is provided.
Args: Parameters
key: The unique key of the term to retrieve. ----------
term_registry: The TermRegistry instance to search in. Defaults to key : str
the global `registry`. The unique key of the term to retrieve.
term_registry : TermRegistry, optional
The TermRegistry instance to search in. Defaults to the global
`registry`.
Returns: Returns
-------
soundevent.data.Term
The corresponding soundevent.data.Term object. The corresponding soundevent.data.Term object.
Raises: Raises
KeyError: If the key is not found in the specified registry. ------
KeyError
If the key is not found in the specified registry.
""" """
return term_registry.get_term(key) return term_registry.get_term(key)
@ -219,11 +251,14 @@ def get_term_keys(term_registry: TermRegistry = registry) -> List[str]:
Uses the global default registry unless a specific `term_registry` Uses the global default registry unless a specific `term_registry`
instance is provided. instance is provided.
Args: Parameters
term_registry: The TermRegistry instance to query. Defaults to ----------
the global `registry`. term_registry : TermRegistry, optional
The TermRegistry instance to query. Defaults to the global `registry`.
Returns: Returns
-------
list[str]
A list of strings representing the keys of all registered terms. A list of strings representing the keys of all registered terms.
""" """
return term_registry.get_keys() return term_registry.get_keys()
@ -237,11 +272,14 @@ class TagInfo(BaseModel):
tags with output classes. It links a tag value to a term definition tags with output classes. It links a tag value to a term definition
via the term's registry key. via the term's registry key.
Attributes: Attributes
value: The value of the tag (e.g., "Myotis myotis", "Echolocation"). ----------
key: The key (alias) of the term associated with this tag, as value : str
registered in the TermRegistry. Defaults to "class", implying The value of the tag (e.g., "Myotis myotis", "Echolocation").
it represents a classification target label by default. key : str, default="class"
The key (alias) of the term associated with this tag, as
registered in the TermRegistry. Defaults to "class", implying
it represents a classification target label by default.
""" """
value: str value: str
@ -257,17 +295,24 @@ def get_tag_from_info(
Looks up the term using the key in the provided `tag_info` from the Looks up the term using the key in the provided `tag_info` from the
specified registry and constructs a Tag object. specified registry and constructs a Tag object.
Args: Parameters
tag_info: The TagInfo object containing the value and term key. ----------
term_registry: The TermRegistry instance to use for term lookup. tag_info : TagInfo
Defaults to the global `registry`. The TagInfo object containing the value and term key.
term_registry : TermRegistry, optional
The TermRegistry instance to use for term lookup. Defaults to the
global `registry`.
Returns: Returns
-------
soundevent.data.Tag
A soundevent.data.Tag object corresponding to the input info. A soundevent.data.Tag object corresponding to the input info.
Raises: Raises
KeyError: If the term key specified in `tag_info.key` is not found ------
in the registry. KeyError
If the term key specified in `tag_info.key` is not found
in the registry.
""" """
term = get_term_from_key(tag_info.key, term_registry=term_registry) term = get_term_from_key(tag_info.key, term_registry=term_registry)
return data.Tag(term=term, value=tag_info.value) return data.Tag(term=term, value=tag_info.value)
@ -280,17 +325,23 @@ class TermInfo(BaseModel):
files (e.g., YAML) which can then be loaded into the TermRegistry. files (e.g., YAML) which can then be loaded into the TermRegistry.
It mirrors the parameters of `TermRegistry.add_custom_term`. It mirrors the parameters of `TermRegistry.add_custom_term`.
Attributes: Attributes
key: The unique key (alias) that will be used to register and ----------
reference this term. key : str
label: The optional display label for the term. Defaults to `key` The unique key (alias) that will be used to register and
if not provided during registration. reference this term.
name: The optional formal name for the term. Defaults to `key` label : str, optional
if not provided during registration. The optional display label for the term. Defaults to `key`
uri: The optional URI identifying the term (e.g., from a standard if not provided during registration.
vocabulary). name : str, optional
definition: The optional textual definition of the term. Defaults to The optional formal name for the term. Defaults to `key`
"Unknown" if not provided during registration. if not provided during registration.
uri : str, optional
The optional URI identifying the term (e.g., from a standard
vocabulary).
definition : str, optional
The optional textual definition of the term. Defaults to
"Unknown" if not provided during registration.
""" """
key: str key: str
@ -306,7 +357,16 @@ class TermConfig(BaseModel):
This model typically corresponds to a section in a configuration file This model typically corresponds to a section in a configuration file
(e.g., YAML) containing a list of term definitions to be registered. (e.g., YAML) containing a list of term definitions to be registered.
Attributes
----------
terms : list[TermInfo]
A list of TermInfo objects, each defining a term to be
registered. Defaults to an empty list.
Examples
--------
Example YAML structure: Example YAML structure:
```yaml ```yaml
terms: terms:
- key: species - key: species
@ -317,10 +377,6 @@ class TermConfig(BaseModel):
definition: Describes a specific project attribute. definition: Describes a specific project attribute.
# ... more TermInfo definitions # ... more TermInfo definitions
``` ```
Attributes:
terms: A list of TermInfo objects, each defining a term to be
registered. Defaults to an empty list.
""" """
terms: List[TermInfo] = Field(default_factory=list) terms: List[TermInfo] = Field(default_factory=list)
@ -337,25 +393,34 @@ def load_terms_from_config(
extracts the list of TermInfo definitions, and adds each one as a extracts the list of TermInfo definitions, and adds each one as a
custom term to the specified TermRegistry instance. custom term to the specified TermRegistry instance.
Args: Parameters
path: The path to the configuration file. ----------
field: Optional key indicating a specific section within the config path : data.PathLike
file where the 'terms' list is located. If None, expects the The path to the configuration file.
list directly at the top level or within a structure matching field : str, optional
TermConfig schema. Optional key indicating a specific section within the config
term_registry: The TermRegistry instance to add the loaded terms to. file where the 'terms' list is located. If None, expects the
Defaults to the global `registry`. list directly at the top level or within a structure matching
TermConfig schema.
term_registry : TermRegistry, optional
The TermRegistry instance to add the loaded terms to. Defaults to
the global `registry`.
Returns: Returns
-------
dict[str, soundevent.data.Term]
A dictionary mapping the keys of the newly added terms to their A dictionary mapping the keys of the newly added terms to their
corresponding Term objects. corresponding Term objects.
Raises: Raises
FileNotFoundError: If the config file path does not exist. ------
ValidationError: If the config file structure does not match the FileNotFoundError
TermConfig schema. If the config file path does not exist.
KeyError: If a term key loaded from the config conflicts with a key pydantic.ValidationError
already present in the registry. If the config file structure does not match the TermConfig schema.
KeyError
If a term key loaded from the config conflicts with a key
already present in the registry.
""" """
data = load_config(path, schema=TermConfig, field=field) data = load_config(path, schema=TermConfig, field=field)
return { return {