Add type stubs for P4 and P4API

P4.pyi

@@ -0,0 +1,285 @@
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from types import TracebackType
+from typing import (
+    Any,
+    ClassVar,
+    Final,
+    Literal,
+    NoReturn,
+    TypedDict,
+    overload,
+    type_check_only,
+)
+
+import sys
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+import P4API
+
+class P4Exception(Exception):
+    value: str
+    errors: list[str] | None
+    warnings: list[str] | None
+    def __init__(self, value: str | tuple[str, list[str], list[str]]) -> None: ...
+
+class Spec(dict[str, str | list[str]]):
+    def __init__(self, fieldmap: Mapping[str, str] | None = None) -> None: ...
+    def __getattr__(self, attr: str) -> str | list[str]: ...
+    def __setattr__(self, attr: str, value: str | list[str]) -> None: ...
+    def __setitem__(self, key: str, value: str | list[str]) -> None: ...
+    def permitted_fields(self) -> Mapping[str, str] | None: ...
+
+class Integration:
+    how: str
+    file: str
+    srev: int
+    erev: int
+    def __init__(self, how: str, file: str, srev: int, erev: int) -> None: ...
+
+class Revision:
+    depotFile: DepotFile
+    integrations: list[Integration]
+    rev: int | None
+    change: int | None
+    action: Literal["add", "edit", "delete", "branch", "integrate"] | None
+    type: str | None
+    time: datetime | None
+    user: str | None
+    client: str | None
+    desc: str | None
+    digest: str | None
+    fileSize: str | None
+    def __init__(self, depotFile: DepotFile) -> None: ...
+    def integration(self, how: str, file: str, srev: int, erev: int) -> Integration: ...
+    def each_integration(self) -> Iterator[Integration]: ...
+
+class DepotFile:
+    depotFile: str
+    revisions: list[Revision]
+    def __init__(self, name: str) -> None: ...
+    def new_revision(self) -> Revision: ...
+    def each_revision(self) -> Iterator[Revision]: ...
+    def str_revision(self, rev: Revision, revFormat: str, changeFormat: str) -> str: ...
+    def str_integration(self, integ: Integration) -> str: ...
+
+class Resolver:
+    def resolve(self, mergeInfo: P4API.P4MergeData, /) -> P4API.ResolveAction: ...
+    def actionResolve(
+        self, mergeInfo: P4API.P4ActionMergeData, /
+    ) -> P4API.ResolveAction: ...
+
+class OutputHandler:
+    REPORT: ClassVar = 0
+    HANDLED: ClassVar = 1
+    CANCEL: ClassVar = 2
+
+    def outputText(self, s: str, /) -> _HandlerResult: ...
+    def outputBinary(self, b: bytes, /) -> _HandlerResult: ...
+    def outputStat(self, h: Spec | dict[str, Any], /) -> _HandlerResult: ...
+    def outputInfo(self, i: str, /) -> _HandlerResult: ...
+    def outputMessage(self, e: P4API.P4Message, /) -> _HandlerResult: ...
+
+_HandlerResult: TypeAlias = Literal[0, 1, 2]
+
+class ReportHandler(OutputHandler): ...
+
+class FilelogOutputHandler(OutputHandler):
+    def outputFilelog(self, f: DepotFile) -> _HandlerResult: ...
+
+class Progress:
+    TYPE_SENDFILE: ClassVar = 1
+    TYPE_RECEIVEFILE: ClassVar = 2
+    TYPE_TRANSFER: ClassVar = 3
+    TYPE_COMPUTATION: ClassVar = 4
+
+    UNIT_PERCENT: ClassVar = 1
+    UNIT_FILES: ClassVar = 2
+    UNIT_KBYTES: ClassVar = 3
+    UNIT_MBYTES: ClassVar = 4
+
+    def init(self, type: Literal[1, 2, 3, 4, 5, 6, 7]) -> None: ...
+    def setDescription(
+        self, description: str, units: Literal[0, 1, 2, 3, 4, 5, 6, 7]
+    ) -> None: ...
+    def setTotal(self, total: int) -> None: ...
+    def update(self, position: int) -> None: ...
+    def done(self, fail: bool | int) -> None: ...
+
+class TextProgress(Progress):
+    TYPES: Final[list[str]]
+    UNITS: Final[list[str]]
+
+    def init(self, type: Literal[1, 2, 3, 4, 5, 6, 7]) -> None: ...
+    def setDescription(
+        self, description: str, units: Literal[0, 1, 2, 3, 4, 5, 6, 7]
+    ) -> None: ...
+    def setTotal(self, total: int) -> None: ...
+    def update(self, position: int) -> None: ...
+    def done(self, fail: bool | int) -> None: ...
+
+def processFilelog(h: Mapping[str, Any]) -> DepotFile: ...
+
+class Map(P4API.P4Map):
+    @overload
+    def __init__(self) -> None: ...
+    @overload
+    def __init__(self, maps: list[str]) -> None: ...
+    @overload
+    def __init__(self, map: str) -> None: ...
+    @overload
+    def __init__(self, lhr: str, rhs: str) -> None: ...
+
+    LEFT2RIGHT: ClassVar = True
+    RIGHT2LEFT: ClassVar = False
+
+    def is_empty(self) -> bool: ...
+    def includes(self, path: str, left_to_right: bool = True, /) -> bool: ...
+    def reverse(self) -> Map: ...
+    @overload
+    def insert(self, maps: list[str], /) -> None: ...
+    @overload
+    def insert(self, lhr: str, rhs: str | None = None, /) -> None: ...
+
+class P4(P4API.P4Adapter):
+    # See https://help.perforce.com/helix-core/apis/p4python/current/Content/P4Python/python.p4.html
+    # for documented public API.  Most documented attributes are inherited from P4API, and are annotated there instead.
+
+    RAISE_ALL: ClassVar = 2
+    RAISE_ERROR: ClassVar = 1
+    RAISE_ERRORS: ClassVar = 1
+    RAISE_NONE: ClassVar = 0
+
+    EV_USAGE: ClassVar = 0x01
+    EV_UNKNOWN: ClassVar = 0x02
+    EV_CONTEXT: ClassVar = 0x03
+    EV_ILLEGAL: ClassVar = 0x04
+    EV_NOTYET: ClassVar = 0x05
+    EV_PROTECT: ClassVar = 0x06
+
+    EV_EMPTY: ClassVar = 0x11
+
+    EV_FAULT: ClassVar = 0x21
+    EV_CLIENT: ClassVar = 0x22
+    EV_ADMIN: ClassVar = 0x23
+    EV_CONFIG: ClassVar = 0x24
+    EV_UPGRADE: ClassVar = 0x25
+    EV_COMM: ClassVar = 0x26
+    EV_TOOBIG: ClassVar = 0x27
+
+    E_EMPTY: ClassVar = 0
+    E_INFO: ClassVar = 1
+    E_WARN: ClassVar = 2
+    E_FAILED: ClassVar = 3
+    E_FATAL: ClassVar = 4
+
+    specfields: Final[dict[str, tuple[str, str]]]
+
+    @classmethod
+    def identify(cls) -> str: ...
+    def __getattr__(self, name: str) -> Any: ...
+    def __init__(self, **kwargs: Any) -> None: ...
+    def is_ignored(self, path: str | Path) -> bool: ...
+    def log_messages(self) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> Literal[False]: ...
+    @contextmanager
+    def while_tagged(self, t: bool) -> Iterator[None]: ...
+    @contextmanager
+    def at_exception_level(self, e: Literal[0, 1, 2]) -> Iterator[None]: ...
+    @contextmanager
+    def using_handler(self, c: OutputHandler) -> Iterator[None]: ...
+    @contextmanager
+    def saved_context(self, **kargs: Any) -> Iterator[None]: ...
+    @contextmanager
+    def temp_client(self, prefix: str, template: str) -> Iterator[str]: ...
+    def run(self, /, *args: Any, **kargs: Any) -> _P4Result: ...
+
+    # Command methods that have explicit implementations with additional processing
+    def run_submit(
+        self,
+        *args: Any | Spec | dict[str, str | list[str]],
+        progress: Progress | None = None,
+        **kargs: Any,
+    ) -> _P4Result: ...
+    def run_shelve(
+        self,
+        *args: Any | Spec | dict[str, str | list[str]],
+        **kargs: Any,
+    ) -> _P4Result: ...
+    @overload
+    def delete_shelve(
+        self,
+        changelist_number: int | str,
+        /,
+        *args: str,
+        **kargs,
+    ) -> list[str]: ...
+    @overload
+    def delete_shelve(self, *args: Any, **kargs: Any) -> list[str]: ...
+    def run_login(self, *args: Any, **kargs: Any) -> _P4Result: ...
+    def run_password(
+        self, oldpass: str, newpass: str, *args: Any, **kargs: Any
+    ) -> list[str]: ...
+    def run_filelog(self, *args: Any, **kwargs: Any) -> list[DepotFile | str]: ...
+    def run_print(self, *args: Any, **kargs) -> list[str | bytes]: ...
+    def run_resolve(
+        self,
+        *args: Any,
+        resolver: Resolver | None = None,
+        **kargs: Any,
+    ) -> _P4Result: ...
+    def run_tickets(self) -> list[TicketInfo]: ...
+    def run_init(self, *args: Any, **kargs: Any) -> NoReturn: ...
+    def run_clone(self, *args: Any, **kargs: Any) -> NoReturn: ...
+
+_P4Result: TypeAlias = list[dict[str, Any] | Spec | str]
+
+@type_check_only
+class TicketInfo(TypedDict):
+    Host: str
+    User: str
+    Ticket: str
+
+class PyKeepAlive:
+    def __init__(self) -> None: ...
+    def isAlive(self) -> Literal[0, 1] | bool: ...
+
+def init(
+    user: str | None = None,
+    client: str | None = None,
+    directory: str | None = None,
+    port: str | None = None,
+    casesensitive: bool | None = None,
+    unicode: bool | None = None,
+    **kwargs: Any,
+) -> P4: ...
+def clone(
+    user: str | None = None,
+    client: str | None = None,
+    directory: str | None = None,
+    depth: int | None = None,
+    verbose: bool | None = None,
+    port: str | None = None,
+    remote: str | None = None,
+    file: str | None = None,
+    noarchive: bool | None = None,
+    progress: Progress | None = None,
+    **kwargs: Any,
+) -> P4: ...