crontab: improve types, update to 2.7 (#9392)

https://gitlab.com/doctormo/python-crontab/-/blob/v2.7.0/crontab.py

Closes #9391

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

stubs/python-crontab/@tests/stubtest_allowlist.txt

@@ -1,2 +1,5 @@
 # Re-export:
 crontabs.X_OK
+
+# stub does not have *args argument "args", but function doesn't actually accept positional args
+crontab.CronTab.remove_all

stubs/python-crontab/METADATA.toml

@@ -1,4 +1,4 @@
-version = "2.6.*"
+version = "2.7.*"
 
 [tool.stubtest]
 ignore_missing_stub = false

stubs/python-crontab/crontab.pyi

@@ -2,11 +2,13 @@ import re
 import subprocess
 from _typeshed import Incomplete, Self
 from collections import OrderedDict
-from collections.abc import Callable, Generator
+from collections.abc import Callable, Generator, Iterator
 from logging import Logger
 from types import TracebackType
 from typing import Any
-from typing_extensions import Literal
+from typing_extensions import Literal, SupportsIndex
+
+from cronlog import CronLog
 
 __pkgname__: str
 ITEMREX: re.Pattern[str]
@@ -31,54 +33,63 @@ def open_pipe(cmd: str, *args: str, **flags) -> subprocess.Popen[Any]: ...
 
 class CronTab:
     lines: Incomplete
-    crons: Incomplete
-    filen: Incomplete
+    crons: list[CronItem]
+    filen: str | None
     cron_command: Incomplete
-    env: Incomplete
+    env: OrderedVariableList
     root: bool
-    intab: Incomplete
+    intab: str | None
     def __init__(
-        self,
-        user: bool | str | None = ...,
-        tab: Incomplete | None = ...,
-        tabfile: Incomplete | None = ...,
-        log: Incomplete | None = ...,
+        self, user: bool | str | None = ..., tab: str | None = ..., tabfile: str | None = ..., log: str | None = ...
     ) -> None: ...
     def __enter__(self: Self) -> Self: ...
     def __exit__(
         self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None
     ) -> None: ...
     @property
-    def log(self): ...
+    def log(self) -> CronLog: ...
     @property
     def user(self) -> str | None: ...
     @property
-    def user_opt(self): ...
-    def read(self, filename: Incomplete | None = ...) -> None: ...
-    def append(self, item, line: str = ..., read: bool = ...) -> None: ...
-    def write(self, filename: Incomplete | None = ..., user: Incomplete | None = ..., errors: bool = ...) -> None: ...
-    def write_to_user(self, user: bool = ...): ...
+    def user_opt(self) -> dict[str, str]: ...
+    def read(self, filename: str | None = ...) -> None: ...
+    def append(
+        self,
+        item: CronItem,
+        line: str = ...,
+        read: bool = ...,
+        before: str | re.Pattern[str] | list[CronItem] | tuple[CronItem, ...] | Generator[CronItem, Any, Any] | None = ...,
+    ) -> None: ...
+    def write(self, filename: str | None = ..., user: bool | str | None = ..., errors: bool = ...) -> None: ...
+    def write_to_user(self, user: bool | str = ...) -> None: ...
     def run_pending(self, **kwargs) -> Generator[Incomplete, None, None]: ...
     def run_scheduler(self, timeout: int = ..., **kwargs) -> Generator[Incomplete, None, None]: ...
-    def render(self, errors: bool = ..., specials: bool = ...): ...
-    def new(self, command: str = ..., comment: str = ..., user: Incomplete | None = ..., pre_comment: bool = ...) -> CronItem: ...
-    def find_command(self, command) -> Generator[Incomplete, None, None]: ...
-    def find_comment(self, comment) -> Generator[Incomplete, None, None]: ...
-    def find_time(self, *args) -> Generator[Incomplete, None, None]: ...
+    def render(self, errors: bool = ..., specials: bool = ...) -> str: ...
+    def new(
+        self,
+        command: str = ...,
+        comment: str = ...,
+        user: str | None = ...,
+        pre_comment: bool = ...,
+        before: str | re.Pattern[str] | list[CronItem] | tuple[CronItem, ...] | Generator[CronItem, Any, Any] | None = ...,
+    ) -> CronItem: ...
+    def find_command(self, command: str | re.Pattern[str]) -> Generator[CronItem, None, None]: ...
+    def find_comment(self, comment: str | re.Pattern[str]) -> Generator[CronItem, None, None]: ...
+    def find_time(self, *args) -> Generator[CronItem, None, None]: ...
     @property
     def commands(self) -> Generator[Incomplete, None, None]: ...
     @property
     def comments(self) -> Generator[Incomplete, None, None]: ...
-    def remove_all(self, *args, **kwargs): ...
-    def remove(self, *items): ...
-    def __iter__(self): ...
-    def __getitem__(self, i): ...
+    def remove_all(self, *, command: str | re.Pattern[str] = ..., comment: str | re.Pattern[str] = ..., time=...) -> int: ...
+    def remove(self, *items: CronItem | list[CronItem] | tuple[CronItem, ...] | Generator[CronItem, Any, Any]) -> int: ...
+    def __iter__(self) -> Iterator[CronItem]: ...
+    def __getitem__(self, i: SupportsIndex) -> CronItem: ...
     def __unicode__(self) -> str: ...
     def __len__(self) -> int: ...
 
 class CronItem:
     cron: Incomplete
-    user: Incomplete
+    user: str | None
     valid: bool
     enabled: bool
     special: bool
@@ -90,13 +101,11 @@ class CronItem:
     marker: Incomplete
     stdin: Incomplete
     slices: Incomplete
-    def __init__(
-        self, command: str = ..., comment: str = ..., user: Incomplete | None = ..., pre_comment: bool = ...
-    ) -> None: ...
+    def __init__(self, command: str = ..., comment: str = ..., user: str | None = ..., pre_comment: bool = ...) -> None: ...
     def __hash__(self) -> int: ...
     def __eq__(self, other: object) -> bool: ...
     @classmethod
-    def from_line(cls: type[Self], line: str, user: Incomplete | None = ..., cron: Incomplete | None = ...) -> Self: ...
+    def from_line(cls: type[Self], line: str, user: str | None = ..., cron: Incomplete | None = ...) -> Self: ...
     def delete(self) -> None: ...
     def set_command(self, cmd: str, parse_stdin: bool = ...) -> None: ...
     def set_comment(self, cmt: str, pre_comment: bool = ...) -> None: ...
@@ -109,10 +118,10 @@ class CronItem:
     def every(self, unit: int = ...): ...
     def setall(self, *args: Any): ...
     def clear(self): ...
-    def frequency(self, year: Incomplete | None = ...): ...
-    def frequency_per_year(self, year: Incomplete | None = ...): ...
-    def frequency_per_day(self): ...
-    def frequency_per_hour(self): ...
+    def frequency(self, year: int | None = ...) -> int: ...
+    def frequency_per_year(self, year: int | None = ...) -> int: ...
+    def frequency_per_day(self) -> int: ...
+    def frequency_per_hour(self) -> int: ...
     def run_pending(self, now: Incomplete | None = ...): ...
     def run(self): ...
     def schedule(self, date_from: Incomplete | None = ...): ...
@@ -120,27 +129,27 @@ class CronItem:
     @property
     def log(self): ...
     @property
-    def minute(self): ...
+    def minute(self) -> CronSlice: ...
     @property
-    def minutes(self): ...
+    def minutes(self) -> CronSlice: ...
     @property
-    def hour(self): ...
+    def hour(self) -> CronSlice: ...
     @property
-    def hours(self): ...
+    def hours(self) -> CronSlice: ...
     @property
-    def day(self): ...
+    def day(self) -> CronSlice: ...
     @property
-    def dom(self): ...
+    def dom(self) -> CronSlice: ...
     @property
-    def month(self): ...
+    def month(self) -> CronSlice: ...
     @property
-    def months(self): ...
+    def months(self) -> CronSlice: ...
     @property
-    def dow(self): ...
+    def dow(self) -> CronSlice: ...
     def __len__(self) -> int: ...
-    def __getitem__(self, key: str): ...
-    def __lt__(self, value): ...
-    def __gt__(self, value): ...
+    def __getitem__(self, key: SupportsIndex) -> CronSlice: ...
+    def __lt__(self, value) -> bool: ...
+    def __gt__(self, value) -> bool: ...
     def __unicode__(self) -> str: ...
 
 class Every:
@@ -160,10 +169,10 @@ class CronSlices(list[CronSlice]):
     def clean_render(self) -> str: ...
     def render(self, specials: bool = ...) -> str: ...
     def clear(self) -> None: ...
-    def frequency(self, year: Incomplete | None = ...): ...
-    def frequency_per_year(self, year: Incomplete | None = ...): ...
-    def frequency_per_day(self): ...
-    def frequency_per_hour(self): ...
+    def frequency(self, year: int | None = ...) -> int: ...
+    def frequency_per_year(self, year: int | None = ...) -> int: ...
+    def frequency_per_day(self) -> int: ...
+    def frequency_per_hour(self) -> int: ...
     def __eq__(self, arg: object) -> bool: ...
 
 class SundayError(KeyError): ...