Create public aliases for arguments

[KalleDK]

The problem I'm trying to solve is having a method that takes an element or elementtree as argument, and forwards that to a XPath object.

x = etree.XPath("//div")

def method(elem):
  // other stuff
  r = x(elem)
  // other stuff

If I do this with fx pylance, I would get the complaint that elem is Unknown. If I try to fix this by adding the type, I would have to write

def method(elem: typing.Union[etree._Element, etree._ElementTree]):

Which of course triggers that the types are private.

For easy fix I would suggest some simple typing aliases

TElement = _Element or something like that (Don't really care about the syntax - more about that the types would be public)

[mvantellingen]

You can use ElementBase for that right? See https://github.com/lxml/lxml-stubs/blob/master/lxml-stubs/etree.pyi#L140 and https://lxml.de/api/lxml.etree.ElementBase-class.html

[KalleDK]

Not if I understand it correctly

As for example parse https://github.com/lxml/lxml-stubs/blob/master/lxml-stubs/etree.pyi#L371 and getnext https://github.com/lxml/lxml-stubs/blob/master/lxml-stubs/etree.pyi#L104 return _ElementTree and _Element along with most of the methods. This would not match ElementBase as it's a subclass of _Element.

def method(elem: etree.ElementBase):
  pass

t = etree.parse(.....)
method(t)

This would say that they don't match.

[scoder]

You can use ElementBase for that right?

ElementBase is a public subclass of _Element that is provided for users as a base class for their own Element classes. It's not a catch-all base class for Elements.

Which of course triggers that the types are private.

So? A private class does not prevent its objects from being passed into functions. Using a private class as argument type hints seems totally reasonable to me, and the warning that you get seems a false positive.

The convention is lxml is that "private" (starting with an underscore) classes are not meant to be instantiated by users. That doesn't prevent them from being used in other ways, e.g. for typing.

[KalleDK]

So? A private class does not prevent its objects from being passed into functions. Using a private class as argument type hints seems totally reasonable to me, and the warning that you get seems a false positive.

The convention is lxml is that "private" (starting with an underscore) classes are not meant to be instantiated by users. That doesn't prevent them from being used in other ways, e.g. for typing.

I know I can use the private classes for typing, but I would say I would be breaking some kinda python rule if my module uses private classes from another module (even if it's only for typing)

Also if I do use them, pylance ( and other static tools ) will complain that you are using private classes

[scoder]

static tools will complain that you are using private classes

Then I would argue that those tools need to be fixed. Apparently, it's not enough to warn about imported names that simply start with an underscore, it's also relevant what they are used for. If they are not used at all, that's an "unused import" case. If they are getting called or instantiated or otherwise actively used in code, that's a violation of an API contract. If they are used for isinstance() type checks, that might be ok but has a code smell (lxml provides an iselement() predicate function, for example). If they are used in type hints, that's probably fine.

lxml might be excessive here with its relatively high number of internal classes, but I'm sure it's not the only package where this problem appears. Adding a non-private alias for the _Element class would counter the intention of keeping private classes private.

[scoder]

Closing, since it's a third-party issue.