feat(mypy): stub files

.github/workflows/test.yml

@@ -11,6 +11,27 @@ permissions:
   contents: read
 
 jobs:
+  mypy-stubs:
+    name: Mypy (stubs)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install mypy
+        run: |
+          python -m pip install --upgrade pip
+          pip install mypy typing_extensions
+      - name: Type check stubs
+        run: |
+          python -m mypy --config-file mypy.ini
+
   test:
     runs-on: ${{ matrix.os }}
     strategy:

cytoolz/__init__.pyi

@@ -0,0 +1,87 @@
+# Builtins - re-export to make them available in toolz namespace
+from builtins import filter as filter, map as map, sorted as sorted
+from functools import partial as partial, reduce as reduce
+
+# Re-export all public APIs from submodules
+# Submodules
+from . import curried as curried
+
+# Specific functions
+from .dicttoolz import (
+    assoc as assoc,
+    assoc_in as assoc_in,
+    dissoc as dissoc,
+    get_in as get_in,
+    itemfilter as itemfilter,
+    itemmap as itemmap,
+    keyfilter as keyfilter,
+    keymap as keymap,
+    merge as merge,
+    merge_with as merge_with,
+    update_in as update_in,
+    valfilter as valfilter,
+    valmap as valmap,
+)
+from .functoolz import (
+    apply as apply,
+    complement as complement,
+    compose as compose,
+    compose_left as compose_left,
+    curry as curry,
+    do as do,
+    excepts as excepts,
+    flip as flip,
+    identity as identity,
+    juxt as juxt,
+    memoize as memoize,
+    pipe as pipe,
+    thread_first as thread_first,
+    thread_last as thread_last,
+)
+from .itertoolz import (
+    accumulate as accumulate,
+    concat as concat,
+    concatv as concatv,
+    cons as cons,
+    count as count,
+    diff as diff,
+    drop as drop,
+    first as first,
+    frequencies as frequencies,
+    get as get,
+    groupby as groupby,
+    interleave as interleave,
+    interpose as interpose,
+    isdistinct as isdistinct,
+    isiterable as isiterable,
+    iterate as iterate,
+    join as join,
+    last as last,
+    mapcat as mapcat,
+    merge_sorted as merge_sorted,
+    nth as nth,
+    partition as partition,
+    partition_all as partition_all,
+    peek as peek,
+    peekn as peekn,
+    pluck as pluck,
+    random_sample as random_sample,
+    reduceby as reduceby,
+    remove as remove,
+    second as second,
+    sliding_window as sliding_window,
+    tail as tail,
+    take as take,
+    take_nth as take_nth,
+    topk as topk,
+    unique as unique,
+)
+from .recipes import countby as countby, partitionby as partitionby
+
+# Aliases
+comp = compose
+
+# Version attribute (available via __getattr__ at runtime)
+__toolz_version__: str
+
+__version__: str

cytoolz/_signatures.pyi

@@ -0,0 +1,28 @@
+import typing
+
+class _AnyCallable[ReturnT](typing.Protocol):
+    def __call__(self, *args: object, **kwargs: object) -> ReturnT: ...
+
+Signature = _AnyCallable[object]
+SignatureInfo = dict[str, list[Signature]]
+
+cytoolz_info: dict[str, SignatureInfo]
+module_info: dict[str, SignatureInfo]
+
+
+def create_signature_registry(info: dict[str, SignatureInfo]) -> None: ...
+
+def update_signature_registry() -> None: ...
+
+
+def _is_arity(func: Signature, n: int) -> bool: ...
+
+def _has_varargs(func: Signature) -> bool: ...
+
+def _has_keywords(func: Signature) -> bool: ...
+
+def _num_required_args(func: Signature) -> int: ...
+
+def _is_partial_args(func: Signature, args: tuple[object, ...], kwargs: dict[str, object]) -> bool: ...
+
+def _is_valid_args(func: Signature, args: tuple[object, ...], kwargs: dict[str, object]) -> bool: ...

cytoolz/_version.pyi

@@ -0,0 +1,15 @@
+import typing
+
+VersionInfo = typing.TypedDict(
+    "VersionInfo",
+    {
+        "version": str,
+        "full-revisionid": str | None,
+        "dirty": bool | None,
+        "error": str | None,
+        "date": str | None,
+    },
+)
+
+
+def get_versions() -> VersionInfo: ...

cytoolz/compatibility.pyi

@@ -0,0 +1,32 @@
+from builtins import filter as filter, map as map, range as range, zip as zip
+from functools import reduce as reduce
+from itertools import filterfalse as filterfalse, zip_longest as zip_longest
+import collections.abc
+import typing
+
+__all__ = (
+    "map",
+    "filter",
+    "range",
+    "zip",
+    "reduce",
+    "zip_longest",
+    "iteritems",
+    "iterkeys",
+    "itervalues",
+    "filterfalse",
+    "PY3",
+    "PY34",
+    "PYPY",
+)
+
+PY3: bool
+PY34: bool
+PYPY: bool
+
+
+def iteritems[K, V](mapping: collections.abc.Mapping[K, V]) -> collections.abc.ItemsView[K, V]: ...
+
+def iterkeys[K, V](mapping: collections.abc.Mapping[K, V]) -> collections.abc.KeysView[K]: ...
+
+def itervalues[K, V](mapping: collections.abc.Mapping[K, V]) -> collections.abc.ValuesView[V]: ...