Parser turns out to not really make sense as a superclass / ABC: it really only has one useful method, and because parsers use delegation there's no real way to override the utility methods / shortcuts, so they're only useful on the caller / client side but they constrain the implementor (who has to extend the ABC and then possibly deal with multiple-inheritance shenanigans).
Making the core object just a callable protocol instead makes the implementation somewhat simpler and more flexible (e.g. just a function or HoF can be a "parser"), however the convenient utility methods are important for end users and should not be discounted.
For that, keep a wrapper Parser object which can be wrapped around a "parser" in order to provide the additional convenience (similar to the free functions at the root). Importantly, Parser methods can also be used as free functions by passing a "parser" as self, they are intended to be compatible. It doesn't work super well from the typechecking perspective, but it works fine enough.
Consideration was given to making the free functions at the package root parametric on the parser e.g.
def parse(ua: str, resolver: Optional[Resolver] = None, /) -> ParseResult:
if resolver is None:
from . import parser as resolver
return resolver(ua, Domain.ALL).complete()
but that feels like it would be pretty error prone, in the sense that it would be too easy to forget to pass in the resolver, compared to consistently resolving via a bespoke parser, or just installing a parser globally.
Also move things around a bit:
move matcher utility functions out of the core, un-prefix them since we're using __all__ for visibility anyway
move eager matchers out of the core, similar to the lazy matchers
Parser turns out to not really make sense as a superclass / ABC: it really only has one useful method, and because parsers use delegation there's no real way to override the utility methods / shortcuts, so they're only useful on the caller / client side but they constrain the implementor (who has to extend the ABC and then possibly deal with multiple-inheritance shenanigans).
Making the core object just a callable protocol instead makes the implementation somewhat simpler and more flexible (e.g. just a function or HoF can be a "parser"), however the convenient utility methods are important for end users and should not be discounted.
For that, keep a wrapper
Parser
object which can be wrapped around a "parser" in order to provide the additional convenience (similar to the free functions at the root). Importantly,Parser
methods can also be used as free functions by passing a "parser" asself
, they are intended to be compatible. It doesn't work super well from the typechecking perspective, but it works fine enough.Consideration was given to making the free functions at the package root parametric on the parser e.g.
but that feels like it would be pretty error prone, in the sense that it would be too easy to forget to pass in the resolver, compared to consistently resolving via a bespoke parser, or just installing a parser globally.
Also move things around a bit:
__all__
for visibility anywayFixes #189