[yara-python] Add yara-python stubs

[zeevro]

No description provided.

[github-actions]

Diff from mypy_primer, showing the effect of this PR on open source code:

scipy-stubs (https://github.com/scipy/scipy-stubs)
+ tests/misc/test_submodules_empty.pyi:3: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports

[srittau]

I don't think the match overloads are correct here: This would allow calls such as ...match(123) (where 123 is a PID), which wouldn't work at runtime. Also technically calls such as ...match("/path", -1, None) should work and I suggest to allow this in stubs as well. Please see my suggestions below. The alternative is to use * to mark arguments as kw-only.

Also, callbacks where the return value is ignored should use object as return type, not Any. Otherwise, as Any types must be explained, the return type must be explained in a comment.

[srittau]

Suggested change

	filepath: str,
	filepath: str,
	pid: Literal[-1] = -1,
	data: None = None,

[srittau]

Suggested change

	@overload
	def match(
	self,
	pid: int,
	externals: dict[str, bool | int | float | str] | None = None,
	callback: Callable[[dict[str, Any]], Any] | None = None,
	fast: bool = False,
	timeout: int = ...,
	modules_data: dict[str, bytes] | None = None,
	modules_callback: Callable[[dict[str, Any]], int] | None = None,
	which_callbacks: int = ...,
	warnings_callback: Callable[[int, str], int] | None = None,
	console_callback: Callable[[str], Any] | None = None,
	allow_duplicate_metadata: bool = False,
	) -> list[Match]: ...
	@overload
	def match(
	self,
	filepath: None,
	pid: int,
	data: None = None,
	externals: dict[str, bool | int | float | str] | None = None,
	callback: Callable[[dict[str, Any]], Any] | None = None,
	fast: bool = False,
	timeout: int = ...,
	modules_data: dict[str, bytes] | None = None,
	modules_callback: Callable[[dict[str, Any]], int] | None = None,
	which_callbacks: int = ...,
	warnings_callback: Callable[[int, str], int] | None = None,
	console_callback: Callable[[str], Any] | None = None,
	allow_duplicate_metadata: bool = False,
	) -> list[Match]: ...
	@overload
	def match(
	self,
	*,
	filepath: None = None,
	pid: int,
	data: None = None,
	externals: dict[str, bool | int | float | str] | None = None,
	callback: Callable[[dict[str, Any]], Any] | None = None,
	fast: bool = False,
	timeout: int = ...,
	modules_data: dict[str, bytes] | None = None,
	modules_callback: Callable[[dict[str, Any]], int] | None = None,
	which_callbacks: int = ...,
	warnings_callback: Callable[[int, str], int] | None = None,
	console_callback: Callable[[str], Any] | None = None,
	allow_duplicate_metadata: bool = False,
	) -> list[Match]: ...

[srittau]

Suggested change

	@overload
	def match(
	self,
	data: bytes | str,
	externals: dict[str, bool | int | float | str] | None = None,
	callback: Callable[[dict[str, Any]], Any] | None = None,
	fast: bool = False,
	timeout: int = ...,
	modules_data: dict[str, bytes] | None = None,
	modules_callback: Callable[[dict[str, Any]], int] | None = None,
	which_callbacks: int = ...,
	warnings_callback: Callable[[int, str], int] | None = None,
	console_callback: Callable[[str], Any] | None = None,
	allow_duplicate_metadata: bool = False,
	) -> list[Match]: ...
	@overload
	def match(
	self,
	filepath: None,
	pid: Literal[-1],
	data: bytes | str,
	externals: dict[str, bool | int | float | str] | None = None,
	callback: Callable[[dict[str, Any]], Any] | None = None,
	fast: bool = False,
	timeout: int = ...,
	modules_data: dict[str, bytes] | None = None,
	modules_callback: Callable[[dict[str, Any]], int] | None = None,
	which_callbacks: int = ...,
	warnings_callback: Callable[[int, str], int] | None = None,
	console_callback: Callable[[str], Any] | None = None,
	allow_duplicate_metadata: bool = False,
	) -> list[Match]: ...
	@overload
	def match(
	self,
	*,
	filepath: None = None,
	pid: Literal[-1] = -1,
	data: bytes | str,
	externals: dict[str, bool | int | float | str] | None = None,
	callback: Callable[[dict[str, Any]], Any] | None = None,
	fast: bool = False,
	timeout: int = ...,
	modules_data: dict[str, bytes] | None = None,
	modules_callback: Callable[[dict[str, Any]], int] | None = None,
	which_callbacks: int = ...,
	warnings_callback: Callable[[int, str], int] | None = None,
	console_callback: Callable[[str], Any] | None = None,
	allow_duplicate_metadata: bool = False,
	) -> list[Match]: ...