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.

[gioannidis]

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.

@svlandeg This has been duly noted, thanks!

Option B: Reset Module Annotations in an Autouse Fixture

@CAOShurong, thanks a lot for your input and analysis, it's really appreciated. Option B appears to work until a proper fix has been pushed.

It should be noted that it does not work in isolation. The typer imports should be refactored with module_import.patch due to the pyfakefs issue #1334.

Option C: Explicit path_type in Typer

this breaks the outer-RealFs test when running after the outer-FakeFs. Applied patch:

--- typer_fakepyfs.py.orig
+++ typer_fakepyfs.py
@@ -7,7 +7,9 @@
 from typer import testing
 
 
-def outer_echo(path: Annotated[pathlib.Path, typer.Argument()]) -> None:
+def outer_echo(
+    path: Annotated[pathlib.Path, typer.Argument(path_type=pathlib.Path)],
+) -> None:
     print(path)
 
 

Assuming that the typer imports have been already refactored (see above):

pytest typer_fakepyfs.py --random-order-seed=1 -v -k outer
typer_fakepyfs.py::test_with_pyfakefs[outer-FakeFs] [SMALL] PASSED
typer_fakepyfs.py::test_with_pyfakefs[outer-RealFs] [SMALL] FAILED

>       assert "test" in result.stdout
E       AssertionError: assert 'test' in ''
E        +  where '' = <Result AssertionError('assert None is not None')>.stdout

This appears to be from typer itself, as the command does not run at all.

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

This is testing CLI commands in "production" files, so defining the commands in fixtures is not possible.

Proposed Pull Request

As a first step, I propose a pull request based on module_import.patch.

Key points:

• ⚙️ Refactors imports by importing the entire module: from pathlib import Path -> import pathlib
• ✔️ Is a refactor with no behavioral change
• 👍 Follows best practices, recommended by the Google and the Khan Academy style guides [1]
• ➰ Allows working around the pyfakefs issue #1334 by resetting annotations in a fixture, as proposed by @CAOShurong
• ❌ Does not directly solve the cross-test pollution caused by cached annotation; requires a workaround

Looking forward to the project team's feedback prior to sending the PR, per the contributing guidelines.

[1] Importing individual classes, instead of modules, introduces issues in mocking. An object must be patched where it is looked up and not necessarily where it is being defined. As a result, importing classes directly leads to unintuitive patching syntax. Example, to patch A.MyClass, one should write @patch("B.MyClass") if module B imports it as from A import MyClass.

[WAHIB-EL-KHADIRI]

@CAOShurong's breakdown is right that Typer holds no cache of its own, but point 2 needs a correction that turns out to be the whole explanation for the order-dependence you are seeing — and it depends on which Python you run.

annotations (func.__annotations__) are evaluated once at function definition time (when the module is imported)

That is true up to 3.13 and false from 3.14, where PEP 649 makes annotations lazy. They are evaluated on first access and cached from then on.

Measured on the same script, swapping pathlib.Path after the function is defined but before any annotation is read:

===== Python 3.12.10 =====
has __annotate__ (PEP 649): False
direct-annot after swap -> Path      (is FakePath: False)

===== Python 3.14.4 =====
has __annotate__ (PEP 649): True
direct-annot after swap -> FakePath  (is FakePath: True)

So on 3.14 a module-level def outer_echo(path: Annotated[pathlib.Path, ...]) does not necessarily hold the real pathlib.Path. It holds whatever pathlib.Path happened to be when something first read its annotations — which, in a test session, is whichever test ran first.

Why it is sticky, and why the last test fails

The part that produces cross-test pollution is that on both versions, once materialised the value is frozen:

1st access (real installed):     Path
2nd access (FakePath installed): Path      -> changed: False

g defined+first-read under FakePath:
g 1st (fake): FakePath | g 2nd (real restored): FakePath  -> sticky: True

Only the timing of that one-time materialisation differs — definition time on ≤3.13, first-access time on 3.14+. Either way the first resolution wins permanently, so whichever of your FakeFs/RealFs parametrisations gets there first decides the answer for every later test. That is exactly why reordering with pytest-random-order moves the failure onto the last test rather than fixing it, and why your fixture-level inner_echo works: it is a new function object per test, so it re-materialises each time.

A fix that does not require redefining the command

Make the annotation deferred, so Typer's get_type_hints() re-resolves it against the module globals on every invocation instead of reading a frozen value. Verified on both interpreters:

python: 3.12.10
get_type_hints: real->Path fake->FakePath real->Path
re-resolves each call: True

python: 3.14.4
get_type_hints: real->Path fake->FakePath real->Path
re-resolves each call: True

Concretely, either quote it or add the future import at the top of the module holding the command:

from __future__ import annotations

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

Because get_type_hints evaluates the string against sys.modules[func.__module__].__dict__ at call time, the module-level command then picks up whichever pathlib.Path pyfakefs currently has installed, and the tests stop depending on order. This also keeps working on 3.14, where the eager-binding assumption no longer holds.

One caveat worth stating plainly: this makes the annotation resolution order-independent, but it does not fix the underlying pyfakefs issue you linked (#1334) — FakePath still has to be something get_click_type recognises. It removes the ordering variable so that the remaining failure is deterministic and actually about the type, which is the part worth fixing upstream.