From 8a36ab5e73e4703856fdf3c795b9e6431874b432 Mon Sep 17 00:00:00 2001
From: Christodoulos Tsoulloftas <chris@komposta.net>
Date: Thu, 25 Jan 2024 20:43:16 +0200
Subject: [PATCH] Finish the parser docstrings

---
 tests/formats/dataclass/parsers/test_xml.py |  2 +-
 xsdata/formats/dataclass/parsers/bases.py   |  5 +-
 xsdata/formats/dataclass/parsers/json.py    |  2 +-
 xsdata/formats/dataclass/parsers/mixins.py  |  2 +-
 xsdata/formats/dataclass/parsers/xml.py     | 52 ++++++++++++---------
 5 files changed, 38 insertions(+), 25 deletions(-)

diff --git a/tests/formats/dataclass/parsers/test_xml.py b/tests/formats/dataclass/parsers/test_xml.py
index abf1f0a3c..7bc3f6778 100644
--- a/tests/formats/dataclass/parsers/test_xml.py
+++ b/tests/formats/dataclass/parsers/test_xml.py
@@ -57,4 +57,4 @@ def test_emit_event(self):
         self.parser.emit_event("foo", "{tns}BarEl", a=1, b=2)
 
         mock_func.assert_called_once_with(a=1, b=2)
-        self.assertEqual({("foo", "{tns}BarEl"): mock_func}, self.parser.emit_cache)
+        self.assertEqual({("foo", "{tns}BarEl"): mock_func}, self.parser.hooks_cache)
diff --git a/xsdata/formats/dataclass/parsers/bases.py b/xsdata/formats/dataclass/parsers/bases.py
index a7efed0bc..9848a15c8 100644
--- a/xsdata/formats/dataclass/parsers/bases.py
+++ b/xsdata/formats/dataclass/parsers/bases.py
@@ -20,11 +20,14 @@
 
 @dataclass
 class NodeParser(PushParser):
-    """Bind xml nodes to dataclasses.
+    """Bind xml nodes to data classes.
 
     Args:
         context: Model context provider
         handler: The xml handler class
+
+    Attributes:
+        ns_map: The parsed namespace prefix-URI map
     """
 
     context: XmlContext = field(default_factory=XmlContext)
diff --git a/xsdata/formats/dataclass/parsers/json.py b/xsdata/formats/dataclass/parsers/json.py
index a343edef8..a08813e98 100644
--- a/xsdata/formats/dataclass/parsers/json.py
+++ b/xsdata/formats/dataclass/parsers/json.py
@@ -17,7 +17,7 @@
 
 @dataclass
 class JsonParser(AbstractParser):
-    """Json parser for dataclasses.
+    """Json parser for data classes.
 
     Args:
         config: Parser configuration
diff --git a/xsdata/formats/dataclass/parsers/mixins.py b/xsdata/formats/dataclass/parsers/mixins.py
index c8b8e3337..ddc5cea2a 100644
--- a/xsdata/formats/dataclass/parsers/mixins.py
+++ b/xsdata/formats/dataclass/parsers/mixins.py
@@ -18,7 +18,7 @@ class PushParser(AbstractParser):
         config: The parser configuration instance
 
     Attributes:
-        ns_map: Namespace registry of parsed prefix-URI mappings
+        ns_map: The parsed namespace prefix-URI map
     """
 
     config: ParserConfig = field(default_factory=ParserConfig)
diff --git a/xsdata/formats/dataclass/parsers/xml.py b/xsdata/formats/dataclass/parsers/xml.py
index 8101529bf..1a77fa429 100644
--- a/xsdata/formats/dataclass/parsers/xml.py
+++ b/xsdata/formats/dataclass/parsers/xml.py
@@ -11,12 +11,15 @@
 
 @dataclass
 class XmlParser(NodeParser):
-    """Default Xml parser for dataclasses.
+    """Default Xml parser for data classes.
 
-    :param config: Parser configuration
-    :param context: Model context provider
-    :param handler: Override default XmlHandler
-    :ivar ms_map: The prefix-URI map generated during parsing
+    Args:
+        config: The parser config instance
+        context: The xml context instance
+        handler: The xml handler class
+
+    Attributes:
+        ns_map: The parsed namespace prefix-URI map
     """
 
     handler: Type[XmlHandler] = field(default=default_handler())
@@ -24,18 +27,25 @@ class XmlParser(NodeParser):
 
 @dataclass
 class UserXmlParser(NodeParser):
-    """User Xml parser for dataclasses with hooks for emitting events to alter the
-    behavior when an elements starts or ends.
-
-    :param config: Parser configuration
-    :param context: Model context provider
-    :param handler: Override default XmlHandler
-    :ivar ms_map: The prefix-URI map generated during parsing
-    :ivar emit_cache: Qname to event name cache
+    """Xml parser for dataclasses with hooks to events.
+
+    The event hooks allow custom parsers to inject custom
+    logic between the start/end element events.
+
+    Args:
+        config: The parser config instance
+        context: The xml context instance
+        handler: The xml handler class
+
+    Attributes:
+        ns_map: The parsed namespace prefix-URI map
+        hooks_cache: The hooks cache is used to avoid
+            inspecting the class for custom methods
+            on duplicate events.
     """
 
     handler: Type[XmlHandler] = field(default=default_handler())
-    emit_cache: Dict = field(init=False, default_factory=dict)
+    hooks_cache: Dict = field(init=False, default_factory=dict)
 
     def start(
         self,
@@ -96,18 +106,18 @@ def emit_event(self, event: str, name: str, **kwargs: Any):
         any input keyword arguments.
 
         Example::
-
             event=start, name={urn}bookTitle -> start_booking_title(**kwargs)
 
-        :param event: Event type start|end
-        :param name: Element qualified name
-        :param kwargs: Event keyword arguments
+        Args:
+            event: The event type start|end
+            name: The qualified name of the element
+            kwargs: Additional keyword arguments passed to the hooks
         """
         key = (event, name)
-        if key not in self.emit_cache:
+        if key not in self.hooks_cache:
             method_name = f"{event}_{snake_case(local_name(name))}"
-            self.emit_cache[key] = getattr(self, method_name, None)
+            self.hooks_cache[key] = getattr(self, method_name, None)
 
-        method = self.emit_cache[key]
+        method = self.hooks_cache[key]
         if method:
             method(**kwargs)