FIX: stubs and ConfigSource doc

[TTsangSC]

This PR addresses the following issues with recent PRs. (Note that there is no actual behavior change on the code-side).

Typing bugs

• line_profiler.cli_utils.add_argument(ArgumentParser(...), ...) actually fails type check.
• The stubs for the following types are botched:
  • line_profiler.toml_config.ConfigSource should have a .path field instead of a .source field.
  • line_profiler.scoping_policy.ScopingPolicy is missing an .EXACT item.

These typing bugs went under our nose because we only do stubs, and thus mypy don't really look into how we're using any of these. But mypy flared up the moment I installed the line_profiler in a non-editable way in another project, which got me investigating... and here we are. This PR remedies the above bugs.

While we're at it, I also updated the stubs for line_profiler.profiler_mixin.ByCountProfilerMixin.wrap_*() and line_profiler.line_profiler.LineProfiler.__call__() so that we get better parametrizations for the param specs and return values (e.g. p: partial[int] = ...; p_profiled = reveal_type(profile(p)) gives partial[int] instead of partial[Any]).

Lacking docs

Shortly after finishing #335 I realized that we never explained whence the config file is looked up (i.e. the current directory's and its ancestors' line_profiler.toml and pyproject.toml) in the online docs, because neither line_profiler.toml_config.find_and_read_config_file() nor .TARGETS is in .__all__, and they are thus omitted from the built doc pages. The PR thus rewrites the docstring for line_profiler.toml_config.ConfigSource.from_config() to (1) be more clear, and (2) document the aforementioned lookup targets and mechanism.

[TTsangSC]

Apropos, I appreciate the rationale behind separating the type annotations into their own stub files:

• This allow for writing more concise type annotations (e.g. dict[int, str | int] instead of typing.Dict[int, typing.Union[str, int]]) without worrying about the code being valid Python in legacy versions.
• This prevents complex function signatures and @typing.overloads from cluttering code files.

However, this does prevent mypy from looking into much of the codebase and actually type-checking it. I wonder if --check-untyped-defs would solve this, or if it will cause more trouble than it's worth.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.18%. Comparing base (60e928f) to head (10005a2).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #367      +/-   ##
==========================================
+ Coverage   87.56%   88.18%   +0.61%     
==========================================
  Files          18       20       +2     
  Lines        1641     1862     +221     
  Branches      348      401      +53     
==========================================
+ Hits         1437     1642     +205     
- Misses        149      160      +11     
- Partials       55       60       +5     

Files with missing lines	Coverage Δ
line_profiler/cli_utils.py	88.88% <ø> (ø)
line_profiler/toml_config.py	93.44% <ø> (ø)

... and 1 file with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9616f7e...10005a2. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Erotemic]

LGTM.

Would running mypy on an installed wheel help in the CI? Strange that it picks up stubs in non-editable mode, but not in editable mode.

[TTsangSC]

Upon closer inspection, this seems to be two separate problems and they are deeper than I suspected:

What's wrong with editable installs?

Strange that it picks up stubs in non-editable mode, but not in editable mode.

The problem was that if line_profiler is installed as editable, when we type-check another project, mypy can't seem to locate ANY of line_profiler files by default, as indicated from the complete lack of line_profiler-related output in mypy --verbose. It seems that the static analysis it uses neglects the __editable___*_finder.py and __editable__.*.pth hooks (see also python/mypy#13392). Nothing we can do on our end it seems – downstream package maintainers will have to install line_profiler in a non-editable manner.

... unless we're willing to write and maintain a mypy plugin to resolve said hooks. Technically we do have the tech for doing so in line_profiler.autoprofile.util_static, but doing that seems to be out of scope for this project, and (unlike pytest plugins) would still require downstream projects to manually configure for said plugin to be used.

Is our code type-checked at all?

Would running mypy on an installed wheel help in the CI?

Unfortunately no. The problem seems to be that if a stub file exists, mypy just doesn't see the Python source file AT ALL:

Hence even with --check-untyped, only the errors in _logger.py and _diagnostics.py are exposed (which BTW we should maybe fix in another PR), but not the mock error I deliberately wrote in line_profiler.py (the short_string_path(1), where said function only takes path-likes).

Trying to explicitly include both the *.py and *.pyi files in the type check however causes an error:

(py3.13)  $ find line_profiler \( -name '*.py' -o -name '*.pyi' \) | xargs mypy --check-untyped
line_profiler/line_profiler_utils.py: error: Duplicate module named "line_profiler.line_profiler_utils" (also at "line_profiler/line_profiler_utils.pyi")
line_profiler/line_profiler_utils.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
line_profiler/line_profiler_utils.py: note: Common resolutions include: a) using `--exclude` to avoid checking one of them, b) adding `__init__.py` somewhere, c) using `--explicit-package-bases` or adjusting MYPYPATH
Found 1 error in 1 file (errors prevented further checking)

The only way out seem to be doing something like

find line_profiler -name '*.py' | xargs mypy --check-untyped

but that obviously ignores information present in the *.pyi files. So such type-checking can at most make the Python code self-consistent in terms of typing... but then we still have no ways of guaranteeing consistency of the stubs with the actual code.