From f3f648e84f78c6983f8fc1598d570b482fad7638 Mon Sep 17 00:00:00 2001 From: Kamil Braun Date: Wed, 18 Nov 2026 18:56:23 +0100 Subject: [PATCH] Add stubs for RouterOS-api RouterOS-api 0.21 ships no type information; this adds partial stubs for its connection pool and API, resources, field structures, queries, sentences, socket wrapper, error parsers and exceptions. Upstream: [the source](https://github.com/socialwifi/RouterOS-api/tree/master/routeros_api) and [its README](https://github.com/socialwifi/RouterOS-api#readme). Written with Claude Code (Claude Opus 5.5). --- .../@tests/test_cases/check_resources.py | 28 ++++ stubs/RouterOS-api/METADATA.toml | 6 + stubs/RouterOS-api/routeros_api/__init__.pyi | 8 ++ stubs/RouterOS-api/routeros_api/api.pyi | 81 ++++++++++++ .../api_communicator/__init__.pyi | 3 + .../routeros_api/api_communicator/base.pyi | 29 +++++ .../RouterOS-api/routeros_api/api_socket.pyi | 35 +++++ .../routeros_api/api_structure.pyi | 67 ++++++++++ .../communication_exception_parsers.pyi | 15 +++ .../RouterOS-api/routeros_api/exceptions.pyi | 12 ++ stubs/RouterOS-api/routeros_api/query.pyi | 42 ++++++ stubs/RouterOS-api/routeros_api/resource.pyi | 123 ++++++++++++++++++ stubs/RouterOS-api/routeros_api/sentence.pyi | 35 +++++ 13 files changed, 484 insertions(+) create mode 100644 stubs/RouterOS-api/@tests/test_cases/check_resources.py create mode 100644 stubs/RouterOS-api/METADATA.toml create mode 100644 stubs/RouterOS-api/routeros_api/__init__.pyi create mode 100644 stubs/RouterOS-api/routeros_api/api.pyi create mode 100644 stubs/RouterOS-api/routeros_api/api_communicator/__init__.pyi create mode 100644 stubs/RouterOS-api/routeros_api/api_communicator/base.pyi create mode 100644 stubs/RouterOS-api/routeros_api/api_socket.pyi create mode 100644 stubs/RouterOS-api/routeros_api/api_structure.pyi create mode 100644 stubs/RouterOS-api/routeros_api/communication_exception_parsers.pyi create mode 100644 stubs/RouterOS-api/routeros_api/exceptions.pyi create mode 100644 stubs/RouterOS-api/routeros_api/query.pyi create mode 100644 stubs/RouterOS-api/routeros_api/resource.pyi create mode 100644 stubs/RouterOS-api/routeros_api/sentence.pyi diff --git a/stubs/RouterOS-api/@tests/test_cases/check_resources.py b/stubs/RouterOS-api/@tests/test_cases/check_resources.py new file mode 100644 index 000000000000..9c36a06158b2 --- /dev/null +++ b/stubs/RouterOS-api/@tests/test_cases/check_resources.py @@ -0,0 +1,28 @@ +from __future__ import annotations + +from datetime import timedelta +from typing import Any +from typing_extensions import assert_type + +from routeros_api import RouterOsApiPool +from routeros_api.api_structure import BooleanField, IntegerField, StringField, TimedeltaField +from routeros_api.resource import RouterOsResource + +api = RouterOsApiPool("192.0.2.1").get_api() + +assert_type(api.get_resource("/ip/address"), RouterOsResource[str, str]) + +# A structure of one field type carries that type into the resource. +flags = api.get_resource("/interface", structure={"disabled": BooleanField(), "running": BooleanField()}) +assert_type(flags, RouterOsResource[bool, bool]) +assert_type(flags.get(disabled=True)[0]["running"], bool) + +# None is sent without a value as an argument, refused as a query, and decoded from "none". +timeouts = api.get_resource("/ip/hotspot/user", structure={"limit-uptime": TimedeltaField()}) +timeouts.set(**{"limit-uptime": None}) +timeouts.get(**{"limit-uptime": None}) # type: ignore +assert_type(timeouts.get()[0]["limit-uptime"], timedelta | None) + +# A structure mixing field types gives a resource whose values' types aren't tracked. +mixed = api.get_resource("/ip/address", structure={"disabled": BooleanField(), "comment": StringField(), "mtu": IntegerField()}) +assert_type(mixed, RouterOsResource[Any, Any]) # Any: the stub's type for a mixed structure diff --git a/stubs/RouterOS-api/METADATA.toml b/stubs/RouterOS-api/METADATA.toml new file mode 100644 index 000000000000..02e4222a0628 --- /dev/null +++ b/stubs/RouterOS-api/METADATA.toml @@ -0,0 +1,6 @@ +version = "0.21.*" +upstream-repository = "https://github.com/socialwifi/RouterOS-api" +partial-stub = true + +[tool.stubtest] +ignore-missing-stub = true diff --git a/stubs/RouterOS-api/routeros_api/__init__.pyi b/stubs/RouterOS-api/routeros_api/__init__.pyi new file mode 100644 index 000000000000..583dea267054 --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/__init__.pyi @@ -0,0 +1,8 @@ +from _typeshed import Incomplete + +from routeros_api import api_structure as api_structure, query as query +from routeros_api.api import RouterOsApiPool as RouterOsApiPool, connect as connect + +__all__ = ["connect", "RouterOsApiPool", "query", "api_structure"] + +def __getattr__(name: str) -> Incomplete: ... diff --git a/stubs/RouterOS-api/routeros_api/api.pyi b/stubs/RouterOS-api/routeros_api/api.pyi new file mode 100644 index 000000000000..3303aafdeb6c --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/api.pyi @@ -0,0 +1,81 @@ +import ssl +from collections.abc import Mapping +from typing import Any, TypeVar, overload + +from routeros_api.api_socket import DummySocket, SocketWrapper +from routeros_api.api_structure import _Field +from routeros_api.communication_exception_parsers import ExceptionHandler +from routeros_api.resource import RouterOsBinaryResource, RouterOsResource, _Communicator + +_In = TypeVar("_In") +_Out = TypeVar("_Out") + +def connect( # undocumented + host: str, + username: str | bytes = "admin", + password: str | bytes = "", + port: int | None = None, + plaintext_login: bool = False, + use_ssl: bool = False, + ssl_verify: bool = True, + ssl_verify_hostname: bool = True, + ssl_context: ssl.SSLContext | None = None, +) -> RouterOsApi: ... + +class RouterOsApiPool: + socket_timeout: float | None # undocumented + host: str # undocumented + username: str | bytes # undocumented + password: str | bytes # undocumented + port: int # undocumented + plaintext_login: bool # undocumented + use_ssl: bool # undocumented + ssl_verify: bool # undocumented + ssl_verify_hostname: bool # undocumented + ssl_context: ssl.SSLContext | None # undocumented + connected: bool # undocumented + # A DummySocket while not connected. + socket: DummySocket | SocketWrapper # undocumented + communication_exception_parser: ExceptionHandler # undocumented + # Set by get_api, absent before its first call. + api: RouterOsApi # undocumented + def __init__( + self, + host: str, + username: str | bytes = "admin", + password: str | bytes = "", + port: int | None = None, + plaintext_login: bool = False, + use_ssl: bool = False, + ssl_verify: bool = True, + ssl_verify_hostname: bool = True, + ssl_context: ssl.SSLContext | None = None, + ) -> None: ... + def get_api(self) -> RouterOsApi: ... + def disconnect(self) -> None: ... + def set_timeout(self, socket_timeout: float | None) -> None: ... # undocumented + +class RouterOsApi: + communicator: _Communicator # undocumented + def __init__(self, communicator: _Communicator) -> None: ... + def login(self, login: str | bytes, password: str | bytes, plaintext_login: bool) -> None: ... # undocumented + + # None selects the default structure, every field text. + @overload + def get_resource(self, path: str, structure: None = None) -> RouterOsResource[str, str]: ... + @overload + def get_resource(self, path: str, structure: Mapping[str, _Field[_In, _Out]]) -> RouterOsResource[_In, _Out]: ... + # A structure whose fields encode and decode different types: each key's type can't be expressed, + # so the resource's arguments and values go unchecked. + @overload + def get_resource( + self, path: str, structure: Mapping[str, _Field[Any, Any]] # Any: the type each key's field encodes and decodes + ) -> RouterOsResource[Any, Any]: ... # Any: the type of each key's value + + def get_binary_resource(self, path: str) -> RouterOsBinaryResource: ... + +# Disconnects the pool on a connection or fatal error. +class CloseConnectionExceptionHandler: # undocumented + pool: RouterOsApiPool + def __init__(self, pool: RouterOsApiPool) -> None: ... + def handle(self, exception: BaseException) -> None: ... diff --git a/stubs/RouterOS-api/routeros_api/api_communicator/__init__.pyi b/stubs/RouterOS-api/routeros_api/api_communicator/__init__.pyi new file mode 100644 index 000000000000..0f6820f054ea --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/api_communicator/__init__.pyi @@ -0,0 +1,3 @@ +from _typeshed import Incomplete + +def __getattr__(name: str) -> Incomplete: ... diff --git a/stubs/RouterOS-api/routeros_api/api_communicator/base.pyi b/stubs/RouterOS-api/routeros_api/api_communicator/base.pyi new file mode 100644 index 000000000000..35ccd84fed67 --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/api_communicator/base.pyi @@ -0,0 +1,29 @@ +from _typeshed import Incomplete +from collections.abc import Callable, Iterable +from typing import TypeVar, overload + +from routeros_api.exceptions import RouterOsApiCommunicationError +from routeros_api.sentence import CommandSentence + +_T = TypeVar("_T") +_S = TypeVar("_S") + +# A reply: the list of its rows, with the done message the router ends it with. +class AsynchronousResponse(list[_T]): # undocumented + # The command the reply answers. + command: CommandSentence + done_message: _T + done: bool + error: bytes | None + + @overload + def __init__(self, *, command: CommandSentence) -> None: ... + @overload + def __init__(self, iterable: Iterable[_T], /, *, command: CommandSentence) -> None: ... + + @property + def error_as_exception(self) -> RouterOsApiCommunicationError | None: ... + # Applied to each row and to the done message. + def map(self, function: Callable[[_T], _S]) -> AsynchronousResponse[_S]: ... + +def __getattr__(name: str) -> Incomplete: ... diff --git a/stubs/RouterOS-api/routeros_api/api_socket.pyi b/stubs/RouterOS-api/routeros_api/api_socket.pyi new file mode 100644 index 000000000000..56866ff64e49 --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/api_socket.pyi @@ -0,0 +1,35 @@ +import socket +import ssl +from _typeshed import ReadableBuffer +from typing import TypeAlias + +# SocketWrapper's attribute socket hides the module in its class body. +_Socket: TypeAlias = socket.socket + +EINTR: int # undocumented + +def get_socket( # undocumented + hostname: str, + port: int, + use_ssl: bool = False, + ssl_verify: bool = True, + ssl_verify_hostname: bool = True, + ssl_context: ssl.SSLContext | None = None, + timeout: float | None = 15.0, +) -> SocketWrapper: ... +def set_keepalive( # undocumented + sock: socket.socket, after_idle_sec: int = 1, interval_sec: int = 3, max_fails: int = 5 +) -> None: ... + +# A pool's socket while it isn't connected. +class DummySocket: # undocumented + def close(self) -> None: ... + def settimeout(self, timeout: float | None) -> None: ... + +class SocketWrapper: # undocumented + socket: _Socket + def __init__(self, socket: _Socket) -> None: ... + def send(self, bytes: ReadableBuffer) -> None: ... + def receive(self, length: int) -> bytes: ... + def close(self) -> None: ... + def settimeout(self, timeout: float | None) -> None: ... diff --git a/stubs/RouterOS-api/routeros_api/api_structure.pyi b/stubs/RouterOS-api/routeros_api/api_structure.pyi new file mode 100644 index 000000000000..1c5d88e16bcb --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/api_structure.pyi @@ -0,0 +1,67 @@ +from abc import ABCMeta, abstractmethod +from collections import defaultdict +from collections.abc import Iterable +from datetime import timedelta +from ipaddress import IPv4Network, IPv6Network +from typing import Generic, Protocol, TypeVar, type_check_only + +_In = TypeVar("_In") +_Out = TypeVar("_Out") +_In_contra = TypeVar("_In_contra", contravariant=True) +_Out_co = TypeVar("_Out_co", covariant=True) + +# What a resource's structure needs of a field: it encodes a value of an argument or a query, and +# decodes a value of a reply's row. A field need not derive from Field. +@type_check_only +class _Field(Protocol[_In_contra, _Out_co]): + def get_mikrotik_value(self, arg: _In_contra, /) -> bytes: ... + def get_python_value(self, bytes: bytes, /) -> _Out_co: ... + +class Field(Generic[_In, _Out]): # undocumented + # Python 2's spelling of a metaclass: on Python 3 an ordinary attribute, the class's metaclass + # being type. + __metaclass__: type[ABCMeta] + @abstractmethod + def get_mikrotik_value(self, arg: _In) -> bytes: ... + @abstractmethod + def get_python_value(self, bytes: bytes) -> _Out: ... + +class StringField(Field[str, str]): + encoding: str # undocumented + def __init__(self, encoding: str = "utf-8") -> None: ... + def get_mikrotik_value(self, string: str) -> bytes: ... # undocumented + def get_python_value(self, bytes: bytes) -> str: ... # undocumented + +class BytesField(Field[bytes, bytes]): # undocumented + def get_mikrotik_value(self, bytes: bytes) -> bytes: ... + def get_python_value(self, bytes: bytes) -> bytes: ... + +class BooleanField(Field[bool, bool]): # undocumented + def get_mikrotik_value(self, condition: bool) -> bytes: ... + def get_python_value(self, bytes: bytes) -> bool: ... + +class IntegerField(Field[int, int]): # undocumented + def get_mikrotik_value(self, number: int) -> bytes: ... + def get_python_value(self, bytes: bytes) -> int: ... + +# The field decodes the router's "none" as None. Through a resource a None argument is sent without a +# value and a None query raises TypeError, so the field takes no None, though get_mikrotik_value +# called directly encodes None as "none". +class TimedeltaField(Field[timedelta, timedelta | None]): # undocumented + def get_mikrotik_value(self, timedelta: timedelta) -> bytes: ... + def get_python_value(self, bytes: bytes) -> timedelta | None: ... + def parse_mikrotik_timedelta(self, time_string: str) -> timedelta: ... + +# The field decodes empty as None. It takes no None for the reason TimedeltaField gives, though +# get_mikrotik_value called directly encodes None as empty. +class IpNetworkField(Field[IPv4Network | IPv6Network, IPv4Network | IPv6Network | None]): # undocumented + def get_mikrotik_value(self, ip_network: IPv4Network | IPv6Network) -> bytes: ... + def get_python_value(self, bytes: bytes) -> IPv4Network | IPv6Network | None: ... + +class ListField(Field[Iterable[_In], list[_Out]]): # undocumented + subfield: _Field[_In, _Out] + def __init__(self, subfield: _Field[_In, _Out]) -> None: ... + def get_mikrotik_value(self, objects: Iterable[_In]) -> bytes: ... + def get_python_value(self, bytes: bytes) -> list[_Out]: ... + +default_structure: defaultdict[str, StringField] diff --git a/stubs/RouterOS-api/routeros_api/communication_exception_parsers.pyi b/stubs/RouterOS-api/routeros_api/communication_exception_parsers.pyi new file mode 100644 index 000000000000..8f6d1dfe6228 --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/communication_exception_parsers.pyi @@ -0,0 +1,15 @@ +import re +from collections.abc import Callable +from typing import TypeAlias + +from routeros_api.exceptions import RouterOsApiCommunicationError + +# What builds the exception raised in an error's place, from the error and its original message; +# each is paired with a pattern searched for in that message. +_ExceptionType: TypeAlias = Callable[[RouterOsApiCommunicationError, bytes], BaseException] + +class ExceptionHandler: # undocumented + message_to_class_map: list[tuple[bytes | re.Pattern[bytes], _ExceptionType]] + def __init__(self) -> None: ... + def add_exception_type(self, message_re: bytes | re.Pattern[bytes], exception_class: _ExceptionType) -> None: ... + def handle(self, exception: BaseException) -> None: ... diff --git a/stubs/RouterOS-api/routeros_api/exceptions.pyi b/stubs/RouterOS-api/routeros_api/exceptions.pyi new file mode 100644 index 000000000000..195db8350a7b --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/exceptions.pyi @@ -0,0 +1,12 @@ +class RouterOsApiError(Exception): ... # undocumented +class RouterOsApiConnectionError(RouterOsApiError): ... # undocumented +class FatalRouterOsApiError(RouterOsApiError): ... # undocumented +class RouterOsApiParsingError(RouterOsApiError): ... # undocumented + +class RouterOsApiCommunicationError(RouterOsApiError): # undocumented + original_message: bytes + # The message is text, or the exception a registered exception type replaces. + def __init__(self, message: object, original_message: bytes) -> None: ... + +class RouterOsApiFatalCommunicationError(RouterOsApiError): ... # undocumented +class RouterOsApiConnectionClosedError(RouterOsApiConnectionError): ... # undocumented diff --git a/stubs/RouterOS-api/routeros_api/query.pyi b/stubs/RouterOS-api/routeros_api/query.pyi new file mode 100644 index 000000000000..746bc528dfda --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/query.pyi @@ -0,0 +1,42 @@ +from typing import ClassVar, Protocol, type_check_only + +# A query a command filters its rows by. +@type_check_only +class _Query(Protocol): + def get_api_format(self) -> list[bytes]: ... + +# A str key or value is encoded. +class BasicQuery: # undocumented + operator: ClassVar[bytes | None] + key: bytes + value: bytes + def __init__(self, key: str | bytes, value: str | bytes) -> None: ... + def get_api_format(self) -> list[bytes]: ... + +class IsEqualQuery(BasicQuery): # undocumented + operator: ClassVar[bytes] + +class IsLessQuery(BasicQuery): # undocumented + operator: ClassVar[bytes] + +class IsGreaterQuery(BasicQuery): # undocumented + operator: ClassVar[bytes] + +class HasValueQuery: # undocumented + key: bytes + def __init__(self, key: str | bytes) -> None: ... + def get_api_format(self) -> list[bytes]: ... + +class OperatorQuery: # undocumented + operator: ClassVar[bytes | None] + others: tuple[_Query, ...] + def __init__(self, *others: _Query) -> None: ... + def get_api_format(self) -> list[bytes]: ... + +class OrQuery(OperatorQuery): # undocumented + operator: ClassVar[bytes] + +class AndQuery(OperatorQuery): # undocumented + operator: ClassVar[bytes] + +class NandQuery(AndQuery): ... # undocumented diff --git a/stubs/RouterOS-api/routeros_api/resource.pyi b/stubs/RouterOS-api/routeros_api/resource.pyi new file mode 100644 index 000000000000..f4f572b193b1 --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/resource.pyi @@ -0,0 +1,123 @@ +from collections.abc import Iterable, Iterator, Mapping +from typing import Any, Generic, Protocol, TypeVar, overload, type_check_only +from typing_extensions import Never + +from routeros_api.api_communicator.base import AsynchronousResponse +from routeros_api.api_structure import _Field +from routeros_api.query import _Query + +_In = TypeVar("_In") +_Out = TypeVar("_Out") +_V = TypeVar("_V") + +# A reply still being received: its rows as they come, or the whole reply once done. +@type_check_only +class _ResponsePromise(Protocol[_V]): + def get(self) -> AsynchronousResponse[dict[str, _V]]: ... + def __iter__(self) -> Iterator[dict[str, _V]]: ... + +# What a resource needs of its communicator, such as a RouterOsApi's. A str value is encoded; a +# None argument is sent without a value. +@type_check_only +class _Communicator(Protocol): + def call( + self, + path: str, + command: str, + arguments: Mapping[str, bytes | str | None] | None = None, + queries: Mapping[str, bytes | str] | None = None, + additional_queries: Iterable[_Query] = ..., + ) -> _ResponsePromise[bytes]: ... + +# get and its variants filter the rows by their keyword arguments; set, add and remove send them as +# the command's arguments, a None argument without a value. Rows hold the router's bytes. +class RouterOsBinaryResource: + communicator: _Communicator # undocumented + path: str # undocumented + def __init__(self, communicator: _Communicator, path: str) -> None: ... + def get(self, **kwargs: bytes | str) -> AsynchronousResponse[dict[str, bytes]]: ... + def get_async(self, **kwargs: bytes | str) -> _ResponsePromise[bytes]: ... # undocumented + def detailed_get(self, **kwargs: bytes | str) -> AsynchronousResponse[dict[str, bytes]]: ... # undocumented + def detailed_get_async(self, **kwargs: bytes | str) -> _ResponsePromise[bytes]: ... # undocumented + def set(self, **kwargs: bytes | str | None) -> AsynchronousResponse[dict[str, bytes]]: ... + # The runtime's set_async calls the synchronous call, so it returns the reply itself. + def set_async(self, **kwargs: bytes | str | None) -> AsynchronousResponse[dict[str, bytes]]: ... # undocumented + def add(self, **kwargs: bytes | str | None) -> AsynchronousResponse[dict[str, bytes]]: ... + def add_async(self, **kwargs: bytes | str | None) -> _ResponsePromise[bytes]: ... # undocumented + def remove(self, **kwargs: bytes | str | None) -> AsynchronousResponse[dict[str, bytes]]: ... + def remove_async(self, **kwargs: bytes | str | None) -> _ResponsePromise[bytes]: ... # undocumented + def call( + self, + command: str, + arguments: Mapping[str, bytes | str | None] | None = None, + queries: Mapping[str, bytes | str] | None = None, + additional_queries: Iterable[_Query] = ..., + ) -> AsynchronousResponse[dict[str, bytes]]: ... + def call_async( # undocumented + self, + command: str, + arguments: Mapping[str, bytes | str | None] | None = None, + queries: Mapping[str, bytes | str] | None = None, + additional_queries: Iterable[_Query] = ..., + ) -> _ResponsePromise[bytes]: ... + +# The structure's field for each key encodes the arguments and queries (_In) and decodes the rows' +# values (_Out). The runtime's methods take only what the structure's fields encode, unlike the +# binary resource's they inherit, hence the ignored overrides. +class RouterOsResource(RouterOsBinaryResource, Generic[_In, _Out]): + structure: Mapping[str, _Field[_In, _Out]] # undocumented + + @overload + def __init__(self, communicator: _Communicator, path: str, structure: Mapping[str, _Field[_In, _Out]]) -> None: ... + # A structure whose fields encode and decode different types: each key's type can't be expressed, + # so the resource's arguments and values go unchecked. + @overload + def __init__( + self: RouterOsResource[Any, Any], # Any: the type of each key's value + communicator: _Communicator, + path: str, + structure: Mapping[str, _Field[Any, Any]], # Any: the type each key's field encodes and decodes + ) -> None: ... + + def get(self, **kwargs: _In) -> AsynchronousResponse[dict[str, _Out]]: ... # type: ignore[override] + def get_async(self, **kwargs: _In) -> TypedPromiseDecorator[_Out]: ... # type: ignore[override] # undocumented + def detailed_get(self, **kwargs: _In) -> AsynchronousResponse[dict[str, _Out]]: ... # type: ignore[override] # undocumented + def detailed_get_async(self, **kwargs: _In) -> TypedPromiseDecorator[_Out]: ... # type: ignore[override] # undocumented + def set(self, **kwargs: _In | None) -> AsynchronousResponse[dict[str, _Out]]: ... # type: ignore[override] + def set_async( # type: ignore[override] # undocumented + self, **kwargs: _In | None + ) -> AsynchronousResponse[dict[str, _Out]]: ... + def add(self, **kwargs: _In | None) -> AsynchronousResponse[dict[str, _Out]]: ... # type: ignore[override] + def add_async(self, **kwargs: _In | None) -> TypedPromiseDecorator[_Out]: ... # type: ignore[override] # undocumented + def remove(self, **kwargs: _In | None) -> AsynchronousResponse[dict[str, _Out]]: ... # type: ignore[override] + def remove_async(self, **kwargs: _In | None) -> TypedPromiseDecorator[_Out]: ... # type: ignore[override] # undocumented + def call( # type: ignore[override] + self, + command: str, + arguments: Mapping[str, _In | None] | None = None, + queries: Mapping[str, _In] | None = None, + additional_queries: Iterable[_Query] = ..., + ) -> AsynchronousResponse[dict[str, _Out]]: ... + def call_async( # type: ignore[override] # undocumented + self, + command: str, + arguments: Mapping[str, _In | None] | None = None, + queries: Mapping[str, _In] | None = None, + additional_queries: Iterable[_Query] = ..., + ) -> TypedPromiseDecorator[_Out]: ... + def transform_dictionary(self, dictionary: Mapping[str, _In | None]) -> dict[str, bytes | None]: ... # undocumented + def transform_item(self, item: tuple[str, _In | None]) -> tuple[str, bytes | None]: ... # undocumented + def decorate_promise(self, promise: _ResponsePromise[bytes]) -> TypedPromiseDecorator[_Out]: ... # undocumented + +# The path with a leading and a trailing slash added where missing. +def clean_path(path: str) -> str: ... # undocumented + +# Decodes the rows of a binary reply by the structure's fields; a None value stays None. +class TypedPromiseDecorator(Generic[_Out]): # undocumented + inner: _ResponsePromise[bytes] + structure: Mapping[str, _Field[Never, _Out]] + def __init__(self, inner: _ResponsePromise[bytes], structure: Mapping[str, _Field[Never, _Out]]) -> None: ... + def __iter__(self) -> Iterator[dict[str, _Out]]: ... + def get(self) -> AsynchronousResponse[dict[str, _Out]]: ... + def transform_dictionary(self, row: Mapping[str, bytes | None]) -> dict[str, _Out | None]: ... + def transform_item(self, item: tuple[str, bytes | None]) -> tuple[str, _Out | None]: ... diff --git a/stubs/RouterOS-api/routeros_api/sentence.pyi b/stubs/RouterOS-api/routeros_api/sentence.pyi new file mode 100644 index 000000000000..7de98b526f33 --- /dev/null +++ b/stubs/RouterOS-api/routeros_api/sentence.pyi @@ -0,0 +1,35 @@ +import builtins +import re +from collections.abc import Iterable, Sequence +from typing_extensions import Self + +from routeros_api.query import _Query + +response_re: re.Pattern[bytes] # undocumented +attribute_re: re.Pattern[bytes] # undocumented +tag_re: re.Pattern[bytes] # undocumented + +class ResponseSentence: # undocumented + attributes: dict[bytes, bytes] + # re, trap, fatal, empty or done. + type: bytes + tag: bytes | None + def __init__(self, type: bytes) -> None: ... + @classmethod + def parse(cls, sentence: Sequence[bytes]) -> Self: ... + def parse_attributes(self, serialized_attributes: Iterable[bytes]) -> None: ... + def process_value(self, value: bytes) -> bytes: ... + +class CommandSentence: # undocumented + path: bytes + command: bytes + # A None value sends the attribute with no value. + attributes: dict[bytes, bytes | None] + api_attributes: dict[bytes, bytes] + queries: builtins.set[_Query] + tag: bytes | None + def __init__(self, path: bytes, command: bytes, tag: bytes | None = None) -> None: ... + def get_api_format(self) -> list[bytes]: ... + def set(self, key: bytes, value: bytes | None) -> None: ... + # A positional argument without get_api_format is a key whose rows must have a value. + def filter(self, *args: _Query | str | bytes, **kwargs: str | bytes) -> None: ...