🚀 port changes of bdc-db 0.8.0

Author: raphaelrpl

CHANGES.rst

@@ -1,6 +1,6 @@
 ..
     This file is part of BDC-DB.
-    Copyright (C) 2023 INPE.
+    Copyright (C) 2025 INPE.
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -21,13 +21,16 @@ BDC-DB - Changes
 ================
 
 
-Version 0.8.0 (2023-10-02)
+Version 0.8.0 (2026-02-12)
 --------------------------
 
-- Upgrade libraries dependencies and support of SQLAlchemy 2x. (`#73 <https://github.com/brazil-data-cube/bdc-db/issues/73>`_).
-- Improve documentation for setup and extension.
-- Improve package Python version support: 3.8, 3.9, 3.10, 3.11+
-- Review unittests for bdc-db
+- Add support of pyproject toml (#78)
+- Add support of Python versions: 3.9, 3.10, 3.11, 3.12 and 3.13+
+- Drop support of pkg_resources (#77)
+- Review default values of SQLAlchemy engine options ``SQLALCHEMY_ENGINE_OPTIONS``.
+- Review documentation setup
+- Review unittests
+- Upgrade libraries dependencies and support of SQLAlchemy 2x. #73
 
 
 Version 0.6.3 (2022-09-22)

bdc_db/cli.py

@@ -31,7 +31,7 @@
 
 
 def abort_if_false(ctx, param, value):
-    """Callback that checks the user confirmation of a command."""
+    """Define the callback that checks the user confirmation of a command."""
     if not value:
         ctx.abort()
 
@@ -161,7 +161,7 @@ def show_namespaces():
 @db.command()
 @with_appcontext
 def create_extension_postgis():
-    """Enables the PostGIS extenion in the database."""
+    """Enable the PostGIS extenion in the database."""
     click.secho(f'Creating extension postgis...', bold=True, fg='yellow')
 
     with _db.session.begin_nested():
@@ -207,7 +207,7 @@ def create_triggers(verbose):
                 if verbose:
                     click.secho(content)
 
-                execute(content, executor=_db.session)
+                execute(content, executor=_db.session, commit=False)
 
             click.secho(f'Triggers from "{module_name}" registered', bold=True, fg='green')
 

bdc_db/config.py

@@ -27,12 +27,12 @@
 
 SQLALCHEMY_DATABASE_URI = os.getenv('SQLALCHEMY_DATABASE_URI',
                                     'postgresql://postgres:postgres@localhost:5432/bdc')
-"""The database URI that should be used for the database connection. 
+"""The database URI that should be used for the database connection.
 
 Defaults to ``'postgresql://postgres:postgres@localhost:5432/bdc'``."""
 
 SQLALCHEMY_TRACK_MODIFICATIONS = os.getenv('SQLALCHEMY_TRACK_MODIFICATIONS', False)
-"""Enable (True) or disable (False) signals before and after changes are committed to the database. 
+"""Enable (True) or disable (False) signals before and after changes are committed to the database.
 
 Defaults to ``False``."""
 
@@ -45,7 +45,11 @@
 """Define the hostname for any JSONSchemas supported by Brazil Data Cube."""
 
 SQLALCHEMY_ENGINE_OPTIONS = dict(
-    pool_pre_ping=True
+    pool_pre_ping=True,
+    pool_recycle=int(os.getenv("SQLALCHEMY_ENGINE_POOL_RECYCLE", 3600)),
+    pool_size=int(os.getenv("SQLALCHEMY_ENGINE_POOL_SIZE", 2)),
+    max_overflow=int(os.getenv("SQLALCHEMY_ENGINE_MAX_OVERFLOW", 1)),
+    poolclass=os.getenv("SQLALCHEMY_ENGINE_POOL_CLASS"),
 )
 """Set default engine options for SQLAlchemy instance.
 

bdc_db/ext.py

@@ -1,6 +1,6 @@
 #
 # This file is part of BDC-DB.
-# Copyright (C) 2022 INPE.
+# Copyright (C) 2025 INPE.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -18,8 +18,7 @@
 
 """Database management extension for Brazil Data Cube applications and services."""
 
-import importlib.resources
-from importlib.metadata import entry_points
+from importlib.util import find_spec
 from pathlib import Path
 from typing import Dict, Iterable, List
 
@@ -30,6 +29,7 @@
 
 from . import config as _config
 from .db import db as _db
+from .utils import entry_points
 
 
 def alembic_include_object(object, name, type_, reflected, compare_to):  # pragma: no cover
@@ -95,6 +95,9 @@ def init_app(self, app, **kwargs):
             entry_point_jsonschemas (str): Custom entry point group for JSONSchemas
             engine_options (dict): Custom SQLAlchemy Engine Options for instance object.
         """
+        if "bdc-db" in app.extensions:
+            return  # Ignore, already initialized.
+
         self.init_db(app, **kwargs)
 
         # Load package namespaces
@@ -108,15 +111,15 @@ def init_app(self, app, **kwargs):
 
         # prepare the configuration for multiple named branches
         # according to each package entry point
-        script_location = str(importlib.resources.path('bdc_db', 'alembic'))
+        script_location = resource_path("bdc_db.alembic")
 
         entrypoints = entry_points(group="bdc_db.alembic")
 
-        version_locations = [
-            (base_entry.name, str(importlib.resources.path(
-                base_entry.name, base_entry.attr
-            ))) for base_entry in entrypoints
-        ]
+        version_locations = []
+        for entry in entrypoints:
+            entry_name = f"{entry.name}.{entry.attr}"
+
+            version_locations.append((entry.name, resource_path(entry_name)))
 
         if ('bdc_db', script_location) in version_locations:  # pragma: no cover
             version_locations.remove(('bdc_db', str(script_location)))
@@ -154,18 +157,21 @@ def init_app(self, app, **kwargs):
         # Add BDC-DB extension to Flask extension list
         app.extensions['bdc-db'] = self
 
-    def init_db(self, app, entry_point_group: str = 'bdc_db.models', engine_options=None, **kwargs):
+    def init_db(self, app, entry_point_group: str = 'bdc_db.models', engine_options=None, uri: str = None, **kwargs):
         """Initialize Flask-SQLAlchemy extension.
 
         Args:
             app: Flask application
             entry_point_group: Entrypoint definition to load models
             engine_options: DB instance engine options
+            uri: the URI to override SQLAlchemy database uri from environment. Defaults to env ``SQLALCHEMY_DATABASE_URI``.
             kwargs: optional Arguments to Flask-SQLAlchemy.
         """
+        uri = uri or _config.SQLALCHEMY_DATABASE_URI
+
         # Setup SQLAlchemy
         app.config.setdefault('SQLALCHEMY_DATABASE_URI',
-                              _config.SQLALCHEMY_DATABASE_URI)
+                              uri)
 
         app.config.setdefault('SQLALCHEMY_TRACK_MODIFICATIONS',
                               _config.SQLALCHEMY_TRACK_MODIFICATIONS)
@@ -271,4 +277,18 @@ def register_scripts(self, module_name: str, trigger_name: str, path: str):
         """Register trigger command to BDC-DB."""
         self.scripts.setdefault(module_name, dict())
 
-        self.scripts[module_name][trigger_name] = path
+        self.scripts[module_name][trigger_name] = path
+
+
+def resource_path(entry_name: str):
+    """Resolve the module path.
+
+    Note:
+        This method returns None when not found or its invalid.
+    """
+    spec = find_spec(entry_name)
+
+    if spec and spec.submodule_search_locations:
+        path = list(spec.submodule_search_locations)[0]
+
+        return str(path)

bdc_db/utils.py

@@ -105,7 +105,7 @@ def delete_trigger(name: str, engine: Engine, table: str, schema: str = None):
     execute(f'DROP TRIGGER IF EXISTS {name} ON {schema}.{table}', engine)
 
 
-def execute(statement: t.Union[str, t.Any], executor: t.Union[Engine, t.Any], *args, **kwargs):
+def execute(statement: t.Union[str, t.Any], executor: t.Union[Engine, t.Any], commit=True, *args, **kwargs):
     """Execute a query statement in SQLAlchemy database engine.
 
     Args:
@@ -116,10 +116,12 @@ def execute(statement: t.Union[str, t.Any], executor: t.Union[Engine, t.Any], *a
         statement = text(statement)
 
     if isinstance(executor, Engine):
-        with executor.connect() as conn:
+        with executor.begin() as conn:
             result = conn.execute(statement, *args, **kwargs)
     else:
         result = executor.execute(statement, *args, **kwargs)
+        if commit:
+            executor.commit()
 
     return result
 
@@ -135,3 +137,31 @@ def has_schema(engine: Engine, schema: str, **kwargs) -> bool:
     """
     inspector = inspect(engine)
     return inspector.has_schema(schema, **kwargs)
+
+
+def entry_points(group):
+    """Retrieve the package entrypoints based on group name.
+
+    This method resolves the retro-compatibility between python versions.
+    On <3.10, the group property is not available due implementation.
+    To solve that, you should use importlib_metadata instead importlib.metadata.
+
+    This method should be removed when we drop support on python 3.9.
+    Its based on invenio-base:
+    https://github.com/inveniosoftware/invenio-base/blob/9f1b8ce862f9a865291f2adfe3916459b08c73e3/invenio_base/utils.py#L19
+    """
+    import importlib.metadata
+    from sys import version_info
+
+    if version_info < (3, 10):
+        eps = importlib.metadata.entry_points()
+        if isinstance(eps, dict):
+            eps = list(set(eps.get(group, [])))
+        else:
+            eps = {
+                ep.name: ep for ep in eps
+            }
+    else:
+        eps = importlib.metadata.entry_points(group=group)
+
+    return eps

bdc_db/version.py

@@ -18,4 +18,6 @@
 
 """Version information for BDC-DB."""
 
-__version__ = '0.8.0'
+from importlib.metadata import version
+
+__version__ = version(__package__)

docs/sphinx/conf.py

@@ -71,9 +71,9 @@
 html_theme = 'sphinx_rtd_theme'
 
 html_theme_options = {
-    'analytics_id': 'XXXXXXXXXX',
+#    'analytics_id': 'XXXXXXXXXX',
     'logo_only': False,
-    'display_version': True,
+    # 'display_version': True,
     'prev_next_buttons_location': 'both',
     'style_external_links': True,
     #'vcs_pageview_mode': 'edit',

pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "bdc-db"
+description = "A database management extension for Brazil Data Cube Applications and Services."
+readme = "README.rst"
+requires-python = ">=3.8"
+license = "GPL-3.0-only"
+authors = [
+    {name = "Brazil Data Cube Team", email = "[email protected]"},
+]
+keywords = [
+    "database",
+    "postgres",
+    "bdc",
+    "big",
+    "orm",
+]
+classifiers = [
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+version="0.8.0"
+dependencies = [
+    "Flask>=2",
+    "Flask-SQLAlchemy>=3.0",
+    "Flask-Alembic>=2.0.0,<3.2.0",
+    "invenio-jsonschemas>=1.1.4",
+    "jsonschema>=3",
+    "psycopg2-binary>=2.8",
+    "SQLAlchemy>=1.3",
+    "SQLAlchemy-Utils>=0.40.0",
+    "alembic>=1.12",
+]
+
+# Extras Dependencies
+[project.optional-dependencies]
+dev = ["pre-commit"]
+docs = [
+    "Sphinx>=7.0",
+    "sphinx_rtd_theme",
+    "sphinx-copybutton",
+    "sphinx-tabs",
+]
+tests = [
+    "coverage>=6.4",
+    "coveralls>=3.3",
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "pydocstyle>=4.0",
+    "isort>4.3",
+    "check-manifest>=0.40",
+]
+all = ["bdc-db[docs,tests]"]
+## End extras dependencies
+
+[build-system]
+requires = ["setuptools>=67.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["bdc_db*"]
+exclude = ["tests*"]
+namespaces = false
+
+[tool.setuptools.package-data]
+"bdc_db" = ["py.typed", "alembic/**"]
+
+[project.urls]
+Homepage = "https://github.com/brazil-data-cube/bdc-db"
+Documentation = "https://github.com/brazil-data-cube/bdc-db"
+Issues = "https://github.com/brazil-data-cube/bdc-db/-/issues"
+Source = "https://github.com/brazil-data-cube/bdc-db"
+# Changelog = ""
+
+[project.scripts]
+bdc-db = "bdc_db.cli:cli"

run-tests.sh

@@ -19,6 +19,14 @@
 
 pydocstyle bdc_db tests setup.py  && \
 isort bdc_db tests setup.py --check-only --diff && \
-check-manifest --ignore ".travis-*" --ignore ".readthedocs.*" && \
+check-manifest --ignore ".travis-*" && \
 sphinx-build -qnW --color -b doctest docs/sphinx/ docs/sphinx/_build/doctest && \
-pytest
+
+# When mode is package, just set context to wheel package name. Otherwise, it the local bdc_db fill fallback as default and no coverage will be found.
+if [ "${MODE}" == "package" ]; then
+    mkdir -p tmp && cd tmp
+    pytest ../tests --pyargs bdc_db --cov=bdc_db
+    cd .. && rm -r tmp
+else
+    pytest
+fi