WL#16752: Deprecate class methods to access instance data or to know instance internal state

Change-Id: I4293ddd909ad45c755f25845dbea0171b3139f79

Author: SubCoder1

CHANGES.txt

@@ -11,6 +11,7 @@ Full release notes:
 v9.3.0
 ======
 
+- WL#16752: Deprecate class methods to access instance data or to know instance internal state
 - WL#16327: Remove Cursors Prepared Raw and Named Tuple
 - BUG#37541353: (Contribution) Fix typing annotation of MySQLConnectionAbstract's close function
 - BUG#37453587: Github links in PyPI project's pages do not work

mysql-connector-python/examples/microseconds.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2009, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2009, 2025, Oracle and/or its affiliates.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License, version 2.0, as
@@ -59,10 +59,10 @@
 def main(config):
     output = []
     cnx = mysql.connector.Connect(**config)
-    if cnx.get_server_version() < (5, 6, 4):
+    if cnx.server_version < (5, 6, 4):
         output.append(
             "MySQL {0} does not support fractional precision"
-            " for timestamps.".format(cnx.get_server_info())
+            " for timestamps.".format(cnx.server_info)
         )
         return output
     cursor = cnx.cursor()

mysql-connector-python/examples/mysql_warnings.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2016, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2016, 2025, Oracle and/or its affiliates.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License, version 2.0, as
@@ -52,7 +52,7 @@ def main(config):
     cursor.execute(STMT)
     cursor.fetchall()
 
-    warnings = cursor.fetchwarnings()
+    warnings = cursor.warnings
     if warnings:
         for w in warnings:
             output.append("%d: %s" % (w[1], w[2]))

mysql-connector-python/examples/transaction.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2009, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2009, 2025, Oracle and/or its affiliates.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License, version 2.0, as
@@ -59,7 +59,7 @@ def main(config):
     ) ENGINE=InnoDB"""
     cursor.execute(stmt_create)
 
-    warnings = cursor.fetchwarnings()
+    warnings = cursor.warnings
     if warnings:
         ids = [i for l, i, m in warnings]
         output.append("Oh oh.. we got warnings..")

mysql-connector-python/examples/warnings.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2009, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2009, 2025, Oracle and/or its affiliates.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License, version 2.0, as
@@ -55,7 +55,7 @@ def main(config):
     cursor.execute(STMT)
     cursor.fetchall()
 
-    warnings = cursor.fetchwarnings()
+    warnings = cursor.warnings
     if warnings:
         for w in warnings:
             output.append("%d: %s" % (w[1], w[2]))

mysql-connector-python/lib/mysql/connector/_decorating.py

@@ -49,7 +49,7 @@ def wrapper(
             cnx: "MySQLConnectionAbstract", *args: Any, **kwargs: Any
         ) -> Callable:
             options: int = args[0]
-            if (options & RefreshOption.GRANT) and cnx.get_server_version() >= (
+            if (options & RefreshOption.GRANT) and cnx.server_version >= (
                 9,
                 2,
                 0,
@@ -68,3 +68,44 @@ def wrapper(
         return wrapper
 
     return decorator
+
+
+def handle_read_write_timeout() -> Callable:
+    """
+    Decorator to close the current connection if a read or a write timeout
+    is raised by the method passed via the func parameter.
+    """
+
+    def decorator(cnx_method: Callable) -> Callable:
+        @functools.wraps(cnx_method)
+        def handle_cnx_method(
+            cnx: "MySQLConnectionAbstract", *args: Any, **kwargs: Any
+        ) -> Any:
+            try:
+                return cnx_method(cnx, *args, **kwargs)
+            except Exception as err:
+                if isinstance(err, TimeoutError):
+                    cnx.close()
+                raise err
+
+        return handle_cnx_method
+
+    return decorator
+
+
+def deprecated(reason: str) -> Callable:
+    """Use it to decorate deprecated methods."""
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Callable:
+            warnings.warn(
+                f"Call to deprecated function {func.__name__}. Reason: {reason}",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

mysql-connector-python/lib/mysql/connector/abstracts.py

@@ -75,6 +75,7 @@
 from .constants import (
     CONN_ATTRS_DN,
     DEFAULT_CONFIGURATION,
+    DEPRECATED_METHOD_WARNING,
     MYSQL_DEFAULT_CHARSET_ID_57,
     MYSQL_DEFAULT_CHARSET_ID_80,
     OPENSSL_CS_NAMES,
@@ -107,6 +108,7 @@
         trace,
     )
 
+from ._decorating import deprecated
 from .optionfiles import read_option_files
 from .tls_ciphers import UNACCEPTABLE_TLS_CIPHERSUITES, UNACCEPTABLE_TLS_VERSIONS
 from .types import (
@@ -597,15 +599,15 @@ def config(self, **kwargs: Any) -> None:
         # Configure client flags
         try:
             default = ClientFlag.get_default()
-            self.set_client_flags(config["client_flags"] or default)
+            self.client_flags = config["client_flags"] or default
             del config["client_flags"]
         except KeyError:
             pass  # Missing client_flags-argument is OK
 
         try:
             if config["compress"]:
                 self._compress = True
-                self.set_client_flags([ClientFlag.COMPRESS])
+                self.client_flags = [ClientFlag.COMPRESS]
         except KeyError:
             pass  # Missing compress argument is OK
 
@@ -627,9 +629,9 @@ def config(self, **kwargs: Any) -> None:
             ):
                 raise AttributeError("allow_local_infile_in_path must be a directory")
         if self._allow_local_infile or self._allow_local_infile_in_path:
-            self.set_client_flags([ClientFlag.LOCAL_FILES])
+            self.client_flags = [ClientFlag.LOCAL_FILES]
         else:
-            self.set_client_flags([-ClientFlag.LOCAL_FILES])
+            self.client_flags = [-ClientFlag.LOCAL_FILES]
 
         try:
             if not config["consume_results"]:
@@ -655,7 +657,7 @@ def config(self, **kwargs: Any) -> None:
 
         # Set converter class
         try:
-            self.set_converter_class(config["converter_class"])
+            self.converter_class = config["converter_class"]
         except KeyError:
             pass  # Using default converter class
         except TypeError as err:
@@ -949,6 +951,7 @@ def _check_server_version(server_version: StrOrBytes) -> Tuple[int, ...]:
 
         return version
 
+    @deprecated(DEPRECATED_METHOD_WARNING.format(property_name="server_version"))
     def get_server_version(self) -> Optional[Tuple[int, ...]]:
         """Gets the MySQL version.
 
