chore: Add numpy typing plugin

[kratsg]

Pull Request Description

Add numpy typing plugin

Checklist Before Requesting Reviewer

• Tests are passing
• "WIP" removed from the title of the pull request
• Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

• Summarize commit messages into a comprehensive review of the PR

* Add numpy typing plugin for improved type checking.
   - c.f. https://numpy.org/doc/2.1/reference/typing.html
* Add additional docstring example.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.23%. Comparing base (157fc95) to head (ebfaad9).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2566   +/-   ##
=======================================
  Coverage   98.23%   98.23%           
=======================================
  Files          65       65           
  Lines        4190     4190           
  Branches      452      452           
=======================================
  Hits         4116     4116           
  Misses         45       45           
  Partials       29       29           

Flag	Coverage Δ
contrib	98.11% <ø> (ø)
doctest	98.23% <ø> (ø)
unittests-3.10	96.42% <ø> (ø)
unittests-3.11	96.42% <ø> (ø)
unittests-3.12	96.42% <ø> (ø)
unittests-3.13	96.42% <ø> (ø)
unittests-3.9	96.46% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[kratsg]

ping @matthewfeickert

[matthewfeickert]

@kratsg This is great overall, but I have a few questions that I've left as review comments.

The other thing that I wanted to get your 👍 / 👎 on is that this is a pretty dang big PR (for good reason!). As we know that there's going to be some CI failures that we have to fix anyway, how do you feel about pulling all of the "drop TensorFlow" stuff out into a seperate PR so that this gets more atomic? Given that you've done all the work for this PR by yourself, I'm happy to volunteer to do that PR so that I don't give you Git surgery.

[kratsg]

The other thing that I wanted to get your 👍 / 👎 on is that this is a pretty dang big PR (for good reason!). As we know that there's going to be some CI failures that we have to fix anyway, how do you feel about pulling all of the "drop TensorFlow" stuff out into a seperate PR so that this gets more atomic? Given that you've done all the work for this PR by yourself, I'm happy to volunteer to do that PR so that I don't give you Git surgery.

It's impossible. We've pushed this PR so far back that we have to drop pytorch AND tensorflow AND have these fixes just to have a working CI. I cannot tell you what to fix if you just drop one dependency without fixing the existing CI. You're stuck with this big PR I think.

[matthewfeickert]

Just a few questions, but other than that this is basically there.

[matthewfeickert]

@kratsg Why are these additional import changes needed? PR #2625 is a subset of this (involves a cherry-pick+squash) and it doesn't require those changes.

[kratsg]

@kratsg Why are these additional import changes needed? PR #2625 is a subset of this (involves a cherry-pick+squash) and it doesn't require those changes.

because you didn't bump the minimum mypy version for python to 3.10. This changes enough in python typing (we shouldn't use 3.9 for typing).

[matthewfeickert]

because you didn't bump the minimum mypy version for python to 3.10. This changes enough in python typing (we shouldn't use 3.9 for typing).

@kratsg I did though: https://github.com/scikit-hep/pyhf/pull/2625/files#r2495650423

From my fork's branch

$ git diff upstream/main  origin/build/drop-python-3-8-support -- .pre-commit-config.yaml
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 07539686..ef188fe0 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -55,14 +55,15 @@ repos:
 -   repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.13.0
     # check the oldest and newest supported Pythons
+    # except skip python 3.9 for numpy, due to poor typing
     hooks:
       - &mypy
         id: mypy
-        name: mypy with Python 3.8
+        name: mypy with Python 3.10
         files: src
         additional_dependencies:
           ['numpy', 'types-tqdm', 'click', 'types-jsonpatch', 'types-pyyaml', 'types-jsonschema', 'importlib_metadata', 'packaging']
-        args: ["--python-version=3.8"]
+        args: ["--python-version=3.10"]
       - <<: *mypy
         name: mypy with Python 3.13
         args: ["--python-version=3.13"]

or just comparing to this PR's branch

$ git diff upstream/fix/ci origin/build/drop-python-3-8-support -- .pre-commit-config.yaml
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index b22720ce..ef188fe0 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -65,8 +65,8 @@ repos:
           ['numpy', 'types-tqdm', 'click', 'types-jsonpatch', 'types-pyyaml', 'types-jsonschema', 'importlib_metadata', 'packaging']
         args: ["--python-version=3.10"]
       - <<: *mypy
-        name: mypy with Python 3.12
-        args: ["--python-version=3.12"]
+        name: mypy with Python 3.13
+        args: ["--python-version=3.13"]
 
 -   repo: https://github.com/codespell-project/codespell
     rev: v2.3.0

[matthewfeickert]

Thanks @kratsg.