|
5 | 5 |
|
6 | 6 | from __future__importannotations |
7 | 7 |
|
8 | | -__all__= ["Git"] |
| 8 | +__all__= ["GitMeta","Git"] |
9 | 9 |
|
10 | 10 | importcontextlib |
11 | 11 | importio |
@@ -354,6 +354,32 @@ def __setattr(cls, name: str, value: Any) -> Any: |
354 | 354 | __setattr__=__setattr |
355 | 355 |
|
356 | 356 |
|
| 357 | +GitMeta=_GitMeta |
| 358 | +"""Alias of :class:`Git`'s metaclass, whether it is :class:`type` or a custom metaclass. |
| 359 | +
|
| 360 | +Whether the :class:`Git` class has the default :class:`type` as its metaclass or uses a |
| 361 | +custom metaclass is not documented and may change at any time. This statically checkable |
| 362 | +metaclass alias is equivalent at runtime to ``type(Git)``. This should almost never be |
| 363 | +used. Code that benefits from it is likely to be remain brittle even if it is used. |
| 364 | +
|
| 365 | +In view of the :class:`Git` class's intended use and :class:`Git` objects' dynamic |
| 366 | +callable attributes representing git subcommands, it rarely makes sense to inherit from |
| 367 | +:class:`Git` at all. Using :class:`Git` in multiple inheritance can be especially tricky |
| 368 | +to do correctly. Attempting uses of :class:`Git` where its metaclass is relevant, such |
| 369 | +as when a sibling class has an unrelated metaclass and a shared lower bound metaclass |
| 370 | +might have to be introduced to solve a metaclass conflict, is not recommended. |
| 371 | +
|
| 372 | +:note: |
| 373 | + The correct static type of the :class:`Git` class itself, and any subclasses, is |
| 374 | + ``Type[Git]``. (This can be written as ``type[Git]`` in Python 3.9 later.) |
| 375 | +
|
| 376 | + :class:`GitMeta` should never be used in any annotation where ``Type[Git]`` is |
| 377 | + intended or otherwise possible to use. This alias is truly only for very rare and |
| 378 | + inherently precarious situations where it is necessary to deal with the metaclass |
| 379 | + explicitly. |
| 380 | +""" |
| 381 | + |
| 382 | + |
357 | 383 | classGit(metaclass=_GitMeta): |
358 | 384 | """The Git class manages communication with the Git binary. |
359 | 385 |
|
|