chore: final review of documentation (#250)

apply changes asked when doing a final review of the documentation for the v2

.github/workflows/dependencies-tests.yml

@@ -19,7 +19,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install Copernicus Marine toolbox
+      - name: Install Copernicus Marine Toolbox
         run: pip install .
 
       - name: Install nox

CONTRIBUTION.md

@@ -17,7 +17,7 @@ After any implementation:
 
 ## Release Process
 
-The Copernicus Marine toolbox might maintain several versions at the same time. To this end, we create a branch that will be used for bug fixes and maintenance of the older versions: `release/*`. This branch is created when the development of the new major version starts.
+The Copernicus Marine Toolbox might maintain several versions at the same time. To this end, we create a branch that will be used for bug fixes and maintenance of the older versions: `release/*`. This branch is created when the development of the new major version starts.
 
 Please be aware when you do a fork and create a pull request which of the branch is relevant: `main` or any of `release/*`.
 

README.md

@@ -1,17 +1,23 @@
-
 <h1 align="center">Copernicus Marine Service Toolbox (CLI & Python)</h1>
 <div align="center">
-  <a href="https://pypi.org/project/copernicusmarine/"><img src="https://img.shields.io/pypi/v/copernicusmarine.svg?style=flat-square" alt="PyPI" /></a>
-  <a href="https://pypi.org/project/copernicusmarine/"><img src="https://img.shields.io/pypi/pyversions/copernicusmarine.svg?style=flat-square" alt="PyPI Supported Versions" /></a>
-  <a href="https://pypi.org/project/copernicusmarine/"><img src="https://img.shields.io/badge/platform-windows | linux | macos-lightgrey?style=flat-square" alt="Supported Platforms" /></a>
-  <a href="https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12"><img src="https://img.shields.io/badge/licence-EUPL-lightblue?style=flat-square" alt="Licence" /></a>
+  <a href="https://pypi.org/project/copernicusmarine/"><img src="https://img.shields.io/pypi/v/copernicusmarine.svg" alt="PyPI" /></a>
+  <a href="https://anaconda.org/conda-forge/copernicusmarine"><img src="https://img.shields.io/conda/vn/conda-forge/copernicusmarine?logo=anaconda" alt="conda-forge" /></a>
+  </div>
+  <div align="center">
+  <a href="https://pypi.org/project/copernicusmarine/"><img src="https://img.shields.io/pypi/pyversions/copernicusmarine.svg" alt="PyPI Supported Versions" /></a>
+  <a href="https://pypi.org/project/copernicusmarine/"><img src="https://img.shields.io/badge/platform-windows | linux | macos-lightgrey" alt="Supported Platforms" /></a>
+  <a href="https://hub.docker.com/r/copernicusmarine/copernicusmarine"><img src="https://img.shields.io/badge/docker-%230db7ed.svg?logo=docker&logoColor=white" alt="Docker" /></a>
+  <a href="https://toolbox-docs.marine.copernicus.eu/en/"><img src="https://img.shields.io/readthedocs/copernicusmarine/pre-releases-2.0.0a4?logo=readthedocs" alt="Documentation" /></a>
+  <a href="https://github.com/python/black"><img src="https://img.shields.io/badge/code%20style-black-000000?style==flat" alt="Code Style" /></a>
+  <a href="https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12"><img src="https://img.shields.io/badge/licence-EUPL-lightblue" alt="Licence" /></a>
+  <a href="https://pypistats.org/packages/copernicusmarine"><img src="https://img.shields.io/pypi/dm/copernicusmarine.svg" alt="Downloads" /></a>
 </div>
 
 ![Copernicus Marine Service and Mercator Ocean international logos](https://www.mercator-ocean.eu/wp-content/uploads/2022/05/Cartouche_CMEMS_poisson_MOi.png)
 
 ## Features
 
-The Copernicus Marine toolbox offers capabilities through both **Command Line Interface (CLI)** and **Python API**:
+The Copernicus Marine Toolbox offers capabilities through both **Command Line Interface (CLI)** and **Python API**:
 
 - **Metadata Information**: List and retrieve metadata information on all products, datasets, variables.
 - **Subset Datasets**: Subset datasets to extract only the parts of interest, in preferred format, such as Analysis-Ready Cloud-Optimized (ARCO) Zarr or NetCDF file format.

copernicusmarine/catalogue_parser/models.py

@@ -19,7 +19,7 @@
 
 class CopernicusMarineServiceNames(str, Enum):
     """
-    Services parsed by the Copernicus Marine toolbox.
+    Services parsed by the Copernicus Marine Toolbox.
     """
 
     GEOSERIES = "arco-geo-series"
@@ -32,7 +32,7 @@ class CopernicusMarineServiceNames(str, Enum):
 
 class CoperniusMarineServiceShortNames(str, Enum):
     """
-    Short names or the services parsed by the Copernicus Marine toolbox.
+    Short names or the services parsed by the Copernicus Marine Toolbox.
     Also accepted when a service is requested.
     """
 
@@ -613,8 +613,9 @@ class DatasetVersionPartNotFound(Exception):
 
     Please verifiy that the requested part can be found in
     the result of the :func:`~copernicusmarine.describe` command
-    for this specific dataset version and dataset id.
-    If yes, please contact user support.
+    for this specific dataset version and datasetID.
+    If yes, please contact the User Support, (widget chat on
+    `Copernicus Marine website <https://help.marine.copernicus.eu/en/>`_).
     """
 
     def __init__(self, version: CopernicusMarineVersion):
@@ -629,7 +630,8 @@ class DatasetVersionNotFound(Exception):
     Please verifiy that the requested version can be found in
     the result of the :func:`~copernicusmarine.describe` command
     for this specific dataset.
-    If yes, please contact user support.
+    If yes, please contact the User Support, (widget chat on
+    `Copernicus Marine website <https://help.marine.copernicus.eu/en/>`_).
     """
 
     def __init__(self, dataset: CopernicusMarineDataset):
@@ -643,12 +645,13 @@ class DatasetNotFound(Exception):
 
     Possible reasons:
 
-    - The dataset id is incorrect and not present in the catalog.
+    - The datasetID is incorrect and not present in the catalogue.
     - The dataset has been retired.
 
-    Please verifiy that the dataset id is can be found in
+    Please verifiy that the datasetID is can be found in
     the result of the :func:`~copernicusmarine.describe` command.
-    If yes, please contact user support.
+    If yes, please contact the User Support, (widget chat on
+    `Copernicus Marine website <https://help.marine.copernicus.eu/en/>`_).
     """
 
     def __init__(self, dataset_id: str):
@@ -696,5 +699,5 @@ def get_version_and_part_from_full_dataset_id(
         dataset_name = match.group(1)
         version = match.group(2) or VERSION_DEFAULT
     else:
-        raise Exception(f"Could not parse dataset id: {full_dataset_id}")
+        raise Exception(f"Could not parse datasetID: {full_dataset_id}")
     return dataset_name, version, part

copernicusmarine/command_line_interface/group_describe.py

@@ -30,7 +30,7 @@ def cli_describe() -> None:
 @cli_describe.command(
     "describe",
     cls=CustomClickOptionsCommand,
-    short_help="Print Copernicus Marine catalogue as JSON.",
+    short_help="Print products metadata of Copernicus Marine catalogue as JSON.",
     help=documentation_utils.DESCRIBE["DESCRIBE_DESCRIPTION_HELP"]
     + " \n\nReturns\n "
     + documentation_utils.DESCRIBE["DESCRIBE_RESPONSE_HELP"],  # noqa

copernicusmarine/core_functions/credentials_utils.py

@@ -77,8 +77,8 @@ class CredentialsCannotBeNone(Exception):
     To use the Copernicus Marine Service, you need to provide a username and
     a password. You can set them as environment variables or pass them as
     arguments to the function or use the :func:`~copernicusmarine.login` command.
-    To register and create your valid credentials, please visit:
-    `copernicusmarine registration page <https://data.marine.copernicus.eu/register>`_
+    To register and create your valid credentials, please visit the
+    Copernicus Marine `registration page <https://data.marine.copernicus.eu/register>`_
     """
 
     pass
@@ -89,7 +89,7 @@ class InvalidUsernameOrPassword(Exception):
     Exception raised when the username or password are invalid.
 
     To register and create your valid credentials, please visit:
-    `copernicusmarine registration page <https://data.marine.copernicus.eu/register>`_
+    Copernicus Marine `registration page <https://data.marine.copernicus.eu/register>`_
     """
 
     pass
@@ -102,7 +102,7 @@ class CouldNotConnectToAuthenticationSystem(Exception):
     Please check the following common problems:
 
     - Check your internet connection
-    - make sure to authorize ``cmems-cas.cls.fr`` and/or ``auth.marine.copernicus.eu`` domains
+    - Make sure to authorize ``cmems-cas.cls.fr`` and/or ``auth.marine.copernicus.eu`` domains
 
     If none of this worked, maybe the authentication system is down, please try again later.
     """  # noqa

copernicusmarine/core_functions/documentation_utils.py

@@ -3,10 +3,10 @@
 SHARED: dict[str, str] = {
     "OVERWRITE_HELP": "If specified and if the file already exists on destination, then it will be overwritten. By default, the toolbox creates a new file with a new index (eg 'filename_(1).nc').",  # noqa: E501
     "USERNAME_HELP": (
-        "The username for authentication."
+        "If not set, search for environment variable COPERNICUSMARINE_SERVICE_USERNAME, then search for a credentials file, else ask for user input."  # noqa
     ),  # a little hardcoding in Python API
     "PASSWORD_HELP": (
-        "The password for authentication."
+        "If not set, search for environment variable COPERNICUSMARINE_SERVICE_PASSWORD, then search for a credentials file, else ask for user input."  # noqa
     ),  # a little hardcoding in Python API
     "LOG_LEVEL_HELP": (
         "Set the details printed to console by the command "
@@ -56,8 +56,13 @@
         " under the ``$HOME/.copernicusmarine`` directory."
     ),
     "LOGIN_RESPONSE_HELP": (
-        "Exit code\n 0 exit code if the login was successfully "
-        "completed, 1 otherwise."
+        "Exit code\n 0 if the login was successfully completed, 1 otherwise."
+    ),
+    "USERNAME_HELP": (
+        "If not set, search for environment variable COPERNICUSMARINE_SERVICE_USERNAME, else ask for user input."  # noqa
+    ),
+    "PASSWORD_HELP": (
+        "If not set, search for environment variable COPERNICUSMARINE_SERVICE_PASSWORD, else ask for user input."  # noqa
     ),
     "CONFIGURATION_FILE_DIRECTORY_HELP": (
         "Path to the directory where the configuration file will be stored."
@@ -123,7 +128,7 @@
 
 SUBSET: dict[str, str] = {
     "SUBSET_DESCRIPTION_HELP": (
-        "Extracts a subset of data from a specified dataset using given parameters."
+        "Extract a subset of data from a specified dataset using given parameters."
         "\n\nThe datasetID is required and can be found via the ``describe`` "
         "command. "  # has some hardcoding in CLI and python API
     ),

copernicusmarine/core_functions/environment_variables.py

@@ -25,7 +25,7 @@
 )
 
 COPERNICUSMARINE_DISABLE_SSL_CONTEXT = os.getenv(
-    "COPERNICUSMARINE_DISABLE_SSL_CONTEXT"
+    "COPERNICUSMARINE_DISABLE_SSL_CONTEXT", "False"
 )
 
 COPERNICUSMARINE_SET_SSL_CERTIFICATE_PATH = os.getenv(

copernicusmarine/core_functions/exceptions.py

@@ -64,7 +64,7 @@ class NetCDFCompressionNotAvailable(Exception):
     Exception raised when the NetCDF compression is not available.
 
     Please make sure the NetCDF compression is available
-    with the current python libraries.
+    with the current Python libraries.
     """
 
     pass
@@ -77,7 +77,7 @@ class WrongDatetimeFormat(Exception):
     Supported formats are:
 
     * the string "now"
-    * all formats supported by dateutil python library
+    * all formats supported by dateutil Python library
 
     see `dateutil documentation page <https://dateutil.readthedocs.io/en/stable/parser.html>`_.
     """  # noqa

copernicusmarine/core_functions/services_utils.py

@@ -285,7 +285,7 @@ def get_retrieval_service(
     if not dataset_metadata:
         raise KeyError(
             f"The requested dataset '{dataset_id}' was not found in the catalogue,"
-            " you can use 'copernicusmarine describe --include-datasets "
+            " you can use 'copernicusmarine describe -r datasets "
             "--contains <search_token>' to find datasets"
         )
     force_service_name: Optional[CopernicusMarineServiceNames] = (

copernicusmarine/core_functions/sessions.py

@@ -43,8 +43,12 @@
 
 
 def get_ssl_context() -> Optional[ssl.SSLContext]:
-    if COPERNICUSMARINE_DISABLE_SSL_CONTEXT is not None:
+    if COPERNICUSMARINE_DISABLE_SSL_CONTEXT == "True":
         return None
+    if COPERNICUSMARINE_SET_SSL_CERTIFICATE_PATH:
+        return ssl.create_default_context(
+            capath=COPERNICUSMARINE_SET_SSL_CERTIFICATE_PATH
+        )
     return ssl.create_default_context(cafile=certifi.where())
 
 
@@ -89,9 +93,12 @@ class ConfiguredRequestsSession(requests.Session):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.trust_env = TRUST_ENV
-        self.verify = (
-            COPERNICUSMARINE_SET_SSL_CERTIFICATE_PATH or certifi.where()
-        )
+        if COPERNICUSMARINE_DISABLE_SSL_CONTEXT == "True":
+            self.verify = False
+        else:
+            self.verify = (
+                COPERNICUSMARINE_SET_SSL_CERTIFICATE_PATH or certifi.where()
+            )
         self.proxies = PROXIES
         if HTTPS_RETRIES:
             self.mount(

copernicusmarine/python_interface/get.py

@@ -55,9 +55,9 @@ def get(
     dataset_part : str, optional
         Force the selection of a specific dataset part.
     username : str, optional
-        The username for authentication.
+        If not set, search for environment variable COPERNICUSMARINE_SERVICE_USERNAME, then search for a credentials file, else ask for user input. See also :func:`~copernicusmarine.login`
     password : str, optional
-        The password for authentication.
+        If not set, search for environment variable COPERNICUSMARINE_SERVICE_PASSWORD, then search for a credentials file, else ask for user input. See also :func:`~copernicusmarine.login`
     no_directories : bool, optional
         If True, downloaded files will not be organized into directories.
     output_directory : Union[pathlib.Path, str], optional

copernicusmarine/python_interface/login.py

@@ -21,9 +21,9 @@ def login(
     Parameters
     ----------
     username : str, optional
-        The username for authentication.
+        If not set, search for environment variable COPERNICUSMARINE_SERVICE_USERNAME, else ask for user input.
     password : str, optional
-        The password for authentication.
+        If not set, search for environment variable COPERNICUSMARINE_SERVICE_PASSWORD, else ask for user input.
     configuration_file_directory : Union[pathlib.Path, str]
         Path to the directory where the configuration file will be stored.
     force_overwrite : bool

copernicusmarine/python_interface/open_dataset.py

@@ -75,9 +75,9 @@ def open_dataset(
     dataset_part : str, optional
         Force the selection of a specific dataset part.
     username : str, optional
-        The username for authentication.
+        If not set, search for environment variable COPERNICUSMARINE_SERVICE_USERNAME, then search for a credentials file, else ask for user input. See also :func:`~copernicusmarine.login`
     password : str, optional
-        The password for authentication.
+        If not set, search for environment variable COPERNICUSMARINE_SERVICE_PASSWORD, then search for a credentials file, else ask for user input. See also :func:`~copernicusmarine.login`
     variables : List[str], optional
         List of variable names to extract.
     minimum_longitude : float, optional

copernicusmarine/python_interface/subset.py

@@ -63,7 +63,7 @@ def subset(
     chunk_size_limit: int = 100,
 ) -> ResponseSubset:
     """
-    Extracts a subset of data from a specified dataset using given parameters.
+    Extract a subset of data from a specified dataset using given parameters.
 
     The datasetID is required and can be found via the ``describe`` command.
 
@@ -76,9 +76,9 @@ def subset(
     dataset_part : str, optional
         Force the selection of a specific dataset part.
     username : str, optional
-        The username for authentication. See also :func:`~copernicusmarine.login`
+        If not set, search for environment variable COPERNICUSMARINE_SERVICE_USERNAME, then search for a credentials file, else ask for user input. See also :func:`~copernicusmarine.login`
     password : str, optional
-        The password for authentication. See also :func:`~copernicusmarine.login`
+        If not set, search for environment variable COPERNICUSMARINE_SERVICE_PASSWORD, then search for a credentials file, else ask for user input. See also :func:`~copernicusmarine.login`
     variables : List[str], optional
         List of variable names to extract.
     minimum_longitude : float, optional