hdx-python-database 1.2.1__tar.gz → 1.2.2__tar.gz

{hdx-python-database-1.2.1 → hdx-python-database-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hdx-python-database
-Version: 1.2.1
+Version: 1.2.2
 Summary: HDX Python database utilities
 Home-page: https://github.com/OCHA-DAP/hdx-python-database
 Author: Michael Rans

{hdx-python-database-1.2.1 → hdx-python-database-1.2.2}/doc/main.md

@@ -17,11 +17,14 @@ Additional postgresql functionality is available if this library is installed wi
 
 ## Breaking changes
 
+From 1.2.2, database datetime columns are assumed to be timezoneless unless
+db_has_tz is set to True.
+
 From 1.2.1, wait_for_postgresql takes connection URI not database parameters, 
 get_params_from_sqlalchemy_url renamed to get_params_from_connection_uri
 and moved to dburi module, get_sqlalchemy_url renamed to get_connection_uri and 
 moved to dburi module. New function remove_driver_from_uri in dburi module.
-Parameter driver replaced by dialect+driver. 
+Parameter driver replaced by dialect+driver. Supports Python 3.8 and later.
 
 From 1.1.2, the postgres module is renamed postgresql and function wait_for_postgres
 is renamed wait_for_postgresql.
@@ -34,8 +37,8 @@ Versions from 1.0.6 no longer support Python 2.7.
 
 ## Database
 
-Your SQLAlchemy database tables must inherit from Base in
-hdx.utilities.database eg. :
+Your SQLAlchemy database tables must inherit from `Base` in
+`hdx.database` or `hdx.database.database_notz` eg. :
 
     from hdx.database import Base
     class MyTable(Base):
@@ -51,9 +54,13 @@ tunnel:
     with Database(database="db", host="1.2.3.4", username="user", 
                   password="pass", dialect="dialect", driver="driver", 
                   ssh_host="5.6.7.8", ssh_port=2222, ssh_username="sshuser", 
-                  ssh_private_key="path_to_key") as session:
+                  ssh_private_key="path_to_key", db_has_tz=True) as session:
         session.query(...)
 
+`db_has_tz` which defaults to `False` indicates whether database datetime 
+columns have timezones. If not, conversion occurs between Python datetimes
+with timezones to timezoneless database columns.   
+
 ## Connection URI
 
 There are functions to handle converting from connection URIs to parameters and

{hdx-python-database-1.2.1 → hdx-python-database-1.2.2}/requirements.txt

@@ -1,3 +1,3 @@
 psycopg[binary]==3.1.8
-sqlalchemy==2.0.3
+sqlalchemy==2.0.4
 sshtunnel==0.4.0

{hdx-python-database-1.2.1 → hdx-python-database-1.2.2}/src/hdx/database/__init__.py

@@ -3,30 +3,32 @@ from .dburi import get_connection_uri
 
 """Database utilities"""
 import logging
-from typing import Any, Optional, Union
+from typing import Any, Optional, Type, Union
 
 from sqlalchemy import create_engine
-from sqlalchemy.ext.declarative import declarative_base, declared_attr
-from sqlalchemy.orm import Session, sessionmaker
+from sqlalchemy.ext.declarative import declared_attr
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
 from sqlalchemy.pool import NullPool
 from sshtunnel import SSHTunnelForwarder
 
-from hdx.database.postgresql import wait_for_postgresql
+from .no_timezone import Base as NoTZBase
+from .postgresql import wait_for_postgresql
 
 logger = logging.getLogger(__name__)
 
 
-class HDXBase:
+class Base(DeclarativeBase):
     @declared_attr.directive
     def __tablename__(cls):
         return f"{cls.__name__.lower()}s"
 
 
-Base = declarative_base(cls=HDXBase)
-
-
 class Database:
-    """Database helper class to handle ssh tunnels, waiting for PostgreSQL to be up etc.
+    """Database helper class to handle ssh tunnels, waiting for PostgreSQL to
+    be up etc. Can be used in a with statement returning a Session object.
+    db_has_tz which defaults to False indicates whether database datetime
+    columns have timezones. If not, conversion occurs between Python datetimes
+    with timezones to timezoneless database columns.
 
     Args:
         database (Optional[str]): Database name
@@ -36,6 +38,7 @@ class Database:
         password (Optional[str]): Password to log into database
         dialect (str): Database dialect. Defaults to "postgresql".
         driver (Optional[str]): Database driver. Defaults to None (psycopg if postgresql or None)
