ua-parser / uap-python

Python implementation of ua-parser
Apache License 2.0
561 stars 152 forks source link

Split Parser and reorganise package #192

Closed masklinn closed 7 months ago

masklinn commented 7 months ago

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:

Fixes #189