@@ -958,9 +961,30 @@ def get_server_version(self) -> Optional[Tuple[int, ...]]:
         """
         return self._server_version
 
+    @deprecated(DEPRECATED_METHOD_WARNING.format(property_name="server_info"))
     def get_server_info(self) -> Optional[str]:
         """Gets the original MySQL version information.
 
+        Returns:
+            The original MySQL server as text. If not previously connected, it will
+            return `None`.
+        """
+        return self.server_info
+
+    @property
+    def server_version(self) -> Optional[Tuple[int, ...]]:
+        """Gets the MySQL Server version the connector is connected to.
+
+        Returns:
+            The MySQL server version as a tuple. If not previously connected, it will
+            return `None`.
+        """
+        return self._server_version
+
+    @property
+    def server_info(self) -> Optional[str]:
+        """Gets the original MySQL server version information.
+
         Returns:
             The original MySQL server as text. If not previously connected, it will
             return `None`.
@@ -992,6 +1016,7 @@ def in_transaction(self) -> bool:
             ```
         """
 
+    @deprecated(DEPRECATED_METHOD_WARNING.format(property_name="client_flags"))
     def set_client_flags(self, flags: Union[int, Sequence[int]]) -> int:
         """Sets the client flags.
 
@@ -1020,6 +1045,40 @@ def set_client_flags(self, flags: Union[int, Sequence[int]]) -> int:
             >>> cnx.reconnect()
             ```
         """
+        self.client_flags = flags
+        return self.client_flags
+
+    @property
+    def client_flags(self) -> int:
+        """Gets the client flags of the current session."""
+        return self._client_flags
+
+    @client_flags.setter
+    def client_flags(self, flags: Union[int, Sequence[int]]) -> None:
+        """Sets the client flags.
+
+        The flags-argument can be either an int or a list (or tuple) of
+        ClientFlag-values. If it is an integer, it will set client_flags
+        to flags as is.
+
+        If flags is a sequence, each item in the sequence sets the flag when the
+        value is positive or unsets it when negative (see example below).
+
+        Args:
+            flags: A list (or tuple), each flag will be set or unset when it's negative.
+
+        Raises:
+            ProgrammingError: When the flags argument is not a set or an integer
+                              bigger than 0.
+
+        Examples:
+            ```
+            For example, to unset `LONG_FLAG` and set the `FOUND_ROWS` flags:
+            >>> from mysql.connector.constants import ClientFlag
+            >>> cnx.client_flags = [ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG]
+            >>> cnx.reconnect()
+            ```
+        """
         if isinstance(flags, int) and flags > 0:
             self._client_flags = flags
         elif isinstance(flags, (tuple, list)):
@@ -1029,8 +1088,7 @@ def set_client_flags(self, flags: Union[int, Sequence[int]]) -> int:
                 else:
                     self._client_flags |= flag
         else:
-            raise ProgrammingError("set_client_flags expect integer (>0) or set")
-        return self._client_flags
+            raise ProgrammingError("client_flags setter expect integer (>0) or set")
 
     def shutdown(self) -> NoReturn:
         """Shuts down connection to MySQL Server.
