Ensure that the value of __module__ for all clases is left untouched in

order to make inspect.getsource() behave as expected; use a metaclass
instead to change the repr() of the class.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -99,6 +99,9 @@ Common Changes
     :ref:`DbObject <dbobjecttype>` which is not actually a collection.
 #)  API documentation is now generated from the source code.
 #)  The test suite now uses `pytest <https://docs.pytest.org/>`__.
+#)  Internal change: the value of ``__module__`` for all classes is now left
+    untouched to avoid issues with ``inspect.getsource()`` but the
+    ``__repr__()`` now consistently shows the module as ``oracledb``.
 #)  Internal change: `typing_extensions <https://pypi.org/project/
     typing-extensions/>`__ is now a dependency.
 

src/oracledb/__init__.py

@@ -1211,6 +1211,7 @@ class JsonId(bytes):
     fetch_info,  # noqa
     future,  # noqa
     lob,  # noqa
+    pipeline,  # noqa
     pool,  # noqa
     pool_params,  # noqa
     sparse_vector,  # noqa

src/oracledb/aq.py

@@ -34,10 +34,11 @@
 from . import connection as connection_module
 from typing import Any, Union
 from . import errors
+from .base import BaseMetaClass
 from .dbobject import DbObject, DbObjectType
 
 
-class BaseQueue:
+class BaseQueue(metaclass=BaseMetaClass):
     @classmethod
     def _from_impl(cls, connection, impl):
         queue = cls.__new__(cls)
@@ -267,7 +268,7 @@ async def enqone(self, message: "MessageProperties") -> None:
         await self._impl.enq_one(message._impl)
 
 
-class DeqOptions:
+class DeqOptions(metaclass=BaseMetaClass):
     @classmethod
     def _from_impl(cls, impl):
         options = cls.__new__(cls)
@@ -420,7 +421,7 @@ def wait(self, value: int) -> None:
         self._impl.set_wait(value)
 
 
-class EnqOptions:
+class EnqOptions(metaclass=BaseMetaClass):
     @classmethod
     def _from_impl(cls, impl):
         options = cls.__new__(cls)
@@ -471,7 +472,7 @@ def visibility(self, value: int) -> None:
         self._impl.set_visibility(value)
 
 
-class MessageProperties:
+class MessageProperties(metaclass=BaseMetaClass):
     _recipients = []
 
     @classmethod

src/oracledb/arrow_array.py

@@ -30,11 +30,12 @@
 # -----------------------------------------------------------------------------
 
 from .arrow_impl import ArrowArrayImpl
+from .base import BaseMetaClass
 
 from . import errors
 
 
-class ArrowArray:
+class ArrowArray(metaclass=BaseMetaClass):
     _impl = None
 
     def __init__(self):

src/oracledb/base.py

@@ -0,0 +1,48 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025, Oracle and/or its affiliates.
+#
+# This software is dual-licensed to you under the Universal Permissive License
+# (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+# 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+# either license.
+#
+# If you elect to accept the software under the Apache License, Version 2.0,
+# the following applies:
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# base.py
+#
+# Contains base classes and methods that have no internal dependencies.
+# -----------------------------------------------------------------------------
+
+from . import __name__ as MODULE_NAME
+
+
+# metaclass used by all oracledb classes; currently this only ensures that when
+# the class is displayed it only shows the overall module name instead of any
+# subpackage names
+class BaseMetaClass(type):
+
+    def __new__(cls, name, bases, attrs):
+        module_name = attrs["__module__"]
+        qual_name = attrs["__qualname__"]
+        if module_name.startswith(MODULE_NAME):
+            module_name = MODULE_NAME
+        attrs["_public_name"] = f"{module_name}.{qual_name}"
+        return super().__new__(cls, name, bases, attrs)
+
+    def __repr__(cls):
+        return f"<class '{cls._public_name}'>"

src/oracledb/base_impl.pxd

@@ -654,7 +654,7 @@ cdef class PoolParamsImpl(ConnectParamsImpl):
         public uint32_t min
         public uint32_t max
         public uint32_t increment
-        public type connectiontype
+        public object connectiontype
         public uint32_t getmode
         public bint homogeneous
         public uint32_t timeout

src/oracledb/connect_params.py

@@ -39,16 +39,16 @@
 
 import oracledb
 
+from .base import BaseMetaClass
 from . import base_impl, utils
 
 
-class ConnectParams:
+class ConnectParams(metaclass=BaseMetaClass):
     """
     Contains all parameters used for establishing a connection to the
     database.
     """
 
-    __module__ = oracledb.__name__
     __slots__ = ["_impl"]
     _impl_class = base_impl.ConnectParamsImpl
 

src/oracledb/connection.py

@@ -40,12 +40,11 @@
 
 import oracledb
 
-from . import __name__ as MODULE_NAME
-
 from . import base_impl, driver_mode, errors, thick_impl, thin_impl
 from . import pool as pool_module
 from .aq import AsyncQueue, Queue, MessageProperties
 from .arrow_impl import ArrowSchemaImpl
+from .base import BaseMetaClass
 from .base_impl import DB_TYPE_BLOB, DB_TYPE_CLOB, DB_TYPE_NCLOB, DbType
 from .connect_params import ConnectParams
 from .cursor import AsyncCursor, Cursor
@@ -63,16 +62,14 @@
 )
 
 
-class BaseConnection:
-    __module__ = MODULE_NAME
+class BaseConnection(metaclass=BaseMetaClass):
     _impl = None
 
     def __init__(self):
         self._version = None
 
     def __repr__(self):
-        typ = self.__class__
-        cls_name = f"{typ.__module__}.{typ.__qualname__}"
+        cls_name = self.__class__._public_name
         if self._impl is None:
             return f"<{cls_name} disconnected>"
         elif self.username is None:
@@ -841,7 +838,6 @@ def xid(
 
 
 class Connection(BaseConnection):
-    __module__ = MODULE_NAME
 
     def __init__(
         self,
@@ -2069,7 +2065,6 @@ def connect(
 
 
 class AsyncConnection(BaseConnection):
-    __module__ = MODULE_NAME
 
     def __init__(
         self,

src/oracledb/cursor.py

@@ -31,17 +31,17 @@
 
 from typing import Any, Union, Callable, Optional
 
-from . import __name__ as MODULE_NAME
 from . import connection as connection_module
 from . import errors
 from . import utils
-from .fetch_info import FetchInfo
-from .var import Var
+from .base import BaseMetaClass
 from .base_impl import DbType, DB_TYPE_OBJECT
 from .dbobject import DbObjectType
+from .fetch_info import FetchInfo
+from .var import Var
 
 
-class BaseCursor:
+class BaseCursor(metaclass=BaseMetaClass):
     _impl = None
 
     def __init__(
@@ -73,8 +73,7 @@ def __exit__(self, exc_type, exc_value, exc_tb):
         self._impl = None
 
     def __repr__(self):
-        typ = self.__class__
-        cls_name = f"{typ.__module__}.{typ.__qualname__}"
+        cls_name = self.__class__._public_name
         return f"<{cls_name} on {self.connection!r}>"
 
     def _call(
@@ -655,7 +654,6 @@ def warning(self) -> Union[errors._Error, None]:
 
 
 class Cursor(BaseCursor):
-    __module__ = MODULE_NAME
 
     def __iter__(self):
         """
@@ -1040,7 +1038,6 @@ def scroll(self, value: int = 0, mode: str = "relative") -> None:
 
 
 class AsyncCursor(BaseCursor):
-    __module__ = MODULE_NAME
 
     async def __aenter__(self):
         """

src/oracledb/dataframe.py

@@ -31,10 +31,11 @@
 
 from .arrow_array import ArrowArray
 from .arrow_impl import DataFrameImpl
+from .base import BaseMetaClass
 from . import errors
 
 
-class DataFrame:
+class DataFrame(metaclass=BaseMetaClass):
     _impl = None
 
     def __init__(self):