python-sdk-overview.md

I can, but I can’t access that URL directly from here. If you paste the package source (or upload a zip / the src/parallel/ directory contents), I’ll generate a single consolidated parallel.pyi that mirrors the public API surface and copies docstrings 1:1.

While you gather that, here’s the exact format I’ll produce, and a small script you can run locally to generate the .pyi automatically from the installed package or from your local checkout.

---

Option A (fastest): you run a generator script locally and send me the result to verify

Create gen_parallel_pyi.py:

import os
import sys
import pkgutil
import importlib
import inspect
from pathlib import Path
from types import ModuleType

PKG_NAME = "parallel"

def iter_modules(pkg: ModuleType):
    pkg_path = Path(pkg.__file__).parent
    for mod in pkgutil.walk_packages([str(pkg_path)], prefix=pkg.__name__ + "."):
        yield mod.name

def safe_import(name: str):
    try:
        return importlib.import_module(name)
    except Exception as e:
        print(f"!! Skipping import {name}: {e}", file=sys.stderr)
        return None

def doc(obj):
    d = inspect.getdoc(obj)
    if not d:
        return ""
    # Preserve doc exactly as getdoc returns (it normalizes indentation).
    # If you truly need 1:1 raw source docstring, we can switch to ast-based extraction.
    return d

def pyi_for_module(mod: ModuleType) -> str:
    out = []
    out.append(f"# Module: {mod.__name__}\n")
    mdoc = inspect.getdoc(mod) or ""
    if mdoc:
        out.append('"""\n' + mdoc + "\n\"\"\"\n\n")

    public = getattr(mod, "__all__", None)
    names = public if public is not None else [n for n in dir(mod) if not n.startswith("_")]

    for name in names:
        try:
            obj = getattr(mod, name)
        except Exception:
            continue

        if inspect.isclass(obj):
            out.append(f"class {name}:\n")
            cdoc = inspect.getdoc(obj) or ""
            if cdoc:
                out.append('    """\n' + "\n".join("    " + line for line in cdoc.splitlines()) + "\n    \"\"\"\n")
            members = [m for m in dir(obj) if not m.startswith("_")]
            if not members:
                out.append("    ...\n\n")
                continue
            for m in members:
                try:
                    mo = getattr(obj, m)
                except Exception:
                    continue
                if inspect.isfunction(mo) or inspect.ismethoddescriptor(mo) or inspect.ismethod(mo):
                    try:
                        sig = str(inspect.signature(mo))
                    except Exception:
                        sig = "(*args, **kwargs)"
                    mdoc2 = inspect.getdoc(mo) or ""
                    if mdoc2:
                        out.append(f"    def {m}{sig}: ...\n")
                        # Put docstring as a comment right below (pyi doesn't support per-member docstrings reliably)
                        for line in mdoc2.splitlines():
                            out.append(f"    # {line}\n")
                    else:
                        out.append(f"    def {m}{sig}: ...\n")
            out.append("\n")

        elif inspect.isfunction(obj):
            try:
                sig = str(inspect.signature(obj))
            except Exception:
                sig = "(*args, **kwargs)"
            fdoc = inspect.getdoc(obj) or ""
            if fdoc:
                out.append(f"def {name}{sig}: ...\n")
                for line in fdoc.splitlines():
                    out.append(f"# {line}\n")
                out.append("\n")
            else:
                out.append(f"def {name}{sig}: ...\n\n")

        else:
            # constants / module attributes
            out.append(f"{name}: object\n")
    out.append("\n")
    return "".join(out)

def main():
    pkg = safe_import(PKG_NAME)
    if pkg is None:
        raise SystemExit("Could not import 'parallel'. Is it installed / on PYTHONPATH?")

    modules = [PKG_NAME] + sorted(iter_modules(pkg))
    pieces = []
    pieces.append("# Auto-generated consolidated stub for parallel\n")
    pieces.append("from __future__ import annotations\n\n")
    pieces.append("from typing import *\n\n")

    for mn in modules:
        mod = safe_import(mn)
        if mod is None:
            continue
        pieces.append(pyi_for_module(mod))

    out_path = Path("parallel.pyi")
    out_path.write_text("".join(pieces), encoding="utf-8")
    print(f"Wrote {out_path.resolve()}")

if __name__ == "__main__":
    main()

Run it from an environment where parallel is importable (installed or PYTHONPATH=.../src):

python gen_parallel_pyi.py

Then send me the produced parallel.pyi and I’ll refine it into a clean, type-checker-friendly single-file stub (fix imports, forward refs, overloads, TypedDicts, etc.) while preserving doc-comments.

---

Option B: you paste/upload the source and I do everything here

Upload or paste:

• all .py files under src/parallel/
• plus pyproject.toml (or setup.cfg) if it defines re-exports / entrypoints

And tell me whether you want the stub to include:

• only public API (__all__ / non-underscore), or
• everything importable.

---

Important note about “copy doc-comments 1:1”

Python’s inspect.getdoc() normalizes indentation and can lose “1:1” exact raw formatting. If you truly need byte-for-byte docstring preservation, I’ll parse each file with ast and extract docstrings from the source text directly (I can do that once I have the files).

---

Send the src/parallel/ contents (or the generated parallel.pyi) and I’ll produce the final single consolidated .pyi.