Add type annotations to xml.py

minio/xml.py

@@ -16,17 +16,19 @@
 
 """XML utility module."""
 
-from __future__ import absolute_import
-
+from __future__ import absolute_import, annotations
+from typing import Type, TypeVar
 import io
 from xml.etree import ElementTree as ET
 
+from typing_extensions import Protocol
+
 _S3_NAMESPACE = "http://s3.amazonaws.com/doc/2006-03-01/"
 
 
-def Element(tag, namespace=_S3_NAMESPACE): # pylint: disable=invalid-name
+def Element(tag: str, namespace=_S3_NAMESPACE): # pylint: disable=invalid-name
  """Create ElementTree.Element with tag and namespace."""
- return ET.Element(tag, {'xmlns': namespace} if namespace else {})
+ return ET.Element(tag, {"xmlns": namespace} if namespace else {})
 
 
 def SubElement(parent, tag, text=None): # pylint: disable=invalid-name
@@ -37,7 +39,7 @@ def SubElement(parent, tag, text=None): # pylint: disable=invalid-name
  return element
 
 
-def _get_namespace(element):
+def _get_namespace(element: ET.Element):
  """Exact namespace if found."""
  start = element.tag.find("{")
  if start < 0:
@@ -49,7 +51,7 @@ def _get_namespace(element):
  return element.tag[start:end]
 
 
-def findall(element, name):
+def findall(element: ET.Element, name: str) -> list[ET.Element]:
  """Namespace aware ElementTree.Element.findall()."""
  namespace = _get_namespace(element)
  return element.findall(
@@ -58,7 +60,7 @@ def findall(element, name):
  )
 
 
-def find(element, name):
+def find(element: ET.Element, name: str):
  """Namespace aware ElementTree.Element.find()."""
  namespace = _get_namespace(element)
  return element.find(
@@ -67,7 +69,11 @@ def find(element, name):
  )
 
 
-def findtext(element, name, strict=False):
+def findtext(
+ element: ET.Element,
+ name: str,
+ strict: bool = False,
+) -> str | None:
  """
  Namespace aware ElementTree.Element.findtext() with strict flag
  raises ValueError if element name not exist.
@@ -80,20 +86,43 @@ def findtext(element, name, strict=False):
  return element.text or ""
 
 
-def unmarshal(cls, xmlstring):
+K = TypeVar("K")
+
+
+class IFromXML(Protocol):
+ """typing stub for class with `fromxml` method"""
+
+ @classmethod
+ def fromxml(cls: Type[K], element: ET.Element) -> K:
+ """Create python object with values from XML element."""
+
+
+T = TypeVar("T", bound=IFromXML)
+
+
+def unmarshal(cls: Type[T], xmlstring: str) -> T:
  """Unmarshal given XML string to an object of passed class."""
  return cls.fromxml(ET.fromstring(xmlstring))
 
 
-def getbytes(element):
+def getbytes(element: ET.Element) -> bytes:
  """Convert ElementTree.Element to bytes."""
- data = io.BytesIO()
- ET.ElementTree(element).write(
- data, encoding=None, xml_declaration=False,
- )
- return data.getvalue()
+ with io.BytesIO() as data:
+ ET.ElementTree(element).write(
+ data,
+ encoding=None,
+ xml_declaration=False,
+ )
+ return data.getvalue()
+
+
+class IToXML(Protocol):
+ """typing stub for class with `toxml` method"""
+
+ def toxml(self, element: ET.Element | None) -> ET.Element:
+ """Convert python object to ElementTree.Element."""
 
 
-def marshal(obj):
+def marshal(obj: IToXML) -> bytes:
  """Get XML data as bytes of ElementTree.Element."""
  return getbytes(obj.toxml(None))

setup.py

@@ -43,7 +43,7 @@
  long_description_content_type="text/markdown",
  package_dir={"minio": "minio"},
  packages=["minio", "minio.credentials"],
- install_requires=["certifi", "urllib3", "argon2-cffi", "pycryptodome"],
+ install_requires=["certifi", "urllib3", "argon2-cffi", "pycryptodome", "typing-extensions"],
  tests_require=[],
  license="Apache-2.0",
  classifiers=[