everysk-lib 1.10.2__cp312-cp312-win_amd64.whl

everysk/server/requests.py

@@ -0,0 +1,62 @@
+###############################################################################
+#
+# (C) Copyright 2025 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+__all__ = ['JSONRequest', 'Request']
+
+from starlette.requests import Request as _Request
+
+from everysk.core.compress import decompress
+from everysk.core.log import Logger
+from everysk.core.serialize import loads
+
+
+log = Logger(__name__)
+
+
+###############################################################################
+#   Request Class Implementation
+###############################################################################
+class Request(_Request):
+
+    async def body(self) -> bytes:
+        """
+        Method to return the body of the request.
+        If we receive a request with a Content-Encoding header, we decompress the body.
+        """
+        # If self._body is set then body was already read.
+        if not hasattr(self, '_body'):
+            body = await super().body()
+            # We only decompress the body if it is not empty.
+            if body:
+                content_encoding = self.headers.get('Content-Encoding', '').lower()
+                if 'gzip' in content_encoding:
+                    try:
+                        body = decompress(body, protocol='gzip', serialize=None )
+                    except Exception: # pylint: disable=broad-except
+                        log.error('Error decompressing the request body.', extra={'labels': {'body': body}})
+
+            self._body = body # pylint: disable=attribute-defined-outside-init
+        return self._body
+
+
+###############################################################################
+#   JSONRequest Class Implementation
+###############################################################################
+class JSONRequest(Request):
+
+    async def json(self):
+        """
+        Method to return the JSON content of the request body.
+        It uses the loads function from the core.serialize module to parse the body.
+        """
+        if not hasattr(self, '_json'):
+            body = await self.body()
+            self._json = loads(body, protocol='json', use_undefined=True) # pylint: disable=attribute-defined-outside-init
+
+        return self._json

everysk/server/responses.py

@@ -0,0 +1,119 @@
+###############################################################################
+#
+# (C) Copyright 2025 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+__all__ = [
+    'FileResponse',
+    'HTMLResponse',
+    'JSONResponse',
+    'PlainTextResponse',
+    'RedirectResponse',
+    'Response',
+    'StreamingResponse',
+]
+
+from typing import Any, Literal
+
+from starlette.background import BackgroundTask
+from starlette.responses import (
+    FileResponse,
+    HTMLResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    Response,
+    StreamingResponse,
+)
+
+from everysk.core.object import BaseObject
+from everysk.core.serialize import dumps
+
+
+###############################################################################
+#   JSONResponse Class Implementation
+###############################################################################
+class DumpsParams(BaseObject):
+    add_class_path: bool = True
+    date_format: str | None = None
+    datetime_format: str | None = None
+    indent: int | None = None
+    protocol: Literal['json', 'orjson'] = 'json'
+    return_type: Literal['bytes', 'str'] = 'bytes'
+    separators: tuple[str] = (',', ':')
+    sort_keys: bool = False
+    use_undefined: bool = True
+    decode_bytes: bool = True
+
+    def __init__(
+        self,
+        add_class_path: bool = True,
+        date_format: str | None = None,
+        datetime_format: str | None = None,
+        indent: int | None = None,
+        protocol: Literal['json', 'orjson'] = 'json',
+        return_type: Literal['bytes', 'str'] = 'bytes',
+        separators: tuple[str] = (',', ':'),
+        sort_keys: bool = False,
+        use_undefined: bool = True,
+        decode_bytes: bool = True,
+        **kwargs,
+    ):
+        super().__init__(
+            add_class_path=add_class_path,
+            date_format=date_format,
+            datetime_format=datetime_format,
+            indent=indent,
+            protocol=protocol,
+            return_type=return_type,
+            separators=separators,
+            sort_keys=sort_keys,
+            use_undefined=use_undefined,
+            decode_bytes=decode_bytes,
+            **kwargs,
+        )
+
+    def to_dict(self):  # pylint: disable=arguments-differ
+        dct = super().to_dict(add_class_path=True, recursion=True)
+        # we remove all private keys because we don't want them in the serialized output
+        return {key: value for key, value in dct.items() if not key.startswith('_')}
+
+
+class JSONResponse(Response):
+    ## Public attributes
+    media_type = 'application/json; charset=UTF-8'
+    serialize_dumps_params: DumpsParams = DumpsParams()
+
+    def __init__(
+        self,
+        content: Any = None,
+        status_code: int = 200,
+        headers: dict[str, str] | None = None,
+        media_type: str | None = None,
+        background: BackgroundTask | None = None,
+        serialize_dumps_params: DumpsParams | None = None
+    ) -> None:
+        # Must be before the render method that runs inside init
+        if serialize_dumps_params:
+            self.serialize_dumps_params = serialize_dumps_params
+
+        super().__init__(
+            content=content,
+            status_code=status_code,
+            headers=headers,
+            media_type=media_type,
+            background=background
+        )
+
+    def render(self, content: Any) -> bytes:
+        """
+        Serialize the content to JSON format using the dumps function from the core.serialize module.
+
+        Args:
+            content (Any): The content to be serialized.
+        """
+        # with indent=None and separators=(",", ":"), the JSON will be minified
+        return dumps(content, **self.serialize_dumps_params.to_dict())

