`py.typed` marker file for mypy

[johncalls]

I'm using llm as a library. Running mypy on my project results in the following error:

error: Skipping analyzing "llm": module is installed, but missing library stubs or py.typed marker [import-untyped]

Adding a file py.typed locally to llm resolves the error for me. I'd suggest adding the marker (or stubs) to the library.

The corresponding PEP can be found here: https://peps.python.org/pep-0561/.

[simonw]

Ran a few rounds with Claude to check the consequences of doing this: https://claude.ai/share/ac09a168-828e-4465-a6f6-6c83511a38af - looks to me like having py.typed in the llm/ folder is already protected by my mypy job, which will fail if any of the public methods in that package are not correctly typed:

llm/.github/workflows/test.yml

Lines 39 to 42 in 0cc26b3

	- name: Run mypy
	if: matrix.os != 'windows-latest'
	run: |
	mypy llm

[simonw]

I'm doing this first:

• Convert setup.py to pyproject.toml #907

[simonw]

I'm trying to figure out if it's worth adding this to pyproject.toml:

[tool.mypy]
disallow_untyped_defs = true
disallow_incomplete_defs = true

Is that the default already? I want to be absolutely sure I don't accidentally ship a release that breaks mypy for other people who are depending on the new py.typed file.

[simonw]

OK, this is in a branch now. I'll open a PR and test it there.

[simonw]

The branch is now available to install from:

https://codeload.github.com/simonw/llm/zip/refs/heads/py.typed

[simonw]

I think the way to test this is with a new temporary Python project that depends on LLM and uses mypy.

[simonw]

cookiecutter gh:simonw/click-app

Then:

  [1/6] app_name (): cowsay-via-llm
  [2/6] description (): cowsay with an LLM
  [3/6] hyphenated (cowsay-via-llm): 
  [4/6] underscored (cowsay_via_llm): 
  [5/6] github_username (): simonw
  [6/6] author_name (): Simon Willison

cd cowsay-via-llm
uv sync --extra

I added llm as a dependency to pyproject.toml (the current shipped version, not the branch).

This is a really silly demo:

import click
import llm

SYSTEM = """
Render this as ASCII art like cowsay does.
Return plain text no markdown or fenced code block
""".strip()


@click.command()
@click.argument("text", nargs=-1)
def cli(text):
    "cowsay with an LLM"
    model = llm.get_model()
    click.echo(model.prompt(" ".join(text), system=SYSTEM))

And now:

uv run cowsay-via-llm hi this is fun

Outputs:

 ___________
< hi this is fun >
 ----------- 
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

[simonw]

I did this:

uv add mypy --dev
uv run mypy .

And got:

cowsay_via_llm/cli.py:2: error: Skipping analyzing "llm": module is installed, but missing library stubs or py.typed marker  [import-untyped]
cowsay_via_llm/cli.py:2: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
Found 1 error in 1 file (checked 4 source files)

[simonw]

I changed the dependencies to:

dependencies = [
    "click",
    "llm @ git+https://github.com/simonw/llm.git@py.typed"
]

(I had to use that @ git syntax, the regular URL didn't work as it did not end in .zip)

Then I ran this:

uv sync --extra test
uv run mypy .

And it passed!

Success: no issues found in 4 source files

[simonw]

Then I mucked around with the code:

import click
import llm

SYSTEM = """
Render this as ASCII art like cowsay does.
Return plain text no markdown or fenced code block
""".strip()


@click.command()
@click.argument("texts", nargs=-1)
def cli(texts):
    "cowsay with an LLM"
    click.echo(say(texts))


def say(texts) -> str:
    model = llm.get_model()
    return model.prompt(" ".join(texts), system=SYSTEM)

And ran uv run mypy . again and it spotted an error:

cowsay_via_llm/cli.py:19: error: Incompatible return value type (got "Response", expected "str")  [return-value]
Found 1 error in 1 file (checked 4 source files)

This is definitely working.