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

193
batdetect2/targets/terms.py
View File

@ -79,8 +79,10 @@ 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 ----------
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. to populate the registry with. Defaults to an empty registry.
""" """
self._terms = terms or {} self._terms = terms or {}
@ -88,12 +90,17 @@ class TermRegistry:
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 ------
KeyError
If a term with the provided key already exists in the
registry. registry.
""" """
if key in self._terms: if key in self._terms:
@ -104,14 +111,20 @@ 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 ------
KeyError
If no term with the specified key is found, with a
helpful message suggesting listing available keys. helpful message suggesting listing available keys.
""" """
try: try:
@ -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,9 +272,12 @@ 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
The value of the tag (e.g., "Myotis myotis", "Echolocation").
key : str, default="class"
The key (alias) of the term associated with this tag, as
registered in the TermRegistry. Defaults to "class", implying registered in the TermRegistry. Defaults to "class", implying
it represents a classification target label by default. it represents a classification target label by default.
""" """
@ -257,16 +295,23 @@ 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 ------
KeyError
If the term key specified in `tag_info.key` is not found
in the registry. 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)
@ -280,16 +325,22 @@ 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 ----------
key : str
The unique key (alias) that will be used to register and
reference this term. reference this term.
label: The optional display label for the term. Defaults to `key` label : str, optional
The optional display label for the term. Defaults to `key`
if not provided during registration. if not provided during registration.
name: The optional formal name for the term. Defaults to `key` name : str, optional
The optional formal name for the term. Defaults to `key`
if not provided during registration. if not provided during registration.
uri: The optional URI identifying the term (e.g., from a standard uri : str, optional
The optional URI identifying the term (e.g., from a standard
vocabulary). vocabulary).
definition: The optional textual definition of the term. Defaults to definition : str, optional
The optional textual definition of the term. Defaults to
"Unknown" if not provided during registration. "Unknown" if not provided during registration.
""" """
@ -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,24 +393,33 @@ 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
The path to the configuration file.
field : str, optional
Optional key indicating a specific section within the config
file where the 'terms' list is located. If None, expects the file where the 'terms' list is located. If None, expects the
list directly at the top level or within a structure matching list directly at the top level or within a structure matching
TermConfig schema. TermConfig schema.
term_registry: The TermRegistry instance to add the loaded terms to. term_registry : TermRegistry, optional
Defaults to the global `registry`. 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
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. already present in the registry.
""" """
data = load_config(path, schema=TermConfig, field=field) data = load_config(path, schema=TermConfig, field=field)