[portage] Start of stubs

[Tatsh]

This is a port of portage-stubs. It is a very minimal set of stubs just enough for my livecheck project to use. The Portage API is fairly unstable, massive, and not entirely what you can call 'public'. However, the parts I have been using have not changed much in the last few years.

Once merged I will deprecate and archive portage-stubs here and on PyPI.

The upstream Portage project is not likely to be fully typed anytime soon. The authors are also not interested in the necessary workarounds such as having a lot of if TYPE_CHECKING: blocks to workaround the dynamic typing in the API.

[brianschubert]

Since there are other public members that are not part of this stub file, we need to add the following:

def __getattr__(name: str): ...  # incomplete module

The partial_stub marker in METADATA.toml only tells type checkers that whole modules are missing, not that modules that do exist might be incomplete. That's what the __getattr__ does.

[Tatsh]

With this line added as is, how do I get past the stricter Pyright check? I saw that no other stubs with this added a return type.

[brianschubert]

See #15391 (comment)

[Tatsh]

Confused on why Black and flake8 are failing. They run fine and have no issues here:

(.venv) tatsh@limelight ~/dev/typeshed/stubs/portage
 $ black . && flake8 .
All done! ✨ 🍰 ✨
8 files left unchanged.

[brianschubert]

The pre-commit failures are unrelated. Not sure what's causing them (they started appearing a few days ago, but also occur when I check out older commits, so I'm not sure it's something on our end)

[brianschubert]

Literal defaults should use the actual value:

Suggested change

	def match(self, mydep: str, use_cache: Literal[0, 1] = ...) -> list[str] | str: ...
	def match(self, mydep: str, use_cache: Literal[0, 1] = 1) -> list[str] | str: ...

[brianschubert]

GitHub mirror, which seems to be up to date and used for active development. Generally github upstream repos play nicer with our automation

Suggested change

	upstream_repository = "https://gitweb.gentoo.org/proj/portage.git"
	upstream_repository = "https://github.com/gentoo/portage"

[brianschubert]

These days we require a comment for each use of Any explaining why it's necessary / what the allowable runtime types are. If you are unsure what the correct types are, you can use Incomplete (from _typeshed) – which is an alias of Any – instead.

[brianschubert]

To fix the pyright errors, you'll need to either add these stubs to to pyrightconfig.stricter.json, or use -> Incomplete for the return type (import from _typeshed, only allowed for __getattr__)

[Tatsh]

Had to make changes for strict Pyright and not use Incomplete in some places as that would then fail the pre-commit check. I do not have an explanation for every use of Any yet or the type info so I will have to come back to this.

[brianschubert]

You can add these stubs to the exclude list in the config file mentioned in #15391 (comment) to suppress the pyright errors. For "top-level" incomplete types it's better to leave the type unannotated than to use an explicit Any (the reason being that some type checkers treat missing annotations and explicit Any annotations differently). Incomplete can be used when the type is partially known (e.g. list[Incomplete]) or when it's not possible to omit the annotation (e.g. attributes).

See also https://typing.python.org/en/latest/guides/writing_stubs.html#incomplete-stubs for other tips on writing partial stubs

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