everysk/server/routing.py

@@ -0,0 +1,64 @@
+###############################################################################
+#
+# (C) Copyright 2025 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+__all__ = ['Route', 'RouteLazy']
+
+from starlette.routing import Route, compile_path
+from starlette.types import Receive, Scope, Send
+
+from everysk.core.string import import_from_string
+
+
+###############################################################################
+#   RouteLazy Class Implementation
+###############################################################################
+class RouteLazy(Route):
+    app: callable = None
+    endpoint: str = None
+    include_in_schema: bool = True
+    methods: set = None
+    name: str = None
+    path: str = None
+
+    def __init__(self, path: str, endpoint: str, name: str | None = None) -> None: # pylint: disable=super-init-not-called
+        """
+        Route class that will lazy load the endpoint class.
+
+        Args:
+            path (str): The path of the route always start with '/'.
+            endpoint (str): Full doted class path of the endpoint.
+            name (str | None, optional): A name for this endpoint. Defaults to the same value in endpoint.
+
+        Raises:
+            ValueError: If the path doesn't start with '/'.
+        """
+        if not path.startswith('/'):
+            raise ValueError("Routed paths must start with '/'")
+
+        self.path = path
+        self.endpoint = endpoint
+        self.name = endpoint if name is None else name
+        self.path_regex, self.path_format, self.param_convertors = compile_path(path)
+
+    async def handle(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """
+        Method to handle the incoming request and execute it.
+        If the endpoint is a string, it will import the endpoint class and execute it.
+
+        Args:
+            scope (Scope): ASGI scope dictionary.
+            receive (Receive): ASGI receive data.
+            send (Send): ASGI send data.
+        """
+        if isinstance(self.endpoint, str):
+            self.app = import_from_string(self.endpoint)
+        else:
+            self.app = self.endpoint
+
+        await self.app(scope, receive, send)

everysk/server/settings.py

@@ -0,0 +1,36 @@
+###############################################################################
+#
+# (C) Copyright 2025 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+
+EVERYSK_SERVER_DEBUG: bool = False
+
+# Used to check access on JSONEndpoints
+EVERYSK_SERVER_REST_KEY_NAME: str = 'X-Rest-Key'
+EVERYSK_SERVER_REST_KEY_VALUE: str = '12345'
+
+# Used by the GZipMiddleware to compress the response
+EVERYSK_SERVER_GZIP_MINIMUM_SIZE: int = 1024
+EVERYSK_SERVER_GZIP_COMPRESS_LEVEL: int = 9
+
+# The codes that will be logged by the Logger
+EVERYSK_SERVER_CODES_LOG: tuple = (500,)
+
+# URL to use in the redirect response
+EVERYSK_SERVER_REDIRECT_URL: str = None
+
+# To enable GZipMiddleware
+EVERYSK_SERVER_GZIP_MIDDLEWARE_ENABLED: bool = True
+
+# To enable SecurityMiddleware
+EVERYSK_SERVER_SECURITY_MIDDLEWARE_ENABLED: bool = True
+
+# Size of the error message to log in the HTTP error response
+# If the error message is larger than this size, it will be truncated
+# and the full message will be in the extra context of the log
+EVERYSK_SERVER_HTTP_ERROR_MESSAGE_SIZE: int = 256

everysk/server/tests.py

@@ -0,0 +1,36 @@
+###############################################################################
+#
+# (C) Copyright 2025 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+# pylint: disable=unused-import
+
+try:
+    from everysk.server._tests.applications import ServerApplication as EveryskLibServerApplication
+
+    from everysk.server._tests.endpoints import (
+        BaseEndpointTestCase as EveryskLibBaseEndpointTestCase,
+        BaseEndpointTestCaseAsync as EveryskLibBaseEndpointTestCaseAsync,
+        DumpsParamsTestCase as EveryskLibDumpsParamsTestCase,
+        HealthCheckEndpointTestCaseAsync as EveryskLibHealthCheckEndpointTestCaseAsync,
+        JSONEndpointTestCase as EveryskLibJSONEndpointTestCase,
+        JSONEndpointTestCaseAsync as EveryskLibJSONEndpointTestCaseAsync,
+        NotAllowedMethodsTestCaseAsync as EveryskLibNotAllowedMethodsTestCaseAsync,
+        RedirectEndpointTestCase as EveryskLibRedirectEndpointTestCase,
+        RedirectEndpointTestCaseAsync as EveryskLibRedirectEndpointTestCaseAsync,
+    )
+
+    from everysk.server._tests.middlewares import (
+        GZipMiddlewareTestCaseAsync as EveryskLibGZipMiddlewareTestCaseAsync,
+        SecurityHeadersMiddlewareTestCaseAsync as EveryskLibSecurityHeadersMiddlewareTestCaseAsync,
+        UpdateMiddlewaresTestCase as EveryskLibUpdateMiddlewaresTestCase
+    )
+    from everysk.server._tests.routing import RouteLazyTestCaseAsync as EveryskLibRouteLazyTestCaseAsync
+except ModuleNotFoundError as error:
+    # This will prevent running these tests if requests is not installed
+    if not error.args[0].startswith("No module named 'starlette'"):
+        raise error

everysk/settings.py

@@ -0,0 +1,98 @@
+###############################################################################
+#
+# (C) Copyright 2023 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+import tempfile
+
+from everysk.core.fields import BoolField, ChoiceField, DictField, FloatField, IntField, ListField, StrField
+
+## Project settings
+DEBUG = BoolField(default=True)
+
+# PROD | DEV | LOCAL
+PROFILE = ChoiceField(default='DEV', choices=('PROD', 'DEV', 'LOCAL'))
+
+## Redis
+REDIS_HOST = StrField(default='0.0.0.0')  # noqa: S104
+REDIS_PORT = IntField(default=6379)
+REDIS_NAMESPACE = StrField()
+REDIS_HEALTH_CHECK_INTERVAL = IntField(default=30)  # seconds
+REDIS_RETRY_ATTEMPTS = IntField(default=3)
+REDIS_RETRY_BACKOFF_MIN = FloatField(default=0.05)  # Minimum backoff between each retry in seconds
+REDIS_RETRY_BACKOFF_MAX = FloatField(default=0.5)  # Maximum backoff between each retry in seconds
+REDIS_RETRY_EXTRA_ERROR_LIST = ListField()  # Added more errors to retry
+REDIS_SOCKET_KEEPALIVE = BoolField(default=True)
+REDIS_SOCKET_TIMEOUT = IntField(default=120)  # seconds
+REDIS_SHOW_LOGS = BoolField(default=False)
+
+## Everysk SIGNING key is used to verify the integrity of the data
+EVERYSK_SIGNING_KEY = StrField(default=None)
+
+## Google Cloud
+EVERYSK_GOOGLE_CLOUD_LOCATION = StrField(default='us-central1')
+EVERYSK_GOOGLE_CLOUD_PROJECT = StrField()
+
+## Logger settings
+# This is the default app server to infer the headers and payload
+LOGGING_APP_SERVER = StrField(default='flask')
+
+# This is the default string to create the Google Cloud Trace ID
+LOGGING_GOOGLE_CLOUD_TRACE_ID = StrField(default='projects/{EVERYSK_GOOGLE_CLOUD_PROJECT}/traces')
+
+# This is the default Formatter for the logs
+LOGGING_JSON = BoolField(default=False)
+
+## Slack URL to send messages
+SLACK_URL = StrField()
+
+## Activate/deactivate HTTP Log for every request/response
+EVERYSK_HTTP_LOG_RESPONSE = BoolField(default=False)
+
+## Activate/deactivate HTTP Log for retry connections
+EVERYSK_HTTP_LOG_RETRY = BoolField(default=False)
+
+## List of HTTP Success status codes that do not raise HTTPError
+HTTP_SUCCESS_STATUS_CODES = ListField(default=[200, 201, 202, 204, 303], readonly=True)
+
+## HTTP default headers used to send requests
+HTTP_DEFAULT_HEADERS = DictField(
+    default={
+        'Accept-Encoding': 'gzip',
+        'Accept-Language': 'en-US, en;q=0.9, pt-BR;q=0.8, pt;q=0.7',
+        'Cache-control': 'no-cache',
+        'Content-Type': 'text/html; charset=UTF-8',
+        'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36',  # noqa: E501
+    },
+    readonly=True,
+)
+HTTP_DEFAULT_TIMEOUT = IntField(default=30)
+HTTP_DEFAULT_SSL_VERIFY = BoolField(default=True)
+HTTP_DEFAULT_RETRY_LIMIT = IntField(default=5)
+HTTP_DEFAULT_RETRY_END_SECONDS = IntField(default=30)
+HTTP_DEFAULT_RETRY_START_SECONDS = IntField(default=5)
+
+## Serialization settings
+SERIALIZE_CONVERT_METHOD_NAME = StrField(default='to_native')
+SERIALIZE_DATE_KEY = StrField(default='__date__')
+SERIALIZE_DATETIME_KEY = StrField('__datetime__')
+SERIALIZE_UNDEFINED_KEY = StrField('__undefined__')
+SERIALIZE_USE_UNDEFINED = BoolField(default=False)
+
+## Activate/deactivate the use of the verify flag on HTTP requests.
+# By default the value is Undefined and the value comes from the self._config.ssl_verify
+# attribute in the HttpConnection class, if it is defined we use it.
+HTTP_REQUESTS_VERIFY = BoolField(default=Undefined)
+
+# Activate/deactivate the use of random user agents on HTTP requests
+HTTP_USE_RANDOM_USER_AGENT = BoolField(default=False)
+
+# Default directory to use the known_hosts file and other SFTP configurations
+EVERYSK_SFTP_DIR = StrField(default=f'{tempfile.gettempdir()}/sftp')
+
+# Enable to show retry logs
+RETRY_SHOW_LOGS = BoolField(default=False)

everysk/sql/__init__.py

@@ -0,0 +1,9 @@
+###############################################################################
+#
+# (C) Copyright 2025 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################

everysk/sql/connection.py

@@ -0,0 +1,232 @@
+###############################################################################
+#
+# (C) Copyright 2025 EVERYSK TECHNOLOGIES
+#
+# This is an unpublished work containing confidential and proprietary
+# information of EVERYSK TECHNOLOGIES. Disclosure, use, or reproduction
+# without authorization of EVERYSK TECHNOLOGIES is prohibited.
+#
+###############################################################################
+from collections.abc import Callable
+from contextvars import ContextVar, Token
+from os import getpid
+from types import TracebackType
+from typing import Literal
+
+from psycopg import Connection, OperationalError
+from psycopg_pool import ConnectionPool as _ConnectionPool
+
+from everysk.config import settings
+from everysk.core.log import Logger
+from everysk.core.retry import retry
+from everysk.sql.row_factory import cls_row, dict_row
+
+_CONNECTIONS: dict[str, 'ConnectionPool'] = {}
+log = Logger('everysk-lib-sql-query')
+
+
+def _log(message: str, extra: dict | None = None) -> None:
+    if settings.POSTGRESQL_LOG_QUERIES:
+        log.debug(message, extra=extra)
+
+
+class ConnectionPool(_ConnectionPool):
+    def __del__(self) -> None:
+        # To close the connections when the pool is deleted
+        # https://everysk.atlassian.net/browse/COD-8885
+        try:
+            return super().__del__()
+        except RuntimeError:
+            # The connection is already closed or discarded because we cannot join the current thread
+            # RuntimeError: cannot join current thread
+            pass
+
+        return None
+
+
+class Transaction:
+    """
+    Context manager for PostgreSQL transactions.
+
+    Usage:
+
+        >>> from everysk.sql.connection import Transaction, execute
+        >>> with Transaction():
+        ...     result = execute("SELECT * FROM my_table WHERE id = %s", params={"id": 1})
+        ...     # Perform other database operations within the transaction
+
+    """
+
+    ## Private attributes
+    _connection: Connection
+    _pool: ConnectionPool
+    _token: Token
+
+    ## Public attributes
+    connection: ContextVar[Connection] = ContextVar('postgresql-psqlpy-transaction', default=None)
+
+    def __init__(self, dsn: str | None = None) -> None:
+        self._pool: ConnectionPool = get_pool(dsn=dsn)
+
+    def __enter__(self) -> None:
+        self._connection = self._pool.getconn()
+        self._token = self.connection.set(self._connection)
+
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
+    ) -> None:
+        if exc_type is None:
+            self._connection.commit()
+        else:
+            self._connection.rollback()
+
+        self.connection.reset(self._token)
+        # Return the connection to the pool
+        self._pool.putconn(self._connection)
+
+        return False
+
+
+def make_connection_dsn(
+    host: str | None = None,
+    port: int | None = None,
+    user: str | None = None,
+    password: str | None = None,
+    database: str | None = None,
+    sslmode: str | None = None,
+) -> str:
+    """
+    Create a PostgreSQL connection DSN from settings.
+    Supports both TCP and Unix socket connections.
+    If parameters are provided, they override the settings.
+
+    Args:
+        host (str | None): The database host. If None, uses the setting.
+        port (int | None): The database port. If None, uses the setting.
+        user (str | None): The database user. If None, uses the setting.
+        password (str | None): The database password. If None, uses the setting.
+        database (str | None): The database name. If None, uses the setting.
+        sslmode (str | None): The SSL mode for connection. If None, uses the setting if defined.
+    """
+    sslmode: str | None = sslmode or settings.POSTGRESQL_CONNECTION_SSLMODE
+    options: dict[str, str | int] = {
+        'host': host or settings.POSTGRESQL_CONNECTION_HOST,
+        'port': port or settings.POSTGRESQL_CONNECTION_PORT,
+        'user': user or settings.POSTGRESQL_CONNECTION_USER,
+        'password': password or settings.POSTGRESQL_CONNECTION_PASSWORD,
+        'database': database or settings.POSTGRESQL_CONNECTION_DATABASE,
+        'sslmode': f'?sslmode={sslmode}' if sslmode else '',
+    }
+
+    # Handle Unix socket connections
+    if options['host'].startswith('/'):
+        return 'postgresql:///{database}?host={host}&user={user}&password={password}'.format(**options)
+
+    # Standard TCP connection
+    return 'postgresql://{user}:{password}@{host}:{port}/{database}{sslmode}'.format(**options)
+
+
+def get_pool(dsn: str | None = None, **kwargs) -> ConnectionPool:
+    """
+    Retrieve a database connection pool for the given DSN.
+
+    If no DSN is provided, a default DSN is generated. The connection pool is cached
+    based on the process ID and DSN hash to ensure reuse within the same process.
+    If a pool for the given key does not exist, a new one is created with the specified
+    maximum size and SSL mode.
+
+    Importantly, this is necessary because connections cannot be shared between processes.
+
+    Args:
+        dsn (str | None): The Data Source Name for the database connection. If None, a default DSN is used.
+        **kwargs: Additional keyword arguments to configure the connection pool.
+
+    Returns:
+        ConnectionPool: The connection pool associated with the given DSN.
+    """
+    dsn = dsn or make_connection_dsn()
+    # https://www.psycopg.org/psycopg3/docs/api/pool.html
+    kwargs['check'] = ConnectionPool.check_connection
+    kwargs['min_size'] = kwargs.get('min_size', settings.POSTGRESQL_POOL_MIN_SIZE)
+    kwargs['max_size'] = kwargs.get('max_size', settings.POSTGRESQL_POOL_MAX_SIZE)
+    kwargs['max_idle'] = kwargs.get('max_idle', settings.POSTGRESQL_POOL_MAX_IDLE)
+    kwargs['max_lifetime'] = kwargs.get('max_lifetime', settings.POSTGRESQL_POOL_MAX_LIFETIME)
+    kwargs['max_waiting'] = kwargs.get('max_waiting', settings.POSTGRESQL_POOL_MAX_WAITING)
+    kwargs['reconnect_timeout'] = kwargs.get('reconnect_timeout', settings.POSTGRESQL_POOL_RECONNECT_TIMEOUT)
+    kwargs['timeout'] = kwargs.get('timeout', settings.POSTGRESQL_POOL_TIMEOUT)
+    kwargs['open'] = kwargs.get('open', settings.POSTGRESQL_POOL_OPEN)
+
+    key = f'{getpid()}:{hash(dsn)}'
+    if key not in _CONNECTIONS:
+        _CONNECTIONS[key] = ConnectionPool(conninfo=dsn, **kwargs)
+
+    return _CONNECTIONS[key]
+
+
+def execute(
+    query: str,
+    params: dict | None = None,
+    return_type: Literal['dict', 'list'] = 'list',
+    dsn: str | None = None,
+    cls: type | None = None,
+    loads: Callable | None = None,
+) -> list[dict] | list[object] | dict | None:
+    """
+    Execute a query and return the results.
+    If return_type is a class, return a list of instances of that class.
+    If return_type is a string, return a dictionary keyed by that string.
+    Otherwise, return a list of dictionaries.
+
+    Args:
+        query (str): The SQL query to execute.
+        params (dict | None, optional): The parameters to include in the query. Defaults to None.
+        return_type (Literal['dict', 'list'], optional): The type of return value. Defaults to 'list'.
+        dsn (str | None, optional): The DSN to use for the connection. Defaults to None.
+        cls (type | None, optional): The class to map the results to. Defaults to None.
+        loads (Callable | None, optional): Optional function to process each value. Defaults to None.
+        retry (int, optional): The current retry count. Defaults to 0.
+    """
+    conn: Connection = Transaction.connection.get()
+    if not conn:
+        pool: ConnectionPool = get_pool(dsn=dsn)
+        conn: Connection = pool.getconn()
+        is_transactional = False
+        log_message = 'PostgreSQL query executed.'
+    else:
+        is_transactional = True
+        log_message = 'PostgreSQL query executed within transaction.'
+
+    _log(log_message, extra={'labels': {'query': query, 'params': params}})
+
+    row_factory = cls_row(cls, loads) if cls else dict_row(loads)
+    # For transactions we let it be controlled externally by the context manager
+    try:
+        with conn.cursor(row_factory=row_factory) as cur:
+            result = retry(cur.execute, {'query': query, 'params': params}, retries=3, exceptions=OperationalError)
+
+            if result.description:
+                result = cur.fetchall()
+            else:
+                result = None
+    except Exception:
+        # On error we need to rollback
+        if not is_transactional:
+            conn.rollback()
+        raise
+
+    else:
+        # Block that only executes if no exception was raised in the try block
+        if not is_transactional:
+            conn.commit()
+
+    finally:
+        # We only return the connection to the pool if we are not in a transaction
+        if not is_transactional:
+            pool.putconn(conn)
+
+    if result and cls and return_type == 'dict':
+        return {row[cls._primary_key]: row for row in result}
+
+    return result