+        db_has_tz (bool): True if db datetime columns have timezone. Defaults to False.
         **kwargs: See below
         ssh_host (str): SSH host (the server to connect to)
         ssh_port (int): SSH port. Defaults to 22.
@@ -55,6 +58,7 @@ class Database:
         password: Optional[str] = None,
         dialect: str = "postgresql",
         driver: Optional[str] = None,
+        db_has_tz: bool = False,
         **kwargs: Any,
     ) -> None:
         if port is not None:
@@ -89,7 +93,11 @@ class Database:
         )
         if dialect == "postgresql":
             wait_for_postgresql(db_uri)
-        self.session = self.get_session(db_uri)
+        if db_has_tz:
+            table_base = Base
+        else:
+            table_base = NoTZBase
+        self.session = self.get_session(db_uri, table_base=table_base)
 
     def __enter__(self) -> Session:
         return self.session
@@ -100,17 +108,20 @@ class Database:
             self.server.stop()
 
     @staticmethod
-    def get_session(db_uri: str) -> Session:
-        """Gets SQLAlchemy session given url. Your tables must inherit
-        from Base in hdx.utilities.database.
+    def get_session(
+        db_uri: str, table_base: Type[DeclarativeBase] = NoTZBase
+    ) -> Session:
+        """Gets SQLAlchemy session given url. Tables must inherit from Base in
+        hdx.utilities.database unless base is defined.
 
         Args:
             db_uri (str): Connection URI