@@ -1129,17 +1187,28 @@ def set_login(
         else:
             self._password = ""
 
+    @deprecated(DEPRECATED_METHOD_WARNING.format(property_name="use_unicode"))
     def set_unicode(self, value: bool = True) -> None:
-        """Toggles unicode mode.
+        """Sets whether we return string fields as unicode or not.
+
+        Args:
+            value: A boolean - default is `True`.
+        """
+        self.use_unicode = value
+
+    @property
+    def use_unicode(self) -> bool:
+        """Gets whether we return string fields as unicode or not."""
+        return self._use_unicode
 
-        Sets whether we return string fields as unicode or not.
+    @use_unicode.setter
+    @abstractmethod
+    def use_unicode(self, value: bool) -> None:
+        """Sets whether we return string fields as unicode or not.
 
         Args:
             value: A boolean - default is `True`.
         """
-        self._use_unicode = value
-        if self.converter:
-            self.converter.set_unicode(value)
 
     @property
     def autocommit(self) -> bool:
@@ -1882,18 +1951,35 @@ def reset_session(
                     cur.execute(f"SET SESSION `{key}` = {value}")
             cur.close()
 
+    @deprecated(DEPRECATED_METHOD_WARNING.format(property_name="converter_class"))
     def set_converter_class(self, convclass: Optional[Type[MySQLConverter]]) -> None:
         """
         Sets the converter class to be used.
 
+        Args:
+            convclass: Should be a class overloading methods and members of
+                       `conversion.MySQLConverter`.
+        """
+        self.converter_class = convclass
+
+    @property
+    def converter_class(self) -> Optional[Type[MySQLConverter]]:
+        """Gets the converter class set for the current session."""
+        return self._converter_class
+
+    @converter_class.setter
+    def converter_class(self, convclass: Optional[Type[MySQLConverter]]) -> None:
+        """
+        Sets the converter class to be used.
+
         Args:
             convclass: Should be a class overloading methods and members of
                        `conversion.MySQLConverter`.
         """
         if convclass and issubclass(convclass, MySQLConverterBase):
             charset_name = self._character_set.get_info(self._charset_id)[0]
             self._converter_class = convclass
-            self.converter = convclass(charset_name, self._use_unicode)
+            self.converter = convclass(charset_name, self.use_unicode)
             self.converter.str_fallback = self._converter_str_fallback
         else:
             raise TypeError(
@@ -3010,7 +3096,7 @@ def lastrowid(self) -> Optional[int]:
 
     @property
     def warnings(self) -> Optional[List[WarningType]]:
-        """Returns a list of tuples (WarningType) containing warnings generated
+        """Gets a list of tuples (WarningType) containing warnings generated
         by the previously executed operation.
 
         Examples:
@@ -3053,6 +3139,7 @@ def statement(self) -> Optional[str]:
         except (AttributeError, UnicodeDecodeError):
             return cast(str, self._executed.strip())
 
+    @deprecated(DEPRECATED_METHOD_WARNING.format(property_name="warnings"))
     def fetchwarnings(self) -> Optional[List[WarningType]]:
         """Returns a list of tuples (WarningType) containing warnings generated by
         the previously executed operation.