Improved annotation & docstrings

rss_parser/_parser.py

@@ -15,7 +15,7 @@
 
 
 class Parser:
-    """Parser for rss files."""
+    """Parser for rss/atom files."""
 
     @staticmethod
     def check_schema(root: dict) -> tuple[dict, type[XMLBaseModel]]:
@@ -30,7 +30,7 @@ def to_xml(data: str, *args, **kwargs):
     @classmethod
     def parse(cls, data: str, *, schema: Optional[Type[XMLBaseModel]] = None, root_key: str = "") -> XMLBaseModel:
         """
-        Parse XML data into schema (default: RSS 2.0).
+        Parse XML data into schema (default: RSS 2.0 or Atom).
 
         :param data: string of XML data that needs to be parsed
         :return: "schema" object

rss_parser/models/atom/atom.py

@@ -9,7 +9,7 @@
 
 
 class Atom(XMLBaseModel):
-    """Atom 1.0."""
+    """Atom 1.0"""
 
     version: Optional[Tag[str]] = pydantic.Field(alias="@version")
     feed: Tag[Feed]

rss_parser/models/atom/entry.py

@@ -10,23 +10,44 @@
 
 class RequiredAtomEntryMixin(XMLBaseModel):
     entry_id: Tag[str] = pydantic.Field(alias="id")
+    "Identifier for the entry."
+
     title: Tag[str]
+    "The title of the entry."
+
     updated: Tag[str]
+    "Indicates when the entry was updated."
 
 
 class RecommendedAtomEntryMixin(XMLBaseModel):
     author: Optional[Tag[dict]] = None
+    "Email, name, and URI of the author of the entry."
+
     link: Optional[Tag[list]] = None
+    "The URL of the entry."
+
     content: Optional[Tag[dict]] = None
+    "The main content of the entry."
+
     summary: Optional[Tag[str]] = None
+    "Conveys a short summary, abstract, or excerpt of the entry. Some feeds use this tag as the main content."
 
 
 class OptionalAtomEntryMixin(XMLBaseModel):
     category: Optional[Tag[dict]] = None
+    "Specifies a categories that the feed belongs to."
+
     contributor: Optional[Tag[dict]] = None
+    "Email, name, and URI of the contributors of the entry."
+
     rights: Optional[Tag[str]] = None
+    "The copyright of the entry."
+
     published: Optional[Tag[DateTimeOrStr]] = None
+    "Indicates when the entry was published."
+
     source: Optional[Tag[str]] = None
+    "Contains metadata from the source feed if this entry is a copy."
 
 
 class Entry(RequiredAtomEntryMixin, RecommendedAtomEntryMixin, OptionalAtomEntryMixin, XMLBaseModel):

rss_parser/models/atom/feed.py

@@ -13,24 +13,48 @@
 
 class RequiredAtomFeedMixin(XMLBaseModel):
     feed_id: Tag[str] = pydantic.Field(alias="id")
+    "Identifies the feed using a universally unique and permanent URI."
+
     title: Tag[str]
+    "Contains a human readable title for the feed."
+
     updated: Tag[DateTimeOrStr]
+    "Indicates the last time the feed was modified in a significant way."
 
 
 class RecommendedAtomFeedMixin(XMLBaseModel):
     author: Optional[Tag[str]] = None
+    "Names one author of the feed. A feed may have multiple author elements."
+
     link: Optional[Tag[list]] = None
+    "The URL to the feed. A feed may have multiple link elements."
 
 
 class OptionalAtomFeedMixin(XMLBaseModel):
     entries: Optional[OnlyList[Tag[Entry]]] = pydantic.Field(alias="entry", default=[])
+    "The entries in the feed. A feed may have multiple entry elements."
+
     category: Optional[Tag[str]] = None
+    "Specifies a categories that the feed belongs to. The feed may have multiple categories elements."
+
     contributor: Optional[Tag[str]] = None
+    "Names one contributor to the feed. A feed may have multiple contributor elements."
+
     generator: Optional[Tag[str]] = None
+    "Identifies the software used to generate the feed, for debugging and other purposes."
+
     icon: Optional[Tag[Image]] = None
+    "Identifies a small image which provides iconic visual identification for the feed. Icons should be square."
+
     logo: Optional[Tag[Image]] = None
+    "Identifies a larger image which provides visual identification for the feed.\
+    Images should be twice as wide as they are tall."
+
     rights: Optional[Tag[str]] = None
+    "The copyright of the feed."
+
     subtitle: Optional[Tag[str]] = None
+    "Contains a human readable description or subtitle for the feed."
 
 
 class Feed(RequiredAtomFeedMixin, RecommendedAtomFeedMixin, OptionalAtomFeedMixin, XMLBaseModel):