geoips.interfaces package#
Subpackages#
- geoips.interfaces.module_based package
- Submodules
- geoips.interfaces.module_based.algorithms module
- geoips.interfaces.module_based.colormappers module
- geoips.interfaces.module_based.coverage_checkers module
- geoips.interfaces.module_based.databases module
- geoips.interfaces.module_based.filename_formatters module
- geoips.interfaces.module_based.interpolators module
- geoips.interfaces.module_based.output_checkers module
- geoips.interfaces.module_based.output_formatters module
- geoips.interfaces.module_based.procflows module
- geoips.interfaces.module_based.readers module
- geoips.interfaces.module_based.sector_adjusters module
- geoips.interfaces.module_based.sector_metadata_generators module
- geoips.interfaces.module_based.sector_spec_generators module
- geoips.interfaces.module_based.title_formatters module
- Module contents
- geoips.interfaces.yaml_based package
- Submodules
- geoips.interfaces.yaml_based.feature_annotators module
- geoips.interfaces.yaml_based.gridline_annotators module
- geoips.interfaces.yaml_based.product_defaults module
- geoips.interfaces.yaml_based.products module
- geoips.interfaces.yaml_based.sectors module
- geoips.interfaces.yaml_based.workflows module
- Module contents
Submodules#
geoips.interfaces.base module#
Base classes for interfaces, plugins, and plugin validation machinery.
- class geoips.interfaces.base.BaseInterface[source]#
Bases:
ABC
Base class for GeoIPS interfaces.
This class should not be instantiated directly. Instead, interfaces should be accessed by importing them from
geoips.interfaces
. For example:` from geoips.interfaces import algorithms `
will retrieve an instance ofAlgorithmsInterface
which will provide access to the GeoIPS algorithm plugins.- call_create_plugin_registries(yaml=False)[source]#
Run command ‘create_plugin_registries’ as a subprocess.
This should be done whenever a plugin is attempted to be loaded but fails because it isn’t an entry in the plugin registry. If the plugin still cannot be found after this function is ran, then report the issue to the user.
- Parameters:
yaml (bool (default=False)) –
Truth value as to whether or not we want to create a .yaml registry. If false, then create the default .json registry instead.
- abstract get_plugin(name, rebuild_registries=True)[source]#
Abstract function for retrieving a plugin under a certain interface.
- Parameters:
name (str or tuple(str)) –
The name of the yaml-based plugin. Either a single string or a tuple of strings for product plugins.
rebuild_registries (bool (default=True)) –
Whether or not to rebuild the registries if get_plugin fails. If set to true and get_plugin fails, rebuild the plugin registry, call then call get_plugin once more with rebuild_registries toggled off, so it only gets rebuilt once.
rbr (ReBuildRegistries) is set in geoips.filenames.base_paths with a default value of True. Users and developers can change this if desired.
- get_plugin_metadata(name)[source]#
Retrieve a plugin’s metadata.
Where the metadata of the plugin matches the plugin’s corresponding entry in the plugin registry.
- Parameters:
name (str or tuple(str)) –
The name of the plugin whose metadata we want.
- Returns:
metadata –
A dictionary of metadata for the requested plugin.
- Return type:
dict
- interface_type = None#
- name = 'BaseInterface'#
- plugin_registry = <geoips.plugin_registry.PluginRegistry object>#
- plugin_registry_module = <module 'geoips.plugin_registry' from '/opt/hostedtoolcache/Python/3.10.17/x64/lib/python3.10/site-packages/geoips/plugin_registry.py'>#
- rbr = True#
- property registered_module_based_plugins#
Return a dictionary of registered module-based plugins.
This property provides centeralized error handling for missing plugin registries.
- property registered_yaml_based_plugins#
Return a dictionary of registered yaml-based plugins.
This property provides centeralized error handling for missing plugin registries.
- retry_get_plugin(name, rebuild_registries, err_str, err_type=<class 'geoips.errors.PluginError'>)[source]#
Re-run self.get_plugin, but call ‘create_plugin_registries’ beforehand.
By running ‘create_plugin_registries’, we automate the registration of plugins in GeoIPS. If the plugin persists not to be found, then we’ll raise an appropriate PluginError as denoted by ‘err_str’.
- Parameters:
name (str or tuple(str)) –
The name of the yaml plugin. Either a single string or a tuple of strings for product plugins.
rebuild_registries (bool) –
Whether or not to rebuild the registries if get_plugin fails. If set to true and get_plugin fails, rebuild the plugin registry, call then call get_plugin once more with rebuild_registries toggled off, so it only gets rebuilt once.
err_str (string) –
The error to be reported.
err_type (Exception-based Class) –
The class of exception to be raised.
- class geoips.interfaces.base.BaseModuleInterface[source]#
Bases:
BaseInterface
Base Class for GeoIPS Interfaces.
This class should not be instantiated directly. Instead, interfaces should be accessed by importing them from
geoips.interfaces
. For example:` from geoips.interfaces import algorithms `
will retrieve an instance ofAlgorithmsInterface
which will provide access to the GeoIPS algorithm plugins.- get_plugin(name, rebuild_registries=None)[source]#
Retrieve a plugin from this interface by name.
- Parameters:
name (str) –
The name the desired plugin.
rebuild_registries (bool (default=None)) –
Whether or not to rebuild the registries if get_plugin fails. If set to None, default to what we have set in geoips.filenames.base_paths, which defaults to True. If specified, use the input value of rebuild_registries, which should be a boolean value. If rebuild registries is true and get_plugin fails, rebuild the plugin registry, call then call get_plugin once more with rebuild_registries toggled off, so it only gets rebuilt once.
- Returns:
An object of type
<interface>Plugin
where<interface>
is the name ofthis interface.
- Raises:
PluginError – If the specified plugin isn’t found within the interface.
- interface_type = 'module_based'#
- name = 'BaseModuleInterface'#
- plugin_is_valid(name)[source]#
Check that an interface is valid.
Check that the requested interface function has the correct call signature. Return values should be as specified below, but are not programmatically verified.
- Parameters:
name (str) – Name of the interface to be validated
- Returns:
True if valid, False if invalid
- Return type:
bool
- plugins_all_valid()[source]#
Test the current interface by validating every Plugin.
- Return type:
True if all plugins are valid, False if any plugin is invalid.
- required_args = {}#
- test_interface()[source]#
Test the current interface by validating each Plugin and testing each method.
Test this interface by opening every Plugin available to the interface, and validating each plugin by calling plugin_is_valid for each. Additionally, ensure all methods of this interface work as expected:
get_plugins
get_plugin
plugin_is_valid
plugins_all_valid
- Returns:
A dictionary containing three keys
’by_family’, ‘validity_check’, ‘func’, and ‘family’. The value for each
of these keys is a dictionary whose keys are the names of the Plugins.
- ‘by_family’ contains a dictionary of plugin names sorted by family.
- ‘validity_check’ contains a dict whose keys are plugin names and whose – values are bools where True indicates that the Plugin’s function is valid according to plugin_is_valid.
- ‘func’ contains a dict whose keys are plugin names and whose values are – the function for each Plugin.
- ‘family’ contains a dict whose keys are plugin names and whose vlaues – are the contents of the ‘family’ attribute for each Plugin.
- class geoips.interfaces.base.BaseYamlInterface[source]#
Bases:
BaseInterface
Base class for GeoIPS yaml-based plugin interfaces.
This class should not be instantiated directly. Instead, interfaces should be accessed by importing them from
geoips.interfaces
. For example:` from geoips.interfaces import products `
will retrieve an instance ofProductsInterface
which will provide access to the GeoIPS products plugins.- get_plugin(name, rebuild_registries=None)[source]#
Get a plugin by its name.
This default method can be overridden to provide different search functionality for an interface. An example of this is in the ProductsInterface which uses a tuple containing ‘source_name’ and ‘name’.
- Parameters:
name (str or tuple(str)) –
The name of the yaml-based plugin. Either a single string or a tuple of strings for product plugins.
rebuild_registries (bool (default=None)) –
Whether or not to rebuild the registries if get_plugin fails. If set to None, default to what we have set in geoips.filenames.base_paths, which defaults to True. If specified, use the input value of rebuild_registries, which should be a boolean value. If rebuild registries is true and get_plugin fails, rebuild the plugin registry, call then call get_plugin once more with rebuild_registries toggled off, so it only gets rebuilt once.
- interface_type = 'yaml_based'#
- name = 'BaseYamlInterface'#
- validator = <geoips.interfaces.base.YamlPluginValidator object>#
- class geoips.interfaces.base.BaseYamlPlugin(*args, **kwargs)[source]#
Bases:
dict
Base class for GeoIPS plugins.
- class geoips.interfaces.base.YamlPluginValidator[source]#
Bases:
object
PluginValidator class.
- property schemas#
Return a list of jsonschema schemas for GeoIPS.
This performs a lazy-load for the schema to avoid loading them if not needed. This reduces the import time for geoips.interfaces.
- validate(plugin, validator_id=None)[source]#
Validate a YAML plugin against the relevant schema.
The relevant schema is determined based on the interface and family of the plugin.
- validate_list(plugin)[source]#
Validate a list of YAML plugins.
Some interfaces allow a ‘list’ family. These list plugins will contain a property that is the same as the interface’s name. Under that is a list of individual plugins.
This function will add the interface property to each plugin in the list, then validate each plugin.
- property validators#
Return schema validators.
This performs a lazy-load for the validators to avoid loading them if not needed. This reduces the import time for geoips.interfaces.
- geoips.interfaces.base.extend_with_default(validator_class)[source]#
Extend a jsonschema validator to make it respect default values.
Note: This does not pollute the input validator object. Calling jsonschema.validators.extend returns a new object.
This will cause the validator to fill in fields that have default values. In cases where fields with default values are contained inside a mapping, that mapping must have default: {} and may not have requires.
- geoips.interfaces.base.get_validators(schema_dict, validator_class)[source]#
Create validators for each schema in schema_dict.
- Parameters:
schema_dict (dict) – A dictionary whose keys are schema $id and whose values are the full schema.
- Returns:
A dictionary whose keys are schema $id and whose values are jsonschema validator instances.
- Return type:
dict
Module contents#
GeoIPS interface module.