database-wrapper 0.1.28__tar.gz

database_wrapper-0.1.28/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.1
+Name: database_wrapper
+Version: 0.1.28
+Summary: A Different Approach to Database Wrappers in Python
+Author-email: Gints Murans <gm@gm.lv>
+License: GNU General Public License v3.0 (GPL-3.0)
+Project-URL: Homepage, https://github.com/gintsmurans/py_database_wrapper
+Project-URL: Documentation, https://github.com/gintsmurans/py_database_wrapper
+Project-URL: Changes, https://github.com/gintsmurans/py_database_wrapper
+Project-URL: Code, https://github.com/gintsmurans/py_database_wrapper
+Project-URL: Issue Tracker, https://github.com/gintsmurans/py_database_wrapper/issues
+Project-URL: Download, https://pypi.org/project/database_wrapper/
+Keywords: database,wrapper,python,pgsql,mysql,mssql,sqlite
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: pgsql
+Requires-Dist: database_wrapper_pgsql==0.1.28; extra == "pgsql"
+Provides-Extra: mysql
+Requires-Dist: database_wrapper_mysql==0.1.28; extra == "mysql"
+Provides-Extra: mssql
+Requires-Dist: database_wrapper_mssql==0.1.28; extra == "mssql"
+Provides-Extra: sqlite
+Requires-Dist: database_wrapper_sqlite==0.1.28; extra == "sqlite"
+Provides-Extra: all
+Requires-Dist: database_wrapper[mssql,mysql,pgsql,sqlite]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: ast-comments>=1.1.2; extra == "dev"
+Requires-Dist: codespell>=2.2; extra == "dev"
+Requires-Dist: build>=1.2.1; extra == "dev"
+Requires-Dist: black>=24.1.0; extra == "dev"
+Requires-Dist: types-setuptools>=61.0.0; extra == "dev"
+Requires-Dist: types-pymssql>=2.1.0; extra == "dev"
+Requires-Dist: psycopg[binary]>=3.2.0; extra == "dev"
+Requires-Dist: psycopg[pool]>=3.2.0; extra == "dev"
+Requires-Dist: mysqlclient>=2.2.2; extra == "dev"
+Requires-Dist: pymssql>=2.2.10; extra == "dev"
+
+# database_wrapper
+
+_Part of the `database_wrapper` package._
+
+This package is a base package for database wrappers. It is not intended to be used directly, but rather to be used via one of the database specific packages.
+
+
+See the README.md files in the database specific packages for more information.
+
+* [database_wrapper_pgsql](https://pypi.org/project/database_wrapper_pgsql/)
+* [database_wrapper_mysql](https://pypi.org/project/database_wrapper_mysql/)
+* [database_wrapper_mssql](https://pypi.org/project/database_wrapper_mssql/)
+* [database_wrapper_sqlite](https://pypi.org/project/database_wrapper_sqlite/)

database_wrapper-0.1.28/README.md

@@ -0,0 +1,13 @@
+# database_wrapper
+
+_Part of the `database_wrapper` package._
+
+This package is a base package for database wrappers. It is not intended to be used directly, but rather to be used via one of the database specific packages.
+
+
+See the README.md files in the database specific packages for more information.
+
+* [database_wrapper_pgsql](https://pypi.org/project/database_wrapper_pgsql/)
+* [database_wrapper_mysql](https://pypi.org/project/database_wrapper_mysql/)
+* [database_wrapper_mssql](https://pypi.org/project/database_wrapper_mssql/)
+* [database_wrapper_sqlite](https://pypi.org/project/database_wrapper_sqlite/)

database_wrapper-0.1.28/database_wrapper/__init__.py

@@ -0,0 +1,29 @@
+"""
+database_wrapper package - Base for database wrappers
+"""
+
+# Copyright 2024 Gints Murans
+
+import logging
+
+from . import utils
+from .db_backend import DatabaseBackend
+from .db_data_model import DBDataModel, DBDefaultsDataModel
+from .db_wrapper import DBWrapper, T, OrderByItem
+
+# Set the logger to a quiet default, can be enabled if needed
+logger = logging.getLogger("database_wrapper")
+if logger.level == logging.NOTSET:
+    logger.setLevel(logging.WARNING)
+
+
+# Expose the classes
+__all__ = [
+    "DatabaseBackend",
+    "DBDataModel",
+    "DBDefaultsDataModel",
+    "DBWrapper",
+    "T",
+    "OrderByItem",
+    "utils",
+]

database_wrapper-0.1.28/database_wrapper/config.py

@@ -0,0 +1,9 @@
+from typing import Any
+
+CONFIG: dict[str, Any] = {
+    # These are supposed to be set automatically by a git pre-compile script
+    # They are one git commit hash behind, if used automatically
+    "git_commit_hash": "0a78ab759900ae378034f586a361aa24f43aad15",
+    "git_commit_date": "08.11.2024 15:05",
+    "app_version": "0.1.28",
+}

database_wrapper-0.1.28/database_wrapper/db_backend.py

@@ -0,0 +1,161 @@
+import logging
+import socket
+
+from typing import Any
+from threading import Event
+from contextvars import ContextVar
+
+from .utils.timer import Timer
+
+
+class DatabaseBackend:
+    connection: Any
+    cursor: Any
+    contextConnection: ContextVar[Any | None]
+    contextAsyncConnection: ContextVar[Any | None]
+
+    config: Any
+
+    connectionTimeout: int
+    slowDownTimeout: int = 5
+
+    name: str
+    logger: logging.Logger
+    timer: ContextVar[Timer | None]
+
+    shutdownRequested: Event
+
+    def __init__(
+        self,
+        dbConfig: Any,
+        connectionTimeout: int = 5,
+        instanceName: str = "database_backend",
+    ) -> None:
+        """
+        Main concept here is that in init we do not connect to database,
+        so that class instances can be safely made regardless of connection statuss.
+
+        Remember to call open() before using this class.
+        Close will be called automatically when class is destroyed.
+        But sometimes in async environment you should call close() proactively.
+        """
+
+        self.config = dbConfig
+        self.connectionTimeout = connectionTimeout
+        self.name = instanceName
+
+        loggerName = f"{__name__}.{self.__class__.__name__}.{self.name}"
+        self.logger = logging.getLogger(loggerName)
+        self.timer = ContextVar(f"db_timer", default=None)
+
+        self.connection = None
+        self.cursor = None
+        self.shutdownRequested = Event()
+        self.contextConnection = ContextVar(f"pg_connection_{self.name}", default=None)
+        self.contextAsyncConnection = ContextVar(
+            f"pg_async_connection_{self.name}", default=None
+        )
+
+    def __del__(self) -> None:
+        """What to do when class is destroyed"""
+        self.logger.debug("Dealloc")
+        self.close()
+
+    # Context
+    def __enter__(self) -> tuple[Any, Any]:
+        """Context manager"""
+        raise Exception("Not implemented")
+
+    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        """Context manager"""
+        raise Exception("Not implemented")
+
+    async def __aenter__(self) -> tuple[Any, Any]:
+        """Context manager"""
+        raise Exception("Not implemented")
+
+    async def __aexit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        """Context manager"""
+        raise Exception("Not implemented")
+
+    # Connection
+    def open(self) -> None:
+        """Connect to database"""
+        raise Exception("Not implemented")
+
+    async def openAsync(self) -> None:
+        """Connect to database"""
+        raise Exception("Not implemented")
+
+    def close(self) -> None:
+        """Close connections"""
+        if self.cursor:
+            self.logger.debug("Closing cursor")
+            self.cursor.close()
+            self.cursor = None
+
+        if self.connection:
+            self.logger.debug("Closing connection")
+            self.connection.close()
+            self.connection = None
+
+    def fixSocketTimeouts(self, fd: Any):
+        # Lets do some socket magic
+        s = socket.fromfd(fd, socket.AF_INET, socket.SOCK_STREAM)
+        # Enable sending of keep-alive messages
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+        # Time the connection needs to remain idle before start sending
+        # keepalive probes
+        s.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, self.connectionTimeout)
+        # Time between individual keepalive probes
+        s.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, 1)
+        # The maximum number of keepalive probes should send before dropping
+        # the connection
+        s.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, 3)
+        # To set timeout for an RTO you must set TCP_USER_TIMEOUT timeout
+        # (in milliseconds) for socket.
+        s.setsockopt(
+            socket.IPPROTO_TCP, socket.TCP_USER_TIMEOUT, self.connectionTimeout * 1000
+        )
+
+    async def newConnection(
+        self,
+    ) -> tuple[Any, Any] | None:
+        """
+        Create new connection
+
+        Used for async context manager and async connection creation
+
+        Returns:
+            tuple[Any, Any] | None: Connection and cursor
+        """
+        raise Exception("Not implemented")
+
+    async def returnConnection(self, connection: Any) -> None:
+        """
+        Return connection to pool
+
+        Used for async context manager and async connections return.
+        For example to return connection to a pool.
+
+        Args:
+            connection (Any): Connection to return to pool
+        """
+        raise Exception("Not implemented")
+
+    # Data
+    def lastInsertId(self) -> int:
+        """Get last inserted row id generated by auto increment"""
+        raise Exception("Not implemented")
+
+    def affectedRows(self) -> int:
+        """Get affected rows count"""
+        raise Exception("Not implemented")
+
+    def commit(self) -> None:
+        """Commit DB queries"""
+        raise Exception("Not implemented")
+
+    def rollback(self) -> None:
+        """Rollback DB queries"""
+        raise Exception("Not implemented")

database_wrapper-0.1.28/database_wrapper/db_data_model.py

@@ -0,0 +1,323 @@
+import re
+import json
+import datetime
+import dataclasses
+
+from enum import Enum
+from dataclasses import dataclass, field, asdict
+
+from decimal import Decimal
+from typing import Any
+
+from psycopg import sql
+
+
+@dataclass
+class DBDataModel(object):
+    """
+    Base class for all database models.
+
+    Attributes:
+    - schemaName (str): The name of the schema in the database.
+    - tableName (str): The name of the table in the database.
+    - tableAlias (str): The alias of the table in the database.
+    - idKey (str): The name of the primary key column in the database.
+    - idValue (Any): The value of the primary key for the current instance.
+    - id (int): The primary key value for the current instance.
+
+    Methods:
+    - __post_init__(): Initializes the instance after it has been created.
+    - __repr__(): Returns a string representation of the instance.
+    - __str__(): Returns a JSON string representation of the instance.
+    - toDict(): Returns a dictionary representation of the instance.
+    - toFormattedDict(): Returns a formatted dictionary representation of the instance.
+    - toJsonSchema(): Returns a JSON schema for the instance.
+    - jsonEncoder(obj: Any): Encodes the given object as JSON.
+    - toJsonString(pretty: bool = False): Returns a JSON string representation of the instance.
+    - strToDatetime(value: Any): Converts a string to a datetime object.
+    - strToBool(value: Any): Converts a string to a boolean value.
+    - strToInt(value: Any): Converts a string to an integer value.
+    - validate(): Validates the instance.
+    """
+
+    ######################
+    ### Default fields ###
+    ######################
+
+    @property
+    def schemaName(self) -> str | None:
+        return None
+
+    @property
+    def tableName(self) -> str:
+        raise NotImplementedError("`tableName` property is not implemented")
+
+    @property
+    def tableAlias(self) -> str | None:
+        return None
+
+    @property
+    def idKey(self) -> str:
+        return "id"
+
+    @property
+    def idValue(self) -> Any:
+        return getattr(self, self.idKey, None)
+
+    # Id should be readonly by default and should be always present if record exists
+    id: int = field(
+        default=0,
+        metadata={
+            "db_field": ("id", "bigint"),
+            "store": False,
+            "update": False,
+        },
+    )
+    """id is readonly by default"""
+
+    # Raw data
+    raw_data: dict[str, Any] = field(
+        default_factory=dict,
+        metadata={
+            "db_field": ("raw_data", "jsonb"),
+            "store": False,
+            "update": False,
+        },
+    )
+    """This is for storing temporary raw data"""
+
+    ##########################
+    ### Conversion methods ###
+    ##########################
+
+    def fillDataFromDict(self, kwargs: dict[str, Any]):
+        fieldNames = set([f.name for f in dataclasses.fields(self)])
+        for key in kwargs:
+            if key in fieldNames:
+                setattr(self, key, kwargs[key])
+
+        self.__post_init__()
+
+    # Init data
+    def __post_init__(self):
+        for field_name, field_obj in self.__dataclass_fields__.items():
+            metadata = field_obj.metadata
+            encode = metadata.get("encode", None)
+            if encode is not None:
+                setattr(self, field_name, encode(getattr(self, field_name)))
+
+    # String - representation
+    def __repr__(self) -> str:
+        return "<%s %s>" % (self.__class__.__name__, self.__dict__)
+
+    def __str__(self) -> str:
+        return self.toJsonString()
+
+    # Dict
+    def toDict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def toFormattedDict(self) -> dict[str, Any]:
+        return self.toDict()
+
+    # JSON
+    def toJsonSchema(self) -> dict[str, Any]:
+        schema: dict[str, Any] = {
+            "type": "object",
+            "properties": {
+                "id": {"type": "number"},
+            },
+        }
+        for field_name, field_obj in self.__dataclass_fields__.items():
+            metadata = field_obj.metadata
+            assert (
+                "db_field" in metadata
+                and isinstance(metadata["db_field"], tuple)
+                and len(metadata["db_field"]) == 2
+            ), f"db_field metadata is not set for {field_name}"
+            fieldType: str = metadata["db_field"][1]
+            schema["properties"][field_name] = {"type": fieldType}
+
+        return schema
+
+    def jsonEncoder(self, obj: Any) -> Any:
+        if isinstance(obj, Decimal):
+            return float(obj)
+
+        if isinstance(obj, datetime.date) or isinstance(obj, datetime.datetime):
+            return obj.strftime("%Y-%m-%dT%H:%M:%S")
+
+        if isinstance(obj, Enum):
+            return obj.value
+
+        if isinstance(obj, int) or isinstance(obj, float) or isinstance(obj, str):
+            return obj
+
+        return str(obj)
+
+    def toJsonString(self, pretty: bool = False) -> str:
+        if pretty:
+            return json.dumps(
+                self.toDict(),
+                ensure_ascii=False,
+                sort_keys=True,
+                indent=4,
+                separators=(",", ": "),
+                default=self.jsonEncoder,
+            )
+
+        return json.dumps(self.toDict(), default=self.jsonEncoder)
+
+    #######################
+    ### Helper methods ####
+    #######################
+
+    @staticmethod
+    def strToDatetime(value: Any) -> datetime.datetime:
+        if isinstance(value, datetime.datetime):
+            return value
+
+        if value and isinstance(value, str):
+            pattern = r"^\d+(\.\d+)?$"
+            if re.match(pattern, value):
+                return datetime.datetime.fromtimestamp(float(value))
+
+            return datetime.datetime.fromisoformat(value)
+
+        return datetime.datetime.now(datetime.UTC)
+
+    @staticmethod
+    def strToBool(value: Any) -> bool:
+        if isinstance(value, bool):
+            return value
+
+        if value:
+            if isinstance(value, str):
+                return value.lower() in ("true", "1")
+
+            if isinstance(value, int):
+                return value == 1
+
+        return False
+
+    @staticmethod
+    def strToInt(value: Any) -> int:
+        if isinstance(value, int):
+            return value
+
+        if value and isinstance(value, str):
+            return int(value)
+
+        return 0
+
+    def validate(self) -> bool:
+        raise NotImplementedError("`validate` is not implemented")
+
+    ########################
+    ### Database methods ###
+    ########################
+
+    def queryBase(self) -> sql.SQL | sql.Composed | str | None:
+        """
+        Base query for all queries
+        """
+        return None
+
+    def storeData(self) -> dict[str, Any] | None:
+        """
+        Store data to database
+        """
+        storeData: dict[str, Any] = {}
+        for field_name, field_obj in self.__dataclass_fields__.items():
+            metadata = field_obj.metadata
+            if "store" in metadata and metadata["store"] == True:
+                storeData[field_name] = getattr(self, field_name)
+
+                if "decode" in metadata and metadata["decode"] is not None:
+                    storeData[field_name] = metadata["decode"](storeData[field_name])
+
+        return storeData
+
+    def updateData(self) -> dict[str, Any] | None:
+        """
+        Update data to database
+        """
+
+        updateData: dict[str, Any] = {}
+        for field_name, field_obj in self.__dataclass_fields__.items():
+            metadata = field_obj.metadata
+            if "update" in metadata and metadata["update"] == True:
+                updateData[field_name] = getattr(self, field_name)
+
+                if "decode" in metadata and metadata["decode"] is not None:
+                    updateData[field_name] = metadata["decode"](updateData[field_name])
+
+        return updateData
+
+
+@dataclass
+class DBDefaultsDataModel(DBDataModel):
+    """
+    This class includes default fields for all database models.
+
+    Attributes:
+    - created_at (datetime.datetime): The timestamp of when the instance was created.
+    - updated_at (datetime.datetime): The timestamp of when the instance was last updated.
+    - enabled (bool): Whether the instance is enabled or not.
+    - deleted (bool): Whether the instance is deleted or not.
+    """
+
+    ######################
+    ### Default fields ###
+    ######################
+
+    created_at: datetime.datetime = field(
+        default_factory=datetime.datetime.now,
+        metadata={
+            "db_field": ("created_at", "timestamptz"),
+            "store": True,
+            "update": False,
+            "encode": lambda value: DBDataModel.strToDatetime(value),  # type: ignore
+            "decode": lambda x: x.isoformat(),  # type: ignore
+        },
+    )
+    """created_at is readonly by default and should be present in all tables"""
+
+    updated_at: datetime.datetime = field(
+        default_factory=datetime.datetime.now,
+        metadata={
+            "db_field": ("updated_at", "timestamptz"),
+            "store": True,
+            "update": True,
+            "encode": lambda value: DBDataModel.strToDatetime(value),  # type: ignore
+            "decode": lambda x: x.isoformat(),  # type: ignore
+        },
+    )
+    """updated_at is readonly by default and should be present in all tables"""
+
+    enabled: bool = field(
+        default=True,
+        metadata={
+            "db_field": ("enabled", "boolean"),
+            "store": False,
+            "update": False,
+        },
+    )
+    deleted: bool = field(
+        default=False,
+        metadata={
+            "db_field": ("deleted", "boolean"),
+            "store": False,
+            "update": False,
+        },
+    )
+
+    def updateData(self) -> dict[str, Any] | None:
+        """
+        Update data to database
+        """
+
+        # Update updated_at
+        self.updated_at = datetime.datetime.now(datetime.UTC)
+
+        return super().updateData()