feat(core): standardize global settings using pydantic

docs/api_reference/index.rst

@@ -18,6 +18,7 @@ The API Reference provides an overview of all public objects, functions and meth
    collection
    provider
    utils
+   settings
    exceptions
    types
    call_graphs
@@ -90,6 +91,14 @@ The API Reference provides an overview of all public objects, functions and meth
 
          Utility functions for logging, callbacks, text search, notebook integration, S3 operations, xarray support, and miscellaneous helpers.
 
+   .. grid-item-card:: :octicon:`gear;1.5em`  Settings
+         :link: settings
+         :link-type: doc
+         :text-align: center
+         :shadow: md
+
+         Configuration management and access to EODAG settings, including user and provider configuration files.
+
    .. grid-item-card:: :octicon:`alert;1.5em`  Exceptions
          :link: exceptions
          :link-type: doc

docs/api_reference/settings.rst

@@ -0,0 +1,14 @@
+.. module:: eodag.config
+
+========
+Settings
+========
+
+``EODAGSettings`` defines the global EODAG configuration parameters. Values can be provided directly when creating the
+settings object or overridden with ``EODAG_``-prefixed environment variables. See
+`Core configuration using environment variables <../getting_started_guide/configure.rst#core-configuration-using-environment-variables>`_
+for detailled information on the supported environment variables.
+
+.. autopydantic_settings:: EODAGSettings
+	:settings-hide-paramlist:
+	:exclude-members: __init__, warn_deprecated_settings, resolved_cfg_file, resolved_locations_cfg_file

docs/conf.py

@@ -378,8 +378,24 @@ def _html_page_context(app, pagename, templatename, context, doctree):
         context["theme_use_edit_page_button"] = False
 
 
+def _hide_base_settings_parameters(app, what, name, obj, options, lines):
+    """Hide inherited BaseSettings constructor parameters from EODAGSettings."""
+    if name != "eodag.config.EODAGSettings":
+        return
+
+    filtered_lines = []
+    skip_parameter = False
+    for line in lines:
+        if line.startswith(":param "):
+            skip_parameter = line.startswith(":param _")
+        if not skip_parameter:
+            filtered_lines.append(line)
+    lines[:] = filtered_lines
+
+
 def setup(app):
     """dummy docstring for pydocstyle"""
+    app.connect("autodoc-process-docstring", _hide_base_settings_parameters)
     app.connect("html-page-context", _html_page_context)
     app.connect("build-finished", _build_finished)
     app.set_translator("html", PatchedHTMLTranslator)

docs/getting_started_guide/configure.rst

@@ -151,7 +151,9 @@ Each configuration parameter can be set with an environment variable.
 Core configuration using environment variables
 """"""""""""""""""""""""""""""""""""""""""""""
 
-Some EODAG core settings can be overriden using environment variables:
+Some EODAG core settings are handled using `Pydantic settings <https://pydantic-docs.helpmanual.io/usage/settings/>`_
+through `EODAGSettings <../api_reference/settings.rst#eodag.config.EODAGSettings>`_ and can be overriden using
+environment variables:
 
 * ``EODAG_CFG_DIR`` customized configuration directory in place of `~/.config/eodag`.
 * ``EODAG_CFG_FILE`` for defining the desired path to the `user configuration file\

eodag/__init__.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 # Copyright 2018, CS GROUP - France, https://www.csgroup.eu/
 #
 # This file is part of EODAG project
@@ -33,16 +32,18 @@
 
 # exportable content
 __all__ = [
+    "EODAGSettings",
     "EODataAccessGateway",
     "EOProduct",
     "SearchResult",
-    "setup_logging",
     "config",
+    "setup_logging",
 ]
 
 # Lazy imports (PEP 562) — avoid loading heavy dependencies on ``import eodag``
 _LAZY_IMPORTS: dict[str, tuple[str, Optional[str]]] = {
     "EODataAccessGateway": (".api.core", "EODataAccessGateway"),
+    "EODAGSettings": (".config", "EODAGSettings"),
     "EOProduct": (".api.product", "EOProduct"),
     "SearchResult": (".api.search_result", "SearchResult"),
     "setup_logging": (".utils.logging", "setup_logging"),

eodag/api/collection.py

@@ -24,7 +24,7 @@
 
 from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
 from pydantic import ValidationError as PydanticValidationError
-from pydantic import model_validator
+from pydantic import ValidationInfo, model_validator
 from pydantic_core import ErrorDetails, InitErrorDetails, PydanticCustomError
 from stac_pydantic.collection import Extent, Provider, SpatialExtent, TimeInterval
 from stac_pydantic.links import Links
@@ -33,7 +33,6 @@
 from eodag.types.queryables import CommonStacMetadata
 from eodag.types.stac_metadata import create_stac_metadata_model
 from eodag.utils import STAC_VERSION
-from eodag.utils.env import is_env_var_true
 from eodag.utils.exceptions import ValidationError
 from eodag.utils.repr import dict_to_html_table
 
@@ -112,14 +111,25 @@ def model_post_init(self, context: Any) -> None:
         """Post-initialization method to set internal attributes."""
         self._id = self.id
 
+    @classmethod
+    def create(cls, validate_collections: bool = False, **kwargs: Any) -> Collection:
+        """Create a Collection with optional validation warning logging."""
+        return cls.model_validate(
+            kwargs,
+            context={"validate_collections": validate_collections},
+        )
+
     @classmethod
     def create_with_dag(cls, dag: EODataAccessGateway, **kwargs) -> Collection:
         """Create a Collection with a EODataAccessGateway instance.
 
         :param dag: The gateway instance to use to search products and to list queryables of the collection instance
         :param kwargs: The collection attributes
         """
-        instance = cls(**kwargs)
+        instance = cls.create(
+            validate_collections=dag.settings.validate_collections,
+            **kwargs,
+        )
         instance._dag = dag
         return instance
 
@@ -148,14 +158,20 @@ def set_id_from_alias(self) -> Self:
     @model_validator(mode="wrap")
     @classmethod
     def validate_collection(
-        cls, values: dict[str, Any] | Self, handler: ModelWrapValidatorHandler[Self]
+        cls,
+        values: dict[str, Any] | Self,
+        handler: ModelWrapValidatorHandler[Self],
+        info: ValidationInfo,
     ) -> Self:
         """Allow to create a collection instance with bad formatted attributes (except ``id``).
         Set incorrectly formatted attributes to ``None`` and ignore extra attributes.
-        Log a warning about validation errors if ``EODAG_VALIDATE_COLLECTIONS`` environment variable is set to ``True``.
+        Log a warning about validation errors when validation logging is enabled.
         """
         errors: list[ErrorDetails] = []
         continue_validation: bool = True
+        validate_collections = bool(
+            info.context and info.context.get("validate_collections", False)
+        )
 
         # iterate over each step of validation where error(s) raise(s)
         while continue_validation:
@@ -189,8 +205,8 @@ def validate_collection(
             else:
                 continue_validation = False
 
-        # log a warning if there were validation errors and the env var is set to True
-        if errors and is_env_var_true("EODAG_VALIDATE_COLLECTIONS"):
+        # log a warning if there were validation errors and logging is enabled
+        if errors and validate_collections:
             # log all errors at once
             error_title = f"collection {values_dict['id']}"
             init_errors: list[InitErrorDetails] = [