Quickstart

CLI

The simplest usage is to point stubpy at a .py file. The stub is written next to the source by default:

stubpy path/to/mymodule.py
# → writes path/to/mymodule.pyi

To specify a custom output path:

stubpy path/to/mymodule.py -o stubs/mymodule.pyi

To also print the generated stub to stdout:

stubpy path/to/mymodule.py --print

Full CLI reference:

usage: stubpy [-h] [-o PATH] [--print] file

positional arguments:
  file          Python source file to stub

optional arguments:
  -h, --help    show this help message and exit
  -o PATH       Output .pyi path (default: same stem and directory as input)
  --print       Print the generated stub to stdout after writing

Python API

from stubpy import generate_stub

# Write stub alongside the source, return content as a string
content = generate_stub("path/to/mymodule.py")

# Write to a custom path
content = generate_stub("path/to/mymodule.py", "out/mymodule.pyi")

A complete example

Given this source file shapes.py:

from typing import Optional

class Shape:
    def __init__(
        self,
        color: str = "black",
        opacity: float = 1.0,
    ) -> None:
        self.color   = color
        self.opacity = opacity

class Circle(Shape):
    def __init__(self, radius: float, **kwargs) -> None:
        super().__init__(**kwargs)
        self.radius = radius

    @classmethod
    def unit(cls, **kwargs) -> "Circle":
        return cls(radius=1.0, **kwargs)

Running:

stubpy shapes.py --print

Produces:

from __future__ import annotations
from typing import Optional

class Shape:
    def __init__(
        self,
        color: str = 'black',
        opacity: float = 1.0,
    ) -> None: ...

class Circle(Shape):
    def __init__(
        self,
        radius: float,
        color: str = 'black',
        opacity: float = 1.0,
    ) -> None: ...
    @classmethod
    def unit(
        cls,
        color: str = 'black',
        opacity: float = 1.0,
    ) -> Circle: ...

Notice that:

• **kwargs in Circle.__init__ is resolved to color and opacity from Shape.__init__.

• Circle.unit is a @classmethod that calls cls(radius=1.0, **kwargs); because radius is hardcoded, it is excluded from the stub, and only the remaining Shape params appear.