Skip to content

Add stubs for RouterOS-api - #16856

Closed
kbr- wants to merge 1 commit into
python:mainfrom
kbr-:routeros-api-stubs
Closed

kbr- wants to merge 1 commit into
python:mainfrom
kbr-:routeros-api-stubs

Conversation

@kbr-

@kbr- kbr- commented Nov 18, 2026 •

Copy link
Copy Markdown

Add stubs for RouterOS-api

RouterOS-api 0.21 ships no type information; this adds partial stubs for its connection pool, API,
resources, field structures, queries and exceptions.

Upstream: the source and its
README
.

Written with Claude Code (Claude Opus 5.5).

@github-actions

This comment has been minimized.

@kbr-
kbr- force-pushed the routeros-api-stubs branch from bd82b0e to 9539cf2 Compare November 18, 2026 10:05
@github-actions

This comment has been minimized.

@kbr-
kbr- force-pushed the routeros-api-stubs branch 2 times, most recently from e430b18 to 9e0e63a Compare November 18, 2026 10:27
@github-actions

This comment has been minimized.

@srittau srittau left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Please remove the tests. In typeshed, we only add regression tests for functions and classes which are known to have caused complex problems in the past, or where stubs are difficult to get right. 100% test coverage for typeshed is neither necessary nor desirable, as it would lead to code duplication.

See tests/REGRESSION.md for more information.

done_message: _T
done: bool
error: bytes | None
def __init__(self, *args: Any, command, **kwargs: Any) -> None: ...

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This should use the concrete arguments that are accepted. Alternatively, leave the *args and **kwargs unannotated for now.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

It now takes the rows as list's optional positional iterable and a keyword-only command: CommandSentence, with stubs for routeros_api.sentence.

Comment on lines +14 to +15
def get_mikrotik_value(self, arg: Any, /) -> bytes: ...
def get_python_value(self, bytes: bytes, /) -> Any: ...

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

We need a short comment why Any is used here or what the possible values are.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

_Field is now generic in what a field encodes and decodes, _Field[_In, _Out], and routeros_api.api_structure has stubs, each field class with its types (StringField encodes and decodes str, IntegerField encodes any value through str() and decodes int, and so on). RouterOsResource is generic over its structure's _In and _Out, and get_resource() without a structure gives RouterOsResource[str, str].

Comment on lines +26 to +36
def get(self, **kwargs: Any) -> AsynchronousResponse[dict[str, Any]]: ...
def get_async(self, **kwargs: Any) -> _ResponsePromise: ...
def detailed_get(self, **kwargs: Any) -> AsynchronousResponse[dict[str, Any]]: ...
def detailed_get_async(self, **kwargs: Any) -> _ResponsePromise: ...
def set(self, **kwargs: Any) -> AsynchronousResponse[dict[str, Any]]: ...
# The runtime's set_async calls the synchronous call, so it returns the reply itself.
def set_async(self, **kwargs: Any) -> AsynchronousResponse[dict[str, Any]]: ...
def add(self, **kwargs: Any) -> AsynchronousResponse[dict[str, Any]]: ...
def add_async(self, **kwargs: Any) -> _ResponsePromise: ...
def remove(self, **kwargs: Any) -> AsynchronousResponse[dict[str, Any]]: ...
def remove_async(self, **kwargs: Any) -> _ResponsePromise: ...

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I assume that the arguments here are not arbitrary? In that case it's best to either use the actually accepted arguments or just leave the kwargs arguments unannotated for now. Otherwise, we need a comment explaining the situation.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Right, they aren't arbitrary. A binary resource's get variants filter by them, so they take bytes | str; set, add and remove send them as arguments, so they take bytes | str | None, None sending the attribute without a value. Its rows are dict[str, bytes]. A typed resource's take its structure's _In, and its rows are dict[str, _Out]; since the runtime's methods accept only what the fields encode, unlike the binary resource's they inherit, they override them with # type: ignore[override].

@kbr-
kbr- force-pushed the routeros-api-stubs branch from 9e0e63a to 7fe5e05 Compare November 18, 2026 13:21
@kbr-

kbr- commented Nov 18, 2026

Copy link
Copy Markdown
Author

Thanks. The tests are removed, and no annotation in the package is Any or Incomplete now; the replies below say what each became.

@github-actions

This comment has been minimized.

RouterOS-api 0.21 ships no type information; this adds partial stubs for its connection pool, API,
resources, field structures, queries 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).
@kbr-
kbr- force-pushed the routeros-api-stubs branch from 7fe5e05 to 1a84370 Compare November 18, 2026 13:41
@github-actions

Copy link
Copy Markdown
Contributor

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

@srittau

srittau commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

I'm sorry, but I can't review the changes, since this was force pushed, against our policy in CONTRIBUTING.md.

@kbr-

kbr- commented Nov 18, 2026 •

Copy link
Copy Markdown
Author

Sorry. I wanted a clean commit history. Should I open another PR?
EDIT: I'll just do it.

@kbr- kbr- closed this Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants