Improve annotation of fromstring

[DMRobertson]

Resolves #63. See discussion there for more context.

1. parser seems like it can be an HTMLParser. There's code in the wild
   that does this without obviously being wrong. As far as I can tell from
   the lxml Cython source, parser is a _BaseParser, which encompasses
   XMLParser, HTMLParser and the iterparse class. I wasn't sure if the
   latter ought to be allowed here too. I erred on the side of caution.

2. It's possible for this function to return None, if the parser has
   recover=True. I couldn't find a good way to express this without
   affecting every other call to fromstring. (Perhaps one could make the
   Parser generic over some kind of Recoverable indicator type... but
   that seemed like overkill).

[scoder]

The HTMLParser is also allowed here.

[scoder]

Since None is really a thing that you'd only get if you pass a suitable parser (and that gets in the way otherwise), maybe we can split up the declarations of fromstring() and parse() to only allow None return values if the parser argument is provided?

Admittedly, you can also change the default parser globally, which then allows a None return value here. And, in fact, it's not even guaranteed that the return value is an Element otherwise, since parsers can really return whatever they choose. However, that's such an extremely rare use case that I'd lean towards not expressing it in the type system. (OTOH, the whole point of this PR is to cater for an extremely rare use case, so …)

[JelleZijlstra]

In typeshed we generally avoid Unions in return types, for reasons discussed in python/mypy#1693. In this case, it sounds like returning None is a very rare edge case, but if we return Element | None, we force every caller to check for None after calling this function. As you say, one improvement could be to use overloads for cases where we know the return value is definitely not None. Another approach we've used in typeshed is to return something like Element | Any. This gives you a lot of type safety but also allows callers to do None checks without hitting "unreachable code" warnings.

[DMRobertson]

Many thanks both!

On returning Union types: I'd read some of the discussion in python/typing#566 which sounded promising at first, but as Jukka writes here:

For new code and new APIs the recommended way is to avoid signatures that would require the use of AnyOf anyway.

I'm about to push three commits which:

• clarify that parse accepts an HTML parser too;
• express that fromstring() without a parser returns an _Element (the comment about changing the default parser notwithstanding; and
• change the return type of fromstring to _Element | Any.

To be explicit: I don't have strong opinions about this PR. I like the idea of annotations that describe everything that a function can possibly do; but there's a balance to between that and pragmatism, and I'm happy to drop the | None change if it's too niche. It'd be nice to get the bit about HTMLParser in though, if nothing else!

[scoder]

Thanks