annotate mercurial/interfaces/status.py @ 52451:f5d134e57f51

scmutil: explicitly subclass the `Status` protocol We shouldn't have to explicitly subclass, but PyCharm has a nifty feature that puts a jump point in the gutter to navigate back and forth between the base class and subclasses (and override functions and base class functions) when there's an explicit subclassing. Additionally, PyCharm will immediately flag signature mismatches without a 40m pytype run. It was also hoped that with explicit subclassing, we would get interface checking for free. Unfortunately when I tried adding methods and fields to the Protocol class to test this theory, pytype happily accepted an assignment of the concrete class without the new field and methods, to a variable annotated with the Protocol class with them. It appears that this is what happens when explicit subclassing is used, since dropping that caused pytype to complain. By making the methods abstract here like the `mercurial.wireprototypes` classes in fd200f5bcaea, pytype will complain in that case outlined that a subclass with abstract methods (not replaced by the subclass itself) cannot be instantiated. That doesn't help with the fields. Making an `abstractproperty` likely isn't appropriate in general, because that effectively becomes a read-only property. This seems like a pretty gaping hole, but I think the benefits of explicit subclassing are worth the risk. (Though I guess it shouldn't be surprising, because a class can be both a Protocol and an implementation, so subclassing something with an empty body method doesn't really signal that it is a requirement for the subclass to implement.)
author Matt Harbison <matt_harbison@yahoo.com>
date Mon, 09 Dec 2024 00:01:03 -0500
parents a1c0f19e7cb4
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
52450
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
1 # status.py - Type annotations for status related objects
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
2 #
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
3 # Copyright Matt Harbison <mharbison72@gmail.com>
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
4 #
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
5 # This software may be used and distributed according to the terms of the
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
6 # GNU General Public License version 2 or any later version.
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
7
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
8 from __future__ import annotations
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
9
52451
f5d134e57f51 scmutil: explicitly subclass the `Status` protocol
Matt Harbison <matt_harbison@yahoo.com>
parents: 52450
diff changeset
10 import abc
f5d134e57f51 scmutil: explicitly subclass the `Status` protocol
Matt Harbison <matt_harbison@yahoo.com>
parents: 52450
diff changeset
11
52450
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
12 from typing import (
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
13 Iterator,
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
14 Protocol,
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
15 )
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
16
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
17
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
18 class Status(Protocol):
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
19 """Struct with a list of files per status.
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
20
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
21 The 'deleted', 'unknown' and 'ignored' properties are only
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
22 relevant to the working copy.
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
23 """
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
24
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
25 modified: list[bytes]
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
26 """The list of files with modifications."""
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
27
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
28 added: list[bytes]
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
29 """The list of files that started being tracked."""
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
30
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
31 removed: list[bytes]
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
32 """The list of files that stopped being tracked."""
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
33
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
34 deleted: list[bytes]
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
35 """The list of files in the working directory that are deleted from the
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
36 file system (but not in the removed state)."""
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
37
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
38 unknown: list[bytes]
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
39 """The list of files in the working directory that are not tracked."""
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
40
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
41 ignored: list[bytes]
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
42 """The list of files in the working directory that are ignored."""
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
43
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
44 clean: list[bytes]
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
45 """The list of files that are not in any other state."""
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
46
52451
f5d134e57f51 scmutil: explicitly subclass the `Status` protocol
Matt Harbison <matt_harbison@yahoo.com>
parents: 52450
diff changeset
47 @abc.abstractmethod
52450
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
48 def __iter__(self) -> Iterator[list[bytes]]:
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
49 """Iterates over each of the categories of file lists."""
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
50
52451
f5d134e57f51 scmutil: explicitly subclass the `Status` protocol
Matt Harbison <matt_harbison@yahoo.com>
parents: 52450
diff changeset
51 @abc.abstractmethod
52450
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
52 def __repr__(self) -> str:
a1c0f19e7cb4 interfaces: add a Protocol class for `scmutil.status`
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
53 """Creates a string representation of the file lists."""