Add an attrs-based parser API

setup.cfg

@@ -72,3 +72,4 @@ strict_equality = True
 warn_redundant_casts = True
 warn_return_any = True
 warn_unreachable = True
+plugins = headerparser.mypy

src/headerparser/__init__.py

@@ -15,6 +15,7 @@
 
 from .errors import (
     BodyNotAllowedError,
+    DuplicateBodyError,
     DuplicateFieldError,
     Error,
     FieldTypeError,
@@ -29,6 +30,15 @@
     UnknownFieldError,
 )
 from .normdict import NormalizedDict
+from .parscls import (
+    BodyField,
+    ExtraFields,
+    Field,
+    MultiExtraFields,
+    MultiField,
+    parsable,
+    parse,
+)
 from .parser import HeaderParser
 from .scanner import (
     Scanner,
@@ -39,7 +49,7 @@
     scan_stanzas_string,
     scan_string,
 )
-from .types import BOOL, lower, unfold
+from .types import BOOL, decode_bool, decode_value, lower, multidict, unfold
 
 __version__ = "0.5.1"
 __author__ = "John Thorvald Wodder II"
@@ -49,23 +59,34 @@
 
 __all__ = [
     "BOOL",
+    "BodyField",
     "BodyNotAllowedError",
+    "DuplicateBodyError",
     "DuplicateFieldError",
     "Error",
-    "HeaderParser",
+    "ExtraFields",
+    "Field",
     "FieldTypeError",
+    "HeaderParser",
     "InvalidChoiceError",
     "MalformedHeaderError",
     "MissingBodyError",
     "MissingFieldError",
+    "MultiExtraFields",
+    "MultiField",
     "NormalizedDict",
     "ParserError",
     "Scanner",
     "ScannerEOFError",
     "ScannerError",
     "UnexpectedFoldingError",
     "UnknownFieldError",
+    "decode_bool",
+    "decode_value",
     "lower",
+    "multidict",
+    "parsable",
+    "parse",
     "scan",
     "scan_next_stanza",
     "scan_next_stanza_string",

src/headerparser/errors.py

@@ -54,6 +54,13 @@ def __str__(self) -> str:
         return f"Header field {self.name!r} occurs more than once"
 
 
+class DuplicateBodyError(ParserError):
+    """Raised when a body field occurs two or more times in the input"""
+
+    def __str__(self) -> str:
+        return "Body field occurs more than once"
+
+
 class FieldTypeError(ParserError):
     """Raised when a ``type`` callable raises an exception"""
 

src/headerparser/mypy.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+from mypy.plugin import Plugin
+from mypy.plugins.attrs import attr_attrib_makers, attr_define_makers
+
+attr_define_makers.add("headerparser.parscls.parsable")
+
+attr_attrib_makers.add("headerparser.parscls.Field")
+attr_attrib_makers.add("headerparser.parscls.MultiField")
+attr_attrib_makers.add("headerparser.parscls.ExtraFields")
+attr_attrib_makers.add("headerparser.parscls.MultiExtraFields")
+attr_attrib_makers.add("headerparser.parscls.BodyField")
+
+
+class HeaderParserPlugin(Plugin):
+    pass
+
+
+def plugin(_version: str) -> type[Plugin]:
+    return HeaderParserPlugin