fix(typing): preserve decorated function type signatures with ParamSpec

[gencurrent]

I encounter this issue with Pyrefly constantly: the declared return type of the decorated function / method does not match the expected return type, so I have to add # ... ignore ... comments.

The @cachier decorator erases all type information from decorated functions. Because cachier() has no return type annotation and no generic type variables, type checkers see every decorated function -- both its signature and return value -- as Any:

@cachier()
def my_func(x: int) -> str:
    return str(x)

reveal_type(my_func)      # Any
reveal_type(my_func(5))   # Any

This breaks IDE autocomplete, disables type error detection on wrong arguments, and forces downstream typed codebases to use stubs or type: ignore.

Changes

• src/cachier/core.py: Add ParamSpec/TypeVar generics to cachier(), _cachier_decorator(), and func_wrapper so the original function signature is preserved through the decorator
• tests/test_typing.py: 12 mypy-based tests covering sync, async, complex signatures, wrong-arg rejection, and decorator argument variants
• tests/requirements.txt: Add mypy as a test dependency
  After:

reveal_type(my_func)      # (x: int) -> str
reveal_type(my_func(5))   # str

⚠️ The docstring step is skipped in the CI pipeline.

[shaypal5]

Looks good. Let's wait and see what CoPilot says. :)

[Copilot]

Pull request overview

This PR aims to improve Cachier’s static typing experience by preserving decorated function signatures/return types (especially for tools like mypy/Pyrefly) using ParamSpec + TypeVar, and adds a mypy-driven test suite to validate the behavior.

Changes:

• Add ParamSpec/TypeVar generics to cachier() and its internal decorator/wrapper to preserve function signatures through decoration.
• Add tests/test_typing.py which runs mypy programmatically to assert signature/return-type preservation for sync/async functions and some decorator argument variants.
• Add mypy to tests/requirements.txt so the typing tests can run in CI.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
src/cachier/core.py	Introduces generic typing for the decorator/wrapper to preserve callable signatures and return types.
tests/test_typing.py	Adds mypy-based tests that validate the preserved typing behavior via reveal_type and error assertions.
tests/requirements.txt	Adds mypy as a test dependency to enable running the typing tests.

[gencurrent]

Now there's a test fail with
failed to connect to the docker API at npipe:////./pipe/docker_engine; check if the path is correct and if the daemon is running: open //./pipe/docker_engine: The system cannot find the file specified.

[shaypal5]

Now there's a test fail with failed to connect to the docker API at npipe:////./pipe/docker_engine; check if the path is correct and if the daemon is running: open //./pipe/docker_engine: The system cannot find the file specified.

I don't know. I'm looking at it now, and the only red flow is codecov's. Please take a look at CoPilot's comments, treat anything valid, resolve as rejected anything that's not, raise patch test coverage to 100% (it's currently at 96.42%), and i'll merge this sucker.

[gencurrent]

Now there's a test fail with failed to connect to the docker API at npipe:////./pipe/docker_engine; check if the path is correct and if the daemon is running: open //./pipe/docker_engine: The system cannot find the file specified.

I don't know. I'm looking at it now, and the only red flow is codecov's. Please take a look at CoPilot's comments, treat anything valid, resolve as rejected anything that's not, raise patch test coverage to 100% (it's currently at 96.42%), and i'll merge this sucker.

Perhaps it failed just once yesterday between some of my commits.
Thank you : ) I replied to all the comments and fixed the relevant ones and replied to each.

[gencurrent]

The pre-commit.ci - pr failure is unrelated to this PR - it's a build error in untokenize (a transitive dep of docformatter v1.7.7 pinned in .pre-commit-config.yaml) on Python 3.12+, where ast.Constant.s was removed.

Note that the GitHub Actions pre-commit job passes (different Python version). Could you either:

1. Bump docformatter in .pre-commit-config.yaml to a newer rev (outside the scope of this PR), or
2. Merge anyway since the real pre-commit check passes?

[gencurrent]

I think it's docformatter: cachier uses it, but the project (https://github.com/PyCQA/docformatter) hasn't been released for almost a year, since May of 2025.

[gencurrent]

@shaypal5 Ready!
But with one caveat: ⚠️ The `docstring` step is skipped in the CI pipeline.