Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docstring cleanup #355

Merged
merged 2 commits into from
Nov 10, 2021
Merged

Docstring cleanup #355

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
31213ae
docs: remove versionadded and versionchanged directives from docstrin…
CGuichard Sep 9, 2021
240f0af
docs: cleanup and update of docstrings (#241)
CGuichard Oct 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
270 changes: 98 additions & 172 deletions eodag/api/core.py
View file
Open in desktop

Large diffs are not rendered by default.

40 changes: 15 additions & 25 deletions eodag/api/product/_product.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,24 +242,20 @@ def download(
feedback on the download progress
:type progress_callback: :class:`~eodag.utils.ProgressCallback` or None
:param wait: (optional) If download fails, wait time in minutes between
two download tries (default=2')
two download tries
:type wait: int
:param timeout: (optional) If download fails, maximum time in minutes
before stop retrying to download (default=20')
before stop retrying to download
:type timeout: int
:param dict kwargs: `outputs_prefix` (str), `extract` (bool) and
`dl_url_params` (dict) can be provided as additional kwargs
and will override any other values defined in a configuration
file or with environment variables.
:param kwargs: `outputs_prefix` (str), `extract` (bool) and
`dl_url_params` (dict) can be provided as additional kwargs
and will override any other values defined in a configuration
file or with environment variables.
:type kwargs: dict
:returns: The absolute path to the downloaded product on the local filesystem
:rtype: str
:raises: :class:`~eodag.utils.exceptions.PluginImplementationError`
:raises: :class:`RuntimeError`

.. versionchanged:: 2.3.0

Returns a file system path instead of a file URI ('/tmp' instead of
'file:///tmp').
"""
if self.downloader is None:
raise RuntimeError(
Expand Down Expand Up @@ -321,26 +317,20 @@ def get_quicklook(self, filename=None, base_dir=None, progress_callback=None):
"""Download the quicklook image of a given EOProduct from its provider if it
exists.

:param filename: (optional) the name to give to the downloaded quicklook. If not
given, it defaults to the product's ID (without file extension).
:param filename: (optional) The name to give to the downloaded quicklook. If not
given, it defaults to the product's ID (without file extension).
:type filename: str
:param base_dir: (optional) the absolute path of the directory where to store
the quicklooks in the filesystem. If not given, it defaults to the
`quicklooks` directory under this EO product downloader's ``outputs_prefix``
config param (e.g. '/tmp/quicklooks/')
:param base_dir: (optional) The absolute path of the directory where to store
the quicklooks in the filesystem. If not given, it defaults to the
`quicklooks` directory under this EO product downloader's ``outputs_prefix``
config param (e.g. '/tmp/quicklooks/')
:type base_dir: str
:param progress_callback: (optional) A method or a callable object which takes
a current size and a maximum size as inputs and handle progress bar creation
and update to give the user a feedback on the download progress
a current size and a maximum size as inputs and handle progress bar
creation and update to give the user a feedback on the download progress
:type progress_callback: :class:`~eodag.utils.ProgressCallback` or None
:returns: The absolute path of the downloaded quicklook
:rtype: str

.. versionchanged::
1.0

* Added the ``base_dir`` optional parameter to choose where to download
the retrieved quicklook
"""

def format_quicklook_address():
Expand Down
37 changes: 21 additions & 16 deletions eodag/api/product/metadata_mapping.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ def get_metadata_path(map_value):
`['productType', '$.properties.productType']` with the sample
above. Or the string `$.properties.id`.
:type map_value: str or list(str)
:return: Either, None and the path to the metadata value, or a list of converter
:returns: Either, None and the path to the metadata value, or a list of converter
and its args, and the path to the metadata value.
:rtype: tuple(list(str) or None, str)
"""
Expand All @@ -98,7 +98,7 @@ def get_metadata_path(map_value):


def get_metadata_path_value(map_value):
""" Get raw metadata path without converter """
"""Get raw metadata path without converter"""
return map_value[1] if isinstance(map_value, list) else map_value


Expand All @@ -108,7 +108,7 @@ def get_search_param(map_value):
:param map_value: The value originating from the definition of `metadata_mapping`
in the provider search config
:type map_value: list
:return: The value of the search parameter as defined in the provider config
:returns: The value of the search parameter as defined in the provider config
:rtype: str
"""
# Assume that caller will pass in the value as a list
Expand Down Expand Up @@ -371,18 +371,18 @@ def convert_s2msil2a_title_to_aws_productinfo(string):
def properties_from_json(json, mapping, discovery_pattern=None, discovery_path=None):
"""Extract properties from a provider json result.

:param json: the representation of a provider result as a json object
:param json: The representation of a provider result as a json object
:type json: dict
:param mapping: a mapping between :class:`~eodag.api.product._product.EOProduct`'s metadata
:param mapping: A mapping between :class:`~eodag.api.product._product.EOProduct`'s metadata
keys and the location of the values of these properties in the json
representation, expressed as a
`jsonpath <http://goessner.net/articles/JsonPath/>`_
:param discovery_pattern: regex pattern for metadata key discovery,
e.g. "^[a-zA-Z]+$"
:param discovery_pattern: (optional) Regex pattern for metadata key discovery,
e.g. "^[a-zA-Z]+$"
:type discovery_pattern: str
:param discovery_path: str representation of jsonpath
:param discovery_path: (optional) String representation of jsonpath
:type discovery_path: str
:return: the metadata of the :class:`~eodag.api.product._product.EOProduct`
:returns: The metadata of the :class:`~eodag.api.product._product.EOProduct`
:rtype: dict
"""
properties = {}
Expand Down Expand Up @@ -467,19 +467,24 @@ def properties_from_xml(
):
"""Extract properties from a provider xml result.

:param xml_as_text: the representation of a provider result as xml
:param xml_as_text: The representation of a provider result as xml
:type xml_as_text: str
:param mapping: a mapping between :class:`~eodag.api.product._product.EOProduct`'s metadata
:param mapping: A mapping between :class:`~eodag.api.product._product.EOProduct`'s metadata
keys and the location of the values of these properties in the xml
representation, expressed as a
`xpath <https://www.w3schools.com/xml/xml_xpath.asp>`_
:param empty_ns_prefix: the name to give to the default namespace of `xml_as_text`.
:param empty_ns_prefix: (optional) The name to give to the default namespace of `xml_as_text`.
This is a technical workaround for the limitation of lxml
not supporting empty namespace prefix (default: ns). The
not supporting empty namespace prefix. The
xpath in `mapping` must use this value to be able to
correctly reach empty-namespace prefixed elements
:type empty_ns_prefix: str
:return: the metadata of the :class:`~eodag.api.product._product.EOProduct`
:param discovery_pattern: (optional) Regex pattern for metadata key discovery,
e.g. "^[a-zA-Z]+$"
:type discovery_pattern: str
:param discovery_path: (optional) String representation of jsonpath
:type discovery_path: str
:returns: the metadata of the :class:`~eodag.api.product._product.EOProduct`
:rtype: dict
"""
properties = {}
Expand Down Expand Up @@ -591,9 +596,9 @@ def mtd_cfg_as_jsonpath(src_dict, dest_dict={}):

:param src_dict: Input dict containing jsonpath str as values
:type src_dict: dict
:param dest_dict: Output dict containing jsonpath objects as values
:param dest_dict: (optional) Output dict containing jsonpath objects as values
:type dest_dict: dict
:return: dest_dict
:returns: dest_dict
:rtype: dict
"""
if not dest_dict:
Expand Down
3 changes: 2 additions & 1 deletion eodag/api/search_result.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ def crunch(self, cruncher, **search_params):

:param cruncher: The plugin instance to use to work on the products
:type cruncher: subclass of :class:`~eodag.plugins.crunch.base.Crunch`
:param dict search_params: The criteria that have been used to produce this result
:param search_params: The criteria that have been used to produce this result
:type search_params: dict
:returns: The result of the application of the crunching method to the EO products
:rtype: :class:`~eodag.api.search_result.SearchResult`
"""
Expand Down
57 changes: 37 additions & 20 deletions eodag/config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,12 +83,14 @@ class ProviderConfig(yaml.YAMLObject):
:type api: :class:`~eodag.config.PluginConfig`
:param search: (optional) The configuration of a plugin of type Search
:type search: :class:`~eodag.config.PluginConfig`
:param dict products: (optional) The products types supported by the provider
:param products: (optional) The products types supported by the provider
:type products: dict
:param download: (optional) The configuration of a plugin of type Download
:type download: :class:`~eodag.config.PluginConfig`
:param auth: (optional) The configuration of a plugin of type Authentication
:type auth: :class:`~eodag.config.PluginConfig`
:param dict kwargs: Additional configuration variables for this provider
:param kwargs: Additional configuration variables for this provider
:type kwargs: dict
"""

yaml_loader = yaml.Loader
Expand Down Expand Up @@ -118,7 +120,11 @@ def from_mapping(cls, mapping):

@staticmethod
def validate(config_keys):
"""Validate a :class:`~eodag.config.ProviderConfig`"""
"""Validate a :class:`~eodag.config.ProviderConfig`

:param config_keys: The configurations keys to validate
:type config_keys: dict
"""
if "name" not in config_keys:
raise ValidationError("Provider config must have name key")
if not any(k in config_keys for k in ("api", "search", "download", "auth")):
Expand All @@ -134,7 +140,8 @@ def validate(config_keys):
def update(self, mapping):
"""Update the configuration parameters with values from `mapping`

:param dict mapping: The mapping from which to override configuration parameters
:param mapping: The mapping from which to override configuration parameters
:type mapping: dict
"""
if mapping is None:
mapping = {}
Expand All @@ -158,9 +165,11 @@ class PluginConfig(yaml.YAMLObject):

:param name: The name of the plugin class to use to instantiate the plugin object
:type name: str
:param dict metadata_mapping: (optional) The mapping between eodag metadata and
:param metadata_mapping: (optional) The mapping between eodag metadata and
the plugin specific metadata
:param dict free_params: (optional) Additional configuration parameters
:type metadata_mapping: dict
:param free_params: (optional) Additional configuration parameters
:type free_params: dict
"""

yaml_loader = yaml.Loader
Expand Down Expand Up @@ -191,7 +200,8 @@ def validate(config_keys):
def update(self, mapping):
"""Update the configuration parameters with values from `mapping`

:param dict mapping: The mapping from which to override configuration parameters
:param mapping: The mapping from which to override configuration parameters
:type mapping: dict
"""
if mapping is None:
mapping = {}
Expand All @@ -201,7 +211,7 @@ def update(self, mapping):


def load_default_config():
"""Build the providers configuration into a dictionnary
"""Load the providers configuration into a dictionnary

:returns: The default provider's configuration
:rtype: dict
Expand All @@ -210,7 +220,7 @@ def load_default_config():


def load_config(config_path):
"""Build providers configuration into a dictionnary from a given file
"""Load the providers configuration into a dictionnary from a given file

:param config_path: The path to the provider config file
:type config_path: str
Expand Down Expand Up @@ -252,7 +262,8 @@ def provider_config_init(provider_config):
def override_config_from_file(config, file_path):
"""Override a configuration with the values in a file

:param dict config: An eodag providers configuration dictionary
:param config: An eodag providers configuration dictionary
:type config: dict
:param file_path: The path to the file from where the new values will be read
:type file_path: str
"""
Expand All @@ -271,7 +282,8 @@ def override_config_from_file(config, file_path):
def override_config_from_env(config):
"""Override a configuration with environment variables values

:param dict config: An eodag providers configuration dictionary
:param config: An eodag providers configuration dictionary
:type config: dict
"""

def build_mapping_from_env(env_var, env_value, mapping):
Expand All @@ -292,7 +304,8 @@ def build_mapping_from_env(env_var, env_value, mapping):
:type env_var: str
:param env_value: The value from environment variable
:type env_value: str
:param dict mapping: The mapping in which the value will be created
:param mapping: The mapping in which the value will be created
:type mapping: dict
"""
parts = env_var.split("__")
if len(parts) == 1:
Expand All @@ -316,8 +329,10 @@ def build_mapping_from_env(env_var, env_value, mapping):
def override_config_from_mapping(config, mapping):
"""Override a configuration with the values in a mapping

:param dict config: An eodag providers configuration dictionary
:param dict mapping: The mapping containing the values to be overriden
:param config: An eodag providers configuration dictionary
:type config: dict
:param mapping: The mapping containing the values to be overriden
:type mapping: dict
"""
for provider, new_conf in mapping.items():
old_conf = config.get(provider)
Expand All @@ -344,8 +359,10 @@ def override_config_from_mapping(config, mapping):
def merge_configs(config, other_config):
"""Override a configuration with the values of another configuration

:param dict config: An eodag providers configuration dictionary
:param dict other_config: An eodag providers configuration dictionary
:param config: An eodag providers configuration dictionary
:type config: dict
:param other_config: An eodag providers configuration dictionary
:type other_config: dict
"""
# configs union with other_config values as default
other_config = dict(config, **other_config)
Expand Down Expand Up @@ -374,7 +391,7 @@ def merge_configs(config, other_config):


def load_yml_config(yml_path):
"""Build a conf dictionnary from given yml absolute path
"""Load a conf dictionnary from given yml absolute path

:returns: The yml configuration file
:rtype: dict
Expand All @@ -384,7 +401,7 @@ def load_yml_config(yml_path):


def load_stac_config():
"""Build the stac configuration into a dictionnary
"""Load the stac configuration into a dictionnary

:returns: The stac configuration
:rtype: dict
Expand All @@ -395,7 +412,7 @@ def load_stac_config():


def load_stac_api_config():
"""Build the stac API configuration into a dictionnary
"""Load the stac API configuration into a dictionnary

:returns: The stac API configuration
:rtype: dict
Expand All @@ -406,7 +423,7 @@ def load_stac_api_config():


def load_stac_provider_config():
"""Build the stac provider configuration into a dictionnary
"""Load the stac provider configuration into a dictionnary

:returns: The stac provider configuration
:rtype: dict
Expand Down
Loading