Cached parameter annotations introduce cross-test pollution when Path is mocked

[gioannidis]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the documentation, with the integrated search.
• I already searched in Google "How to X" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.

Example Code

#!/usr/bin/env python3
import pathlib
from typing import Annotated

import pytest
import typer
from typer import testing


def outer_echo(path: Annotated[pathlib.Path, typer.Argument()]) -> None:
    print(path)


@pytest.fixture
def app(should_use_inner_echo: bool) -> typer.Typer:
    """Provides a clean application to each test case."""

    def inner_echo(path: Annotated[pathlib.Path, typer.Argument()]) -> None:
        print(path)

    test_app: typer.Typer = typer.Typer()
    _ = test_app.command("echo")(inner_echo if should_use_inner_echo else outer_echo)
    return test_app


@pytest.mark.small
@pytest.mark.parametrize(
    "should_use_fakefs",
    [True, False],
    ids=["FakeFs", "RealFs"],
)
@pytest.mark.parametrize(
    "should_use_inner_echo",
    [True, False],
    ids=["inner", "outer"],
)
def test_with_pyfakefs(
    request: pytest.FixtureRequest,
    app: typer.Typer,
    should_use_fakefs: bool,
) -> None:
    if should_use_fakefs:
        _ = request.getfixturevalue("fs")

    runner: testing.CliRunner = testing.CliRunner()
    result: testing.Result = runner.invoke(app=app, args="/path/to/test.txt")

    assert "test" in result.stdout

Description

First of all, thanks for your hard work, @tiangolo. Typer is truly an amazing project!

I'm opening this thread:

1. to understand how commands and their annotations, when defined at a module-level, are cached, and
2. to discuss, per the contribution guidelines a proposed fix, prior to sending a pull request.

Context

• I have developed a CLI using typer, which takes a pathlib.Path as an argument
• The production code and testing with the actual pathlib.Path work as expected
• I use pyfakefs to abstract I/O operations for unit testing, which replaces pathlib.Path with a subclass FakePath; these tests may fail based on their execution order

Sample test cases

The code snippet shared above implements a simple echo command in two different ways:

• an outer_echo function, defined at module-level
• an inner_echo function, defined at fixture level, which provides a "clean" command to every test case

A clean typer.Typer application is provided to every test.

Each test case runs twice:

1. With the real pathlib.Path
2. With the in-memory pyfakefs.fake_pathlib.FakePath

Required packages

• pyfakefs
• pytest
• pytest-random-order (to validate cross-test pollution)

Test results

v0.27.2: all FakeFs tests fail

Test execution: (include the trailing ] in the pattern)

$ pytest typer_pyfakefs.py -k "FakeFs]" --tb=no
FAILED typer_pyfakefs.py::test_with_pyfakefs[inner-FakeFs] - RuntimeError: Type not yet supported: <class 'pyfakefs.fake_pathlib.FakePath'>
FAILED typer_pyfakefs.py::test_with_pyfakefs[outer-FakeFs] - RuntimeError: Type not yet supported: <class 'pyfakefs.fake_pathlib.FakePath'>

Key findings:

