refactor: move public api to init

src/rfc3987_syntax2/__init__.py

@@ -2,22 +2,281 @@
 # Copyright (c) 2026 Jan Kowalleck - modifications and maintenance
 # SPDX-License-Identifier: MIT
 
-from typing import Any
+from pathlib import Path
+from threading import Lock
+from typing import Any, Callable, Optional, TYPE_CHECKING, Literal
+from warnings import warn
 
-from . import syntax_helpers as _syntax_helpers
+from lark import Lark, ParseTree, exceptions
 
-__all__ = _syntax_helpers.__all__
 
-_EXPORTS_SH = frozenset(_syntax_helpers.__all__)
+RFC3987_SYNTAX_PARSER_TYPE: str = "earley"
+RFC3987_SYNTAX_GRAMMAR_PATH: Path = Path(__file__).parent / "syntax_rfc3987.lark"
+RFC3987_SYNTAX_TERMS: list[str] = [
+    "iri",
+    "iri_reference",
+    "absolute_iri",
+    "scheme",
+    "ihier_part",
+    "irelative_ref",
+    "irelative_part",
+    "iauthority",
+    "iuserinfo",
+    "ihost",
+    "ireg_name",
+    "ipath",
+    "ipath_abempty",
+    "ipath_absolute",
+    "ipath_noscheme",
+    "ipath_rootless",
+    "ipath_empty",
+    "isegment",
+    "isegment_nz",
+    "isegment_nz_nc",
+    "ipchar",
+    "iquery",
+    "ifragment",
+    "iunreserved",
+    "ucschar",
+    "iprivate",
+    "sub_delims",
+    "ip_literal",
+    "ipvfuture",
+    "ipv6address",
+    "h16",
+    "ls32",
+    "ipv4address",
+    "dec_octet",
+    "digit",
+    "non_zero",
+    "unreserved",
+    "alpha",
+    "hexdig",
+    "port",
+    "pct_encoded",
+]
+
+_T_SYNTAX_PARSER_TERM = Literal["iri", "iri_reference", "absolute_iri"]
+_SYNTAX_PARSER_STARTS: list[_T_SYNTAX_PARSER_TERM] = ["iri", "iri_reference", "absolute_iri"]
+
+def parse(term: _T_SYNTAX_PARSER_TERM, value: str) -> 'ParseTree':
+    return _get_syntax_parser().parse(value, start=term)
+
+
+def is_valid_syntax(term: _T_SYNTAX_PARSER_TERM, value: str) -> bool:
+    try:
+        parse(term=term, value=value)
+    except exceptions.UnexpectedInput:
+        # from Lark.parse()
+        return False
+    except exceptions.LarkError as err:
+        # from Lark internals / initialization (non-UnexpectedInput)
+        warn("Unexpected LarkError (non-UnexpectedInput) "
+             f"for term={term!r}: {type(err).__name__}: {err}",
+            RuntimeWarning,
+            stacklevel=2)
+        return False
+    return True
+
+_T_SYNTAX_VALIDATOR = Callable[[str], bool]
+
+def make_syntax_validator(rule_name: str) -> _T_SYNTAX_VALIDATOR:
+    parser: Optional[Lark] = None
+    parser_lock = Lock()
+
+    def syntax_validator(text: str) -> bool:
+        nonlocal parser
+        with parser_lock:
+            if parser is None:
+                parser = Lark(_get_grammar(),
+                              start=rule_name,
+                              parser=RFC3987_SYNTAX_PARSER_TYPE)
+        try:
+            parser.parse(text)
+        except exceptions.LarkError:
+            return False
+        else:
+            return True
+
+    return syntax_validator
+
+
+_grammar: Optional[str] = None
+_grammar_lock = Lock()
+
+def _get_grammar() -> str:
+    """this is private API"""
+    global _grammar
+    with _grammar_lock:
+        if _grammar is None:
+            _grammar = RFC3987_SYNTAX_GRAMMAR_PATH.read_text(encoding='utf-8')
+        return _grammar
+
+
+_syntax_parser: Optional[Lark] = None
+_syntax_parser_lock = Lock()
+
+def _get_syntax_parser() -> Lark:
+    """this is private API"""
+    global _syntax_parser
+    if _syntax_parser is not None:
+        return _syntax_parser
+    grammar = _get_grammar()
+    with _syntax_parser_lock:
+        if _syntax_parser is None:
+            _syntax_parser = Lark(grammar,
+                                  start=_SYNTAX_PARSER_STARTS,
+                                  parser=RFC3987_SYNTAX_PARSER_TYPE)
+        return _syntax_parser
+
+
+is_valid_syntax_iri = make_syntax_validator("iri")
+
+is_valid_syntax_iri_reference = make_syntax_validator("iri_reference")
+
+is_valid_syntax_absolute_iri = make_syntax_validator("absolute_iri")
+
+is_valid_syntax_scheme = make_syntax_validator("scheme")
+
+is_valid_syntax_ihier_part = make_syntax_validator("ihier_part")
+
+is_valid_syntax_irelative_ref = make_syntax_validator("irelative_ref")
+
+is_valid_syntax_irelative_part = make_syntax_validator("irelative_part")
+
+is_valid_syntax_iauthority = make_syntax_validator("iauthority")
+
+is_valid_syntax_iuserinfo = make_syntax_validator("iuserinfo")
+
+is_valid_syntax_ihost = make_syntax_validator("ihost")
+
+is_valid_syntax_ireg_name = make_syntax_validator("ireg_name")
+
+is_valid_syntax_ipath = make_syntax_validator("ipath")
+
+is_valid_syntax_ipath_abempty = make_syntax_validator("ipath_abempty")
+
+is_valid_syntax_ipath_absolute = make_syntax_validator("ipath_absolute")
+
+is_valid_syntax_ipath_noscheme = make_syntax_validator("ipath_noscheme")
+
+is_valid_syntax_ipath_rootless = make_syntax_validator("ipath_rootless")
+
+is_valid_syntax_ipath_empty = make_syntax_validator("ipath_empty")
+
+is_valid_syntax_isegment = make_syntax_validator("isegment")
+
+is_valid_syntax_isegment_nz = make_syntax_validator("isegment_nz")
+
+is_valid_syntax_isegment_nz_nc = make_syntax_validator("isegment_nz_nc")
+
+is_valid_syntax_ipchar = make_syntax_validator("ipchar")
+
+is_valid_syntax_iquery = make_syntax_validator("iquery")
+
+is_valid_syntax_ifragment = make_syntax_validator("ifragment")
+
+is_valid_syntax_iunreserved = make_syntax_validator("iunreserved")
+
+is_valid_syntax_ucschar = make_syntax_validator("ucschar")
+
+is_valid_syntax_iprivate = make_syntax_validator("iprivate")
+
+is_valid_syntax_sub_delims = make_syntax_validator("sub_delims")
+
+is_valid_syntax_ip_literal = make_syntax_validator("ip_literal")
+
+is_valid_syntax_ipvfuture = make_syntax_validator("ipvfuture")
+
+is_valid_syntax_ipv6address = make_syntax_validator("ipv6address")
+
+is_valid_syntax_h16 = make_syntax_validator("h16")
+
+is_valid_syntax_ls32 = make_syntax_validator("ls32")
+
+is_valid_syntax_ipv4address = make_syntax_validator("ipv4address")
+
+is_valid_syntax_dec_octet = make_syntax_validator("dec_octet")
+
+is_valid_syntax_digit = make_syntax_validator("digit")
+
+is_valid_syntax_non_zero = make_syntax_validator("non_zero")
+
+is_valid_syntax_unreserved = make_syntax_validator("unreserved")
+
+is_valid_syntax_alpha = make_syntax_validator("alpha")
+
+is_valid_syntax_hexdig = make_syntax_validator("hexdig")
+
+is_valid_syntax_port = make_syntax_validator("port")
+
+is_valid_syntax_pct_encoded = make_syntax_validator("pct_encoded")
+
+RFC3987_SYNTAX_TERM_VALIDATORS: dict[str, _T_SYNTAX_VALIDATOR] = {  # frozendict
+    "iri": is_valid_syntax_iri,
+    "iri_reference": is_valid_syntax_iri_reference,
+    "absolute_iri": is_valid_syntax_absolute_iri,
+    "scheme": is_valid_syntax_scheme,
+    "ihier_part": is_valid_syntax_ihier_part,
+    "irelative_ref": is_valid_syntax_irelative_ref,
+    "irelative_part": is_valid_syntax_irelative_part,
+    "iauthority": is_valid_syntax_iauthority,
+    "iuserinfo": is_valid_syntax_iuserinfo,
+    "ihost": is_valid_syntax_ihost,
+    "ireg_name": is_valid_syntax_ireg_name,
+    "ipath": is_valid_syntax_ipath,
+    "ipath_abempty": is_valid_syntax_ipath_abempty,
+    "ipath_absolute": is_valid_syntax_ipath_absolute,
+    "ipath_noscheme": is_valid_syntax_ipath_noscheme,
+    "ipath_rootless": is_valid_syntax_ipath_rootless,
+    "ipath_empty": is_valid_syntax_ipath_empty,
+    "isegment": is_valid_syntax_isegment,
+    "isegment_nz": is_valid_syntax_isegment_nz,
+    "isegment_nz_nc": is_valid_syntax_isegment_nz_nc,
+    "ipchar": is_valid_syntax_ipchar,
+    "iquery": is_valid_syntax_iquery,
+    "ifragment": is_valid_syntax_ifragment,
+    "iunreserved": is_valid_syntax_iunreserved,
+    "ucschar": is_valid_syntax_ucschar,
+    "iprivate": is_valid_syntax_iprivate,
+    "sub_delims": is_valid_syntax_sub_delims,
+    "ip_literal": is_valid_syntax_ip_literal,
+    "ipvfuture": is_valid_syntax_ipvfuture,
+    "ipv6address": is_valid_syntax_ipv6address,
+    "h16": is_valid_syntax_h16,
+    "ls32": is_valid_syntax_ls32,
+    "ipv4address": is_valid_syntax_ipv4address,
+    "dec_octet": is_valid_syntax_dec_octet,
+    "digit": is_valid_syntax_digit,
+    "non_zero": is_valid_syntax_non_zero,
+    "unreserved": is_valid_syntax_unreserved,
+    "alpha": is_valid_syntax_alpha,
+    "hexdig": is_valid_syntax_hexdig,
+    "port": is_valid_syntax_port,
+    "pct_encoded": is_valid_syntax_pct_encoded,
+}
+
+
+# region lazy loaded attrs
+
+if TYPE_CHECKING:  # types for lazy-loaded symbols
+    grammar: str
+    syntax_parser: Lark
 
 
 def __getattr__(name: str) -> Any:
-    if name in _EXPORTS_SH:
-        value = getattr(_syntax_helpers, name)
-        globals()[name] = value
-        return value
+    if name == "grammar":
+        print('get_grammar')
+        global grammar
+        grammar = _get_grammar()
+        return grammar
+    if name == "syntax_parser":
+        global syntax_parser
+        syntax_parser = _get_syntax_parser()
+        return syntax_parser
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
-
 def __dir__() -> list[str]:
-    return sorted(set(globals().keys()) | set(__all__))
+    return sorted(set(globals().keys()) | {"grammar", "syntax_parser"})
+
+# endregion lazy loaded attrs