+            table_base (Type[DeclarativeBase]): Base database table class. Defaults to NoTZBase.
 
         Returns:
             sqlalchemy.orm.Session: SQLAlchemy session
         """
         engine = create_engine(db_uri, poolclass=NullPool, echo=False)
         Session = sessionmaker(bind=engine)
-        Base.metadata.create_all(engine)
+        table_base.metadata.create_all(engine)
         return Session()

{hdx-python-database-1.2.1 → hdx-python-database-1.2.2}/src/hdx/database/_version.py

@@ -1,4 +1,4 @@
 # file generated by setuptools_scm
 # don't change, don't track in version control
-__version__ = version = '1.2.1'
-__version_tuple__ = version_tuple = (1, 2, 1)
+__version__ = version = '1.2.2'
+__version_tuple__ = version_tuple = (1, 2, 2)

hdx-python-database-1.2.2/src/hdx/database/no_timezone.py

@@ -0,0 +1,40 @@
+"""Utilities for database datetime columns without timezone"""
+from datetime import datetime, timezone
+from typing import Optional
+
+from sqlalchemy import DateTime, TypeDecorator
+from sqlalchemy.orm import DeclarativeBase, declared_attr
+
+
+class ConversionNoTZ(TypeDecorator):
+    """Convert from/to datetime with timezone from database columns that don't
+    use timezone"""
+
+    impl = DateTime
+    cache_ok = True
+
+    def process_bind_param(self, value: Optional[datetime], _):
+        if value is None:
+            return value
+        if value.tzinfo:
+            value = value.astimezone(timezone.utc)
+
+        return value.replace(tzinfo=None)
+
+    def process_result_value(self, value, _):
+        if value is None:
+            return value
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+
+        return value.astimezone(timezone.utc)
+
+
+class Base(DeclarativeBase):
+    type_annotation_map = {
+        datetime: ConversionNoTZ,
+    }
+
+    @declared_attr.directive
+    def __tablename__(cls):
+        return f"{cls.__name__.lower()}s"

{hdx-python-database-1.2.1 → hdx-python-database-1.2.2}/src/hdx/database/postgresql.py

@@ -2,7 +2,7 @@
 import logging
 import time
 
-from hdx.database.dburi import remove_driver_from_uri
+from .dburi import remove_driver_from_uri
 
 try:
     import psycopg

{hdx-python-database-1.2.1 → hdx-python-database-1.2.2}/src/hdx_python_database.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hdx-python-database
-Version: 1.2.1
+Version: 1.2.2
 Summary: HDX Python database utilities
 Home-page: https://github.com/OCHA-DAP/hdx-python-database
 Author: Michael Rans

{hdx-python-database-1.2.1 → hdx-python-database-1.2.2}/src/hdx_python_database.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ doc/main.md
 src/hdx/database/__init__.py
 src/hdx/database/_version.py
 src/hdx/database/dburi.py
+src/hdx/database/no_timezone.py
 src/hdx/database/postgresql.py
 src/hdx_python_database.egg-info/PKG-INFO
 src/hdx_python_database.egg-info/SOURCES.txt
@@ -19,9 +20,9 @@ src/hdx_python_database.egg-info/dependency_links.txt
 src/hdx_python_database.egg-info/requires.txt
 src/hdx_python_database.egg-info/top_level.txt
 src/hdx_python_database.egg-info/zip-safe
-tests/test_database.db
 tests/hdx/database/__init__.py
 tests/hdx/database/conftest.py
+tests/hdx/database/dbtestdate.py
 tests/hdx/database/test_database.py
 tests/hdx/database/test_dburi.py
 tests/hdx/database/test_postgresql.py

{hdx-python-database-1.2.1 → hdx-python-database-1.2.2}/test-requirements.txt

@@ -1,4 +1,4 @@
 pytest==7.2.1
 pytest-cov==4.0.0
-tox==4.4.5
+tox==4.4.6
 -r requirements.txt

hdx-python-database-1.2.2/tests/hdx/database/dbtestdate.py

@@ -0,0 +1,23 @@
+"""SQLAlchemy class representing DBTestDate row. Holds test data for dates.
+"""
+from datetime import datetime
+
+from sqlalchemy.orm import Mapped, mapped_column
+
+from hdx.database.no_timezone import Base
+
+
+class DBTestDate(Base):
+    """
+    test_date: Mapped[datetime] = mapped_column(primary_key=True)
+    """
+
+    test_date: Mapped[datetime] = mapped_column(primary_key=True)
+
+    def __repr__(self) -> str:
+        """String representation of DBTestDate row
+
+        Returns:
+            str: String representation of DBTestDate row
+        """
+        return f"<Test date={str(self.test_date)}>"

{hdx-python-database-1.2.1 → hdx-python-database-1.2.2}/tests/hdx/database/test_database.py

@@ -2,17 +2,23 @@
 import copy
 import os
 from collections import namedtuple
+from datetime import datetime, timezone
 from os.path import join
 
 import pytest
+from sqlalchemy import select
 from sshtunnel import SSHTunnelForwarder
 
-from hdx.database import Database
+from hdx.database import Base, Database
+from hdx.database.no_timezone import Base as NoTZBase
+
+from .dbtestdate import DBTestDate
 
 
 class TestDatabase:
     started = False
     stopped = False
+    table_base = NoTZBase
     dbpath = join("tests", "test_database.db")
     params_pg = {
         "database": "mydatabase",
@@ -49,7 +55,7 @@ class TestDatabase:
         monkeypatch.setattr(SSHTunnelForwarder, "local_bind_host", "0.0.0.0")
         monkeypatch.setattr(SSHTunnelForwarder, "local_bind_port", 12345)
 
-        def get_session(_, db_url):
+        def get_session(_, db_url, table_base):
             class Session:
                 bind = namedtuple("Bind", "engine")
 
@@ -58,6 +64,7 @@ class TestDatabase:
 
             Session.bind.engine = namedtuple("Engine", "url")
             Session.bind.engine.url = db_url
+            TestDatabase.table_base = table_base
             return Session()
 
         monkeypatch.setattr(Database, "get_session", get_session)
@@ -67,6 +74,14 @@ class TestDatabase:
             database=TestDatabase.dbpath, port=None, dialect="sqlite"
         ) as dbsession:
             assert str(dbsession.bind.engine.url) == nodatabase
+            assert TestDatabase.table_base == NoTZBase
+            now = datetime(2022, 10, 20, 22, 35, 55, tzinfo=timezone.utc)
+            input_dbtestdate = DBTestDate()
+            input_dbtestdate.test_date = now
+            dbsession.add(input_dbtestdate)
+            dbsession.commit()
+            dbtestdate = dbsession.execute(select(DBTestDate)).scalar_one()
+            assert dbtestdate.test_date == now
 
     def test_get_session_ssh(self, mock_psycopg, mock_SSHTunnelForwarder):
         with Database(
@@ -85,3 +100,12 @@ class TestDatabase:
                 str(dbsession.bind.engine.url)
                 == "postgresql+psycopg://myuser@0.0.0.0:12345/mydatabase"
             )
+        assert TestDatabase.table_base == NoTZBase
+        with Database(
+            ssh_host="mysshhost", ssh_port=25, db_has_tz=True, **params
+        ) as dbsession:
+            assert (
+                str(dbsession.bind.engine.url)
+                == "postgresql+psycopg://myuser@0.0.0.0:12345/mydatabase"
+            )
+            assert TestDatabase.table_base == Base