• All tests fail when using the FakePath
• The exception is thrown from get_click_type
• This bug originates from pyfakefs (see issue#1334); can be partially mitigated by replacing Path → pathlib.Path

Patch: module imports

I've worked around the pyfakefs bug by replacing direct class imports with module imports. See: module_import.patch

This patch passes both tests using the inner_echo command, i.e., when the function is redefined for each test:

$ pytest typer_pyfakefs.py -k "inner"

typer_pyfakefs.py::test_with_pyfakefs[inner-FakeFs] PASSED
typer_pyfakefs.py::test_with_pyfakefs[inner-RealFs] PASSED

However, the tests using the outer_echo command are still failing. In particular, the last executed test fails. Below, the test with the real pathlib.Path is executed last - and fails:

$ pytest typer_pyfakefs.py -k "outer" -v --tb=no --random-order-seed=1

typer_pyfakefs.py::test_with_pyfakefs[outer-FakeFs] PASSED
typer_pyfakefs.py::test_with_pyfakefs[outer-RealFs] FAILED

FAILED typer_pyfakefs.py::test_with_pyfakefs[outer-RealFs] - RuntimeError: Type not yet supported: <class 'pyfakefs.fake_pathlib.FakePath'>

Below, the test with the in-memory fake_pathlib.FakePath is executed last - and fails:

$ pytest typer_pyfakefs.py -k "outer" -v --tb=no --random-order-seed=2

typer_pyfakefs.py::test_with_pyfakefs[outer-RealFs] PASSED
typer_pyfakefs.py::test_with_pyfakefs[outer-FakeFs] FAILED

FAILED typer_pyfakefs.py::test_with_pyfakefs[outer-FakeFs] - RuntimeError: Type not yet supported: <class 'pathlib.Path'>

Patch using lenient_issubclass

I have applied a further patch, replacing annotation == Path → lenient_issubclass(annotation, pathlib.Path). See:
lenient_subclass.patch

With this patch, both test cases with outer_echo pass when the FakeFs is executed first:

$ pytest typer_pyfakefs.py -k "outer" -v --tb=no --random-order-seed=1

typer_pyfakefs.py::test_with_pyfakefs[outer-FakeFs] PASSED
typer_pyfakefs.py::test_with_pyfakefs[outer-RealFs] PASSED

However, the FakeFs test fails when it's executed last:

$ pytest typer_pyfakefs.py -k "outer" -v --tb=no --random-order-seed=2

typer_pyfakefs.py::test_with_pyfakefs[outer-RealFs] PASSED
typer_pyfakefs.py::test_with_pyfakefs[outer-FakeFs] FAILED

FAILED typer_pyfakefs.py::test_with_pyfakefs[outer-FakeFs] - RuntimeError: Type not yet supported: <class 'pathlib.Path'>

An introspection with inspect in the latter test case shows that:

• The annotation module is /home/user/.local/share/uv/python/cpython-3.14.6-linux-x86_64-gnu/lib/python3.14/pathlib/__init__.py
• The pathlib.Path module is /path/to/.venv/lib/python3.14/site-packages/pyfakefs/fake_pathlib.py, because it has been replaced by FakePath

As I understand it:

• The outer_echo command is registered once, when the first test runs.
• Since the real pathlib.Path is run first, the command is registered with a pathlib.Path annotation.
• The annotation remains pathlib.Path when the second test runs.
• In the second test, Path has been replaced by FakePath. The test fails because Path is not a subclass of FakePath (but the other way around).

Note that all bash/test.sh test cases pass with this patch.

Patch: double lenient_issubclass

Finally, I applied a double subclass check in double_subclass.patch, shown briefly below:

@@ -1565,7 +1565,8 @@ def get_click_type(
     elif annotation == datetime:
         return types.DateTime(formats=parameter_info.formats)
     elif (
-        annotation == Path
+        lenient_issubclass(annotation, pathlib.Path)
+        or lenient_issubclass(pathlib.Path, annotation)
         or parameter_info.allow_dash
         or parameter_info.path_type
         or parameter_info.resolve_path

All tests pass, regardless of order.

Caveats:

• The "double issubclass" patch is unintuitive from a readability perspective.

• The patch relies on undocumented behavior, namely, that Path may be something else and that either annotation or Path can be a subclass of the other, depending on the circumstances.

• It breaks a few test cases, raising the error:

  TypeError: Subscripted generics cannot be used with class and instance checks
  

Questions

1. When defined at module level, is a typer command created once? Example: outer_echo in the test above.
2. On the same note, do the parameter annotations remain invariant, even if a type is subsequently replaced? Example: a parameter is created with the pathlib.Path annotation, but subsequently the type is replaced by pyfakefs.fake_pathlib.FakePath.
3. Where exactly is the command/parameter "state" cached? In the test above, we are creating a fresh typer.Typer application in every test. Yet, there is cross-test pollution, indicating that the parameter annotations are cached somewhere else.
4. What's a recommended way to force a command / group to be rebuilt between tests, when it is defined at a module level?
5. Should a pull request be created? At a very minimum, the change Path → pathlib.Path is a no-op.

Files

• module_import.patch
• lenient_subclass.patch
• double_subclass.patch

Operating System

Linux

Operating System Details

Debian 7.1.3-1

Project Version

0.27.2

Python Version

3.14.6

Additional Context

• Linux-7.1.3+deb14-amd64-x86_64-with-glibc2.43
• Python 3.14.6 (main, Jun 23 2026, 15:18:23) [Clang 22.1.3 ]
• pyfakefs 6.2.0
• pytest 9.1.1
• typer 0.27.2

[CAOShurong]

Here is a comprehensive breakdown of what is happening under the hood and direct answers to your 5 questions:

---

1. When defined at module level, is a typer command created once?

The Python function object is created once; the Click command is created on invocation.

• When your test file is imported by pytest, Python executes the module body once and creates the outer_echo function object as a module-level singleton.
• In typer, calling @app.command() merely registers a CommandInfo(callback=outer_echo, ...) on the app.registered_commands list.
• Even when your test creates a fresh app = typer.Typer() and registers outer_echo, that new app still references the exact same module-level outer_echo function object in memory.

---

2. Do the parameter annotations remain invariant, even if a type is subsequently replaced?

Yes, absolutely.

• In Python, annotations (func.__annotations__) are evaluated once at function definition time (when the module is imported). The dictionary key 'path' is bound directly to the in-memory pathlib.Path class object that was in scope at that instant.
• When pyfakefs runs later during a test case, it monkeypatches the module attribute pathlib.Path = FakePath. It does not (and cannot safely) traverse all existing function objects in memory across loaded modules to rewrite their __annotations__ dictionaries.
• Therefore, outer_echo.__annotations__['path'] remains permanently bound to the original CPython pathlib.Path object created at Python startup.

---

3. Where exactly is the command/parameter "state" cached?

It is not cached in Typer or Click at all.

There is no lru_cache, singleton cache, or internal param store in typer.main. Every time CliRunner.invoke(app, ...) or get_command(app) is executed, Typer dynamically introspects the callback via inspect.signature(func) and get_type_hints(func).

The perceived "cache" and cross-test pollution is entirely due to the lifespan of the Python function object:

1. When get_click_type(annotation, parameter_info) is evaluated, it compares:

   elif (
       annotation == Path
       ...
   ):

2. annotation is retrieved from func.__annotations__ (which holds the original pathlib.Path).
3. If Path in the current scope has been swapped by pyfakefs to FakePath, annotation == Path is original_Path == FakePath, which is False!
4. Because the condition evaluates to False, Typer falls through to:

   raise RuntimeError(f"Type not yet supported: {annotation}")

---

4. What is the recommended way to handle this between tests?

Option A (Best practice with pyfakefs): Function/Fixture Scope

Define commands inside fixtures or test functions (like your inner_echo). Because the def statement executes after pyfakefs has established its patches, the function's __annotations__ naturally resolve to FakePath in mock runs and real Path in non-mock runs.

Option B: Reset Module Annotations in an Autouse Fixture

If your commands must be defined at the module level, reset the function's annotation dictionary in a pytest fixture so it resolves to the currently active pathlib.Path:

@pytest.fixture(autouse=True)
def sync_typer_annotations():
    import pathlib
    outer_echo.__annotations__["path"] = pathlib.Path
    yield

Option C: Explicit path_type in Typer

In typer.Option or typer.Argument, passing path_type or enabling path flags bypasses the strict annotation == Path branch in get_click_type:

import pathlib
import typer

def outer_echo(path: pathlib.Path = typer.Argument(..., path_type=pathlib.Path)):
    ...

---

5. Should a pull request be created in Typer?

Yes, a PR would be very welcome and valuable.

Checking annotation == Path via exact identity is fragile in modern Python ecosystems:

1. It fails on valid subclasses of Path (such as pyfakefs.fake_pathlib.FakePath or custom virtual path types).
2. It fails on related standard path abstractions like os.PathLike or pathlib.PurePath.

In typer/main.py, replacing:

    elif (
        annotation == Path
        or parameter_info.allow_dash
        or parameter_info.path_type
        or parameter_info.resolve_path
    ):

with:

    elif (
        lenient_issubclass(annotation, (pathlib.PurePath, os.PathLike))
        or parameter_info.allow_dash
        or parameter_info.path_type
        or parameter_info.resolve_path
    ):

is semantically robust, eliminates the strict object identity pitfall, and remains 100% backward-compatible with Click and existing Typer applications.

[svlandeg]

Yes, a PR would be very welcome and valuable.

Please note that this post was NOT written by a maintainer! Only maintainers can give confirmation for this.