Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Type and mark as final module-level dunders not meant to be overwritten in stdlib/ #9709

Merged
merged 4 commits into from
Feb 12, 2023
Merged

Type and mark as final module-level dunders not meant to be overwritten in stdlib/ #9709

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d9fd3bf
Type and mark as final module-level dunders not meant to be overwritten
Avasam Feb 11, 2023
7aa5028
Fix pytype error
Avasam Feb 11, 2023
61d5479
Fix pytype error
Avasam Feb 11, 2023
23744af
PR comment
Avasam Feb 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions stdlib/_csv.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
from _typeshed import SupportsWrite
from collections.abc import Iterable, Iterator
from typing import Any
from typing_extensions import Literal, TypeAlias
from typing_extensions import Final, Literal, TypeAlias

__version__: str
__version__: Final[str]

QUOTE_ALL: Literal[1]
QUOTE_MINIMAL: Literal[0]
Expand Down
6 changes: 3 additions & 3 deletions stdlib/_decimal.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@ import sys
from collections.abc import Container, Sequence
from types import TracebackType
from typing import Any, ClassVar, NamedTuple, overload
from typing_extensions import Literal, Self, TypeAlias
from typing_extensions import Final, Literal, Self, TypeAlias

_Decimal: TypeAlias = Decimal | int
_DecimalNew: TypeAlias = Decimal | float | str | tuple[int, Sequence[int], int]
_ComparableNum: TypeAlias = Decimal | float | numbers.Rational

__version__: str
__libmpdec_version__: str
__version__: Final[str]
__libmpdec_version__: Final[str]

class DecimalTuple(NamedTuple):
sign: int
Expand Down
3 changes: 2 additions & 1 deletion stdlib/_heapq.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
from typing import Any, TypeVar
from typing_extensions import Final

_T = TypeVar("_T")

__about__: str
__about__: Final[str]

def heapify(__heap: list[Any]) -> None: ...
def heappop(__heap: list[_T]) -> _T: ...
Expand Down
3 changes: 2 additions & 1 deletion stdlib/cgitb.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@ from _typeshed import OptExcInfo, StrOrBytesPath
from collections.abc import Callable
from types import FrameType, TracebackType
from typing import IO, Any
from typing_extensions import Final

__UNDEF__: object # undocumented sentinel
__UNDEF__: Final[object] # undocumented sentinel

def reset() -> str: ... # undocumented
def small(text: str) -> str: ... # undocumented
Expand Down
3 changes: 2 additions & 1 deletion stdlib/heapq.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,13 @@ from _heapq import *
from _typeshed import SupportsRichComparison
from collections.abc import Callable, Iterable
from typing import Any, TypeVar
from typing_extensions import Final

__all__ = ["heappush", "heappop", "heapify", "heapreplace", "merge", "nlargest", "nsmallest", "heappushpop"]

_S = TypeVar("_S")

__about__: str
__about__: Final[str]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing an opportunity to type this as

Literal["""\
Heap queues
[explanation by François Pinard]
Heaps are arrays for which a[k] <= a[2*k+1] and a[k] <= a[2*k+2] for
all k, counting elements from 0.  For the sake of comparison,
non-existing elements are considered to be infinite.  The interesting
property of a heap is that a[0] is always its smallest element.
The strange invariant above is meant to be an efficient memory
representation for a tournament.  The numbers below are `k', not a[k]:
                                   0
                  1                                 2
          3               4                5               6
      7       8       9       10      11      12      13      14
    15 16   17 18   19 20   21 22   23 24   25 26   27 28   29 30
In the tree above, each cell `k' is topping `2*k+1' and `2*k+2'.  In
a usual binary tournament we see in sports, each cell is the winner
over the two cells it tops, and we can trace the winner down the tree
to see all opponents s/he had.  However, in many computer applications
of such tournaments, we do not need to trace the history of a winner.
To be more memory efficient, when a winner is promoted, we try to
replace it by something else at a lower level, and the rule becomes
that a cell and the two cells it tops contain three different items,
but the top cell "wins" over the two topped cells.
If this heap invariant is protected at all time, index 0 is clearly
the overall winner.  The simplest algorithmic way to remove it and
find the "next" winner is to move some loser (let's say cell 30 in the
diagram above) into the 0 position, and then percolate this new 0 down
the tree, exchanging values, until the invariant is re-established.
This is clearly logarithmic on the total number of items in the tree.
By iterating over all items, you get an O(n ln n) sort.
A nice feature of this sort is that you can efficiently insert new
items while the sort is going on, provided that the inserted items are
not "better" than the last 0'th element you extracted.  This is
especially useful in simulation contexts, where the tree holds all
incoming events, and the "win" condition means the smallest scheduled
time.  When an event schedule other events for execution, they are
scheduled into the future, so they can easily go into the heap.  So, a
heap is a good structure for implementing schedulers (this is what I
used for my MIDI sequencer :-).
Various structures for implementing schedulers have been extensively
studied, and heaps are good for this, as they are reasonably speedy,
the speed is almost constant, and the worst case is not much different
than the average case.  However, there are other representations which
are more efficient overall, yet the worst cases might be terrible.
Heaps are also very useful in big disk sorts.  You most probably all
know that a big sort implies producing "runs" (which are pre-sorted
sequences, which size is usually related to the amount of CPU memory),
followed by a merging passes for these runs, which merging is often
very cleverly organised[1].  It is very important that the initial
sort produces the longest runs possible.  Tournaments are a good way
to that.  If, using all the memory available to hold a tournament, you
replace and percolate items that happen to fit the current run, you'll
produce runs which are twice the size of the memory for random input,
and much better for input fuzzily ordered.
Moreover, if you output the 0'th item on disk and get an input which
may not fit in the current tournament (because the value "wins" over
the last output value), it cannot fit in the heap, so the size of the
heap decreases.  The freed memory could be cleverly reused immediately
for progressively building a second heap, which grows at exactly the
same rate the first heap is melting.  When the first heap completely
vanishes, you switch heaps and start a new run.  Clever and quite
effective!
In a word, heaps are useful memory structures to know.  I use them in
a few applications, and I think it is good to keep a `heap' module
around. :-)
--------------------
[1] The disk balancing algorithms which are current, nowadays, are
more annoying than clever, and this is a consequence of the seeking
capabilities of the disks.  On devices which cannot seek, like big
tape drives, the story was quite different, and one had to be very
clever to ensure (far in advance) that each tape movement will be the
most effective possible (that is, will best participate at
"progressing" the merge).  Some tapes were even able to read
backwards, and this was also used to avoid the rewinding time.
Believe me, real good tape sorts were quite spectacular to watch!
From all times, sorting has always been a Great Art! :-)
"""]

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something tells me this is on the same level as "adding docstrings to stubs" 😅


def merge(
*iterables: Iterable[_S], key: Callable[[_S], SupportsRichComparison] | None = None, reverse: bool = False
Expand Down
10 changes: 5 additions & 5 deletions stdlib/pydoc.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,16 @@ from collections.abc import Callable, Container, Mapping, MutableMapping
from reprlib import Repr
from types import MethodType, ModuleType, TracebackType
from typing import IO, Any, AnyStr, NoReturn, TypeVar
from typing_extensions import TypeGuard
from typing_extensions import Final, TypeGuard

__all__ = ["help"]

_T = TypeVar("_T")

__author__: str
__date__: str
__version__: str
__credits__: str
__author__: Final[str]
__date__: Final[str]
__version__: Final[str]
__credits__: Final[str]

def pathdirs() -> list[str]: ...
def getdoc(object: object) -> str: ...
Expand Down
11 changes: 6 additions & 5 deletions stdlib/sys.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ from importlib.machinery import ModuleSpec
from io import TextIOWrapper
from types import FrameType, ModuleType, TracebackType
from typing import Any, NoReturn, Protocol, TextIO, TypeVar, overload
from typing_extensions import Literal, TypeAlias, final
from typing_extensions import Final, Literal, TypeAlias, final

_T = TypeVar("_T")

Expand Down Expand Up @@ -62,9 +62,10 @@ stdout: TextIO
stderr: TextIO
if sys.version_info >= (3, 10):
stdlib_module_names: frozenset[str]
__stdin__: TextIOWrapper
__stdout__: TextIOWrapper
__stderr__: TextIOWrapper

__stdin__: Final[TextIOWrapper] # Contains the original value of stdin
__stdout__: Final[TextIOWrapper] # Contains the original value of stdout
__stderr__: Final[TextIOWrapper] # Contains the original value of stderr
tracebacklimit: int
version: str
api_version: int
Expand Down Expand Up @@ -278,7 +279,7 @@ if sys.platform == "win32":
def intern(__string: str) -> str: ...
def is_finalizing() -> bool: ...

__breakpointhook__: Any # contains the original value of breakpointhook
__breakpointhook__ = breakpointhook # Contains the original value of breakpointhook
AlexWaygood marked this conversation as resolved.
Show resolved Hide resolved

def breakpointhook(*args: Any, **kwargs: Any) -> Any: ...

Expand Down
4 changes: 2 additions & 2 deletions stdlib/unittest/mock.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ from collections.abc import Awaitable, Callable, Coroutine, Iterable, Mapping, S
from contextlib import _GeneratorContextManager
from types import TracebackType
from typing import Any, Generic, TypeVar, overload
from typing_extensions import Literal, Self, TypeAlias
from typing_extensions import Final, Literal, Self, TypeAlias

_T = TypeVar("_T")
_TT = TypeVar("_TT", bound=type[Any])
Expand Down Expand Up @@ -47,7 +47,7 @@ else:
"seal",
)

__version__: str
__version__: Final[str]

FILTER_DIR: Any

Expand Down