Merge branch 'master' into improve-linear-search-edge-case

Author: cclauss

.github/pull_request_template.md

@@ -17,4 +17,4 @@
 * [ ] All function parameters and return values are annotated with Python [type hints](https://docs.python.org/3/library/typing.html).
 * [ ] All functions have [doctests](https://docs.python.org/3/library/doctest.html) that pass the automated testing.
 * [ ] All new algorithms include at least one URL that points to Wikipedia or another similar explanation.
-* [ ] If this pull request resolves one or more open issues then the description above includes the issue number(s) with a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue): "Fixes #ISSUE-NUMBER".
+* [ ] If this pull request resolves one or more open issues, then the description above includes the issue number(s) with a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue): "Fixes #ISSUE-NUMBER".

.github/skills/new-pull-request/SKILL.md

@@ -19,7 +19,13 @@ hand. A hand-modified `uv.lock` makes the `algorithms-keeper` bot close the pull
 request as invalid, and even a repo maintainer cannot undo that.
 
 Always check at least one Markdown checkbox in the pull request description (the "Describe your change" section), or the
-`algorithms-keeper` bot will close the pull request as invalid. Any repo maintainer can undo this if you @mention them on the closed pull request.
+`algorithms-keeper` bot will close the pull request as invalid — and it does
+this *before* a human reads the PR, so a genuinely good change gets closed for a
+formatting reason. This applies to **every** pull request, including CI, docs,
+and tooling changes that are not algorithms: tick the boxes that genuinely apply
+so the body is never submitted with all boxes empty. Any repo maintainer can
+undo this if you @mention them on the closed pull request, but re-opening is
+often unreliable, so it is far better to get it right the first time.
 
 ### 1. Before contributing / Is this an algorithm?
 
@@ -55,3 +61,15 @@ Always check at least one Markdown checkbox in the pull request description (the
 - [ ] At least one **Wikipedia (or equivalent) URL** documenting the algorithm.
 - [ ] Docstring explains what the function does and its parameters/returns.
 - [ ] No unnecessary third-party dependencies.
+
+## Before you click "Create pull request"
+
+This is the final gate. Do not open the pull request until every item here is true:
+
+- [ ] At least one Markdown checkbox in the PR description is checked. **Verify
+      this by re-reading the rendered body** — if every box is still `- [ ]`, the
+      `algorithms-keeper` bot will auto-close the PR before any human sees it.
+      Check the boxes that genuinely apply to this change; never submit an
+      all-empty checklist, even for a CI, docs, or tooling PR.
+- [ ] The branch is not `master`, and `master` is synced with `upstream/master`.
+- [ ] `uv.lock` was not hand-edited.

.github/skills/review-open-issue/SKILL.md

@@ -0,0 +1,110 @@
+# Skill: Review an open issue for TheAlgorithms/Python
+
+Triage an open issue — most often one carrying the `bug` label — **together with
+every pull request attached to it**, and produce a verdict a maintainer can act on
+without re-doing the work. The goal is a review that any triager (human or AI) can
+run the same way every time, and that ends in an explicit list of `Closes #NNNNN`
+lines the maintainer can paste into a merge commit.
+
+This repo exists to **teach visitors to fix bugs by doing**. So the default is to
+merge adequate existing contributor work, not to open a fresh PR that races them.
+Only open your own PR when no attached PR adequately solves the issue.
+
+## How to run this skill
+
+### 1. Reproduce before you trust the report
+
+- Check out current `master` and actually **run the failing case** from the issue.
+- If it reproduces, say so and paste the minimal reproducer (inputs → observed
+  output, e.g. `nan` + a `RuntimeWarning`).
+- If you **cannot** confirm it locally — an optional dependency isn't installed,
+  the failure needs an external service, the report is too vague — **say that
+  explicitly rather than guessing.** "Not reproducible in a vanilla checkout"
+  is a real, useful verdict.
+
+### 2. Classify the issue
+
+Sort each issue into one bucket and act accordingly:
+
+- **Confirmed bug with an adequate open PR** → recommend the specific PR to merge.
+- **Confirmed bug, no adequate PR** → open a new PR yourself (see step 5).
+- **Not a bug / working-as-intended** → recommend closing, and explain why (e.g.
+  binary search returning *an* index of a duplicate is correct, not a defect).
+- **Feature request mislabeled as a bug** → recommend dropping the `bug` label; do
+  **not** close it as a bug.
+- **Too vague / needs reporter info** → comment **on the issue itself** asking for
+  the one concrete thing missing (a file path, a traceback, a reproducer), and note
+  it should be closed if no answer arrives.
+- **Environment / optional-dependency, not an algorithm defect** → note it needs
+  someone with that environment; it is not fixable in a vanilla checkout.
+
+### 3. Examine every attached PR — pick one, name the duplicates
+
+For a bug with several open PRs:
+
+- **Verify each fix's doctest values numerically** against a trusted reference
+  (`scipy`, `numpy.linalg`, `geopy`, or a brute-force check over random inputs).
+  Don't take a doctest's word for it — confirm the number.
+- Prefer the **first-in PR with the smallest correct diff** that follows repo
+  convention (doctests over new test files, `raise` over `assert`, no unrelated
+  reindentation or churn of clean doctests into floating-point noise).
+- **Reject out-of-scope "fixes"** — e.g. swapping a real divide-by-zero for a
+  `1e-15` magic constant makes results implementation-defined. Fix the issue, not
+  more.
+- Identify the byte-for-byte **duplicates** so the maintainer can close them with
+  thanks in the same action.
+
+### 4. Emit the verdict — fixed output shape
+
+Post one comment that a maintainer can act on directly. For each issue give a
+one-line rationale and the exact autoclose line. Two formatting rules matter a lot
+to human maintainers scanning the thread:
+
+- **Start every line that references an issue or PR with a Markdown list marker
+  (`-` or `* `).** GitHub-flavored Markdown only autolinks `#NNNNN` inside a list,
+  and those autolinks are colored — **purple = merged, red = closed, green = open** —
+  so the maintainer can see merge/close progress at a glance. A bare `#14813` at the
+  start of a line does not autolink.
+- **Merging a PR that closes an issue also closes the issue's other open PRs**, so
+  fold the duplicates into one autoclose statement rather than listing the winner
+  alone:
+
+  ```text
+  * #14813 — 3x3 inverse returns the transpose → merge #14821
+    (Closes #14813, Closes #14840, Closes #15045)
+  ```
+
+Recommended shape:
+
+```text
+## Confirmed bugs with an adequate open PR — merge
+* #<issue> — <one-line what/why> → merge #<pr> (Closes #<issue>, Closes #<dupe>, …)
+
+## Not a bug / not merge-ready
+* #<issue> — <feature-request → relabel | needs cleanup | needs a human call>
+
+## Summary — lines to add
+* Closes #<issue> → #<pr>
+```
+
+### 5. When you must open your own PR
+
+If no attached PR is adequate, open one — but let the contributors keep the credit
+where their work was close. Use autoclose keywords in the **commit message body**
+so the merge closes the issue *and* the superseded PRs:
+
+```text
+Fixes #12233
+Fixes #12262
+Fixes #13635
+```
+
+Follow the [`new-pull-request`](../new-pull-request/SKILL.md) skill for the
+mechanics (synced `master`, named branch, checked description box, untouched
+`uv.lock`).
+
+## Tone
+
+Be specific and kind. Name the exact PR and the exact reason, credit the
+contributor by handle, and offer runners-up detailed feedback so they learn — the
+point of the repo is that people come back and fix the next one.

.github/workflows/build.yml

@@ -20,6 +20,12 @@ jobs:
         with:
           python-version-file: .python-version
           allow-prereleases: true
+      # keras needs hdf5 on pre-release Python.
+      - run: |
+          if [ "$(python -c 'import sys; print(sys.version_info.releaselevel)')" != "final" ]; then
+            sudo apt-get update -qq
+            sudo apt-get install --yes libhdf5-dev
+          fi
       - run: uv sync --group=test
       - name: Run tests
         # opencv-python is gated out on 3.14t (no cp314t wheel yet), so skip the

.github/workflows/hacktoberfest_prep.yml

@@ -80,6 +80,12 @@ jobs:
           fi
           git config --global user.name "$GITHUB_ACTOR"
           git config --global user.email "$GITHUB_ACTOR@users.noreply.github.com"
+          # `actions/checkout` runs with `persist-credentials: false`, so git has
+          # no token to authenticate the push below (it fails with
+          # `fatal: could not read Username for 'https://github.com'`). Wire the
+          # bundled `gh` in as git's credential helper so `git push` reuses
+          # GH_TOKEN — no third-party action and no token baked into the remote URL.
+          gh auth setup-git
           git switch -c "$BRANCH"
           git add docs/hacktober_2026_prep.md
           git commit -m "chore: refresh Hacktoberfest 2026 prep tracker"

.github/workflows/sphinx.yml

@@ -33,6 +33,12 @@ jobs:
         with:
           python-version-file: .python-version
           allow-prereleases: true
+      # keras needs hdf5 on pre-release Python.
+      - run: |
+          if [ "$(python -c 'import sys; print(sys.version_info.releaselevel)')" != "final" ]; then
+            sudo apt-get update -qq
+            sudo apt-get install --yes libhdf5-dev
+          fi
       - run: uv sync --group=docs
       - uses: actions/configure-pages@v6
       - run: uv run sphinx-build -c docs . docs/_build/html

.github/zizmor.yml

@@ -2,7 +2,6 @@ rules:
   excessive-permissions:
     disable: true
   unpinned-uses:
-    disable: true
-    # config:
-    #   policies:
-    #     actions/*: ref-pin
+    config:
+      policies:
+        "*": ref-pin

.pre-commit-config.yaml

@@ -34,13 +34,13 @@ repos:
       - id: pyproject-fmt
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.16.6
+    rev: v0.16.7
     hooks:
       - id: ruff-check
       - id: ruff-format
 
   - repo: https://github.com/rvben/rumdl-pre-commit
-    rev: v0.2.69
+    rev: v0.2.73
     hooks:
       - id: rumdl-fmt
       - id: rumdl
@@ -55,7 +55,7 @@ repos:
         pass_filenames: false
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.12.11
+    rev: 0.12.13
     hooks:
       - id: uv-lock
 

CONTRIBUTING.md

@@ -1,35 +1,35 @@
-# Contributing guidelines
+# Contributing Guidelines
 
-## Before contributing
+## Before Contributing
 
-Welcome to [TheAlgorithms/Python](https://github.com/TheAlgorithms/Python)! Before submitting your pull requests, please ensure that you __read the whole guidelines__. If you have any doubts about the contributing guide, please feel free to [state it clearly in an issue](https://github.com/TheAlgorithms/Python/issues/new) or ask the community on [Gitter](https://gitter.im/TheAlgorithms/community).
+Welcome to [TheAlgorithms/Python](https://github.com/TheAlgorithms/Python)! Before submitting your pull requests, please ensure that you __read the entire guidelines__. If you have any doubts about the contributing guide, please feel free to [state them clearly in an issue](https://github.com/TheAlgorithms/Python/issues/new) or ask the community on [Gitter](https://gitter.im/TheAlgorithms/community).
 
 ## Contributing
 
 ### Contributor
 
 We are delighted that you are considering implementing algorithms and data structures for others! This repository is referenced and used by learners from all over the globe. By being one of our contributors, you agree and confirm that:
 
-- You did your work - no plagiarism allowed.
+- You did your work — no plagiarism allowed.
   - Any plagiarized work will not be merged.
-- Your work will be distributed under [MIT License](LICENSE.md) once your pull request is merged.
+- Your work will be distributed under the [MIT License](LICENSE.md) once your pull request is merged.
 - Your submitted work fulfills or mostly fulfills our styles and standards.
 
-__New implementation__ is welcome! For example, new solutions for a problem, different representations for a graph data structure or algorithm designs with different complexity, but __identical implementation__ of an existing implementation is not allowed. Please check whether the solution is already implemented or not before submitting your pull request.
+__New implementations__ are welcome! For example, new solutions for a problem, different representations for a graph data structure, or algorithm designs with different complexities. However, __identical implementations__ of an existing one are not allowed. Please check whether the solution is already implemented before submitting your pull request.
 
 __Improving comments__ and __writing proper tests__ are also highly welcome.
 
 ### Contribution
 
-We appreciate any contribution, from fixing a grammar mistake in a comment to implementing complex algorithms. Please read this section if you are contributing your work.
+We appreciate any contribution — from fixing a grammar mistake in a comment to implementing complex algorithms. Please read this section if you are contributing your work.
 
 Your contribution will be tested by our [automated testing on GitHub Actions](https://github.com/TheAlgorithms/Python/actions) to save time and mental energy. After you have submitted your pull request, you should see the GitHub Actions tests start to run at the bottom of your submission page.
 
 If those tests fail, then click on the ___details___ button to read through the GitHub Actions output to understand the failure. If you do not understand, please leave a comment on your submission page, and a community member will try to help.
 
 #### Issues
 
-If you are interested in resolving an [open issue](https://github.com/TheAlgorithms/Python/issues), simply make a pull request with your proposed fix. __We do not assign issues in this repo__ so please do not ask for permission to work on an issue.
+If you are interested in resolving an [open issue](https://github.com/TheAlgorithms/Python/issues), simply make a pull request with your proposed fix. __We do not assign issues in this repo__, so please do not ask for permission to work on an issue.
 
 __Do not__ create an issue to contribute an algorithm. Please submit a pull request instead.
 
@@ -44,17 +44,31 @@ GitHub will use this tag to [auto-close the issue](https://docs.github.com/en/is
 
 #### What is an Algorithm?
 
-An Algorithm is one or more functions (or classes) that:
+An algorithm is one or more functions (or classes) that:
 
 - take one or more inputs,
 - perform some internal calculations or data manipulations,
 - return one or more outputs,
-- have minimal side effects (Ex. `print()`, `plot()`, `read()`, `write()`).
+- have minimal side effects (e.g., `print()`, `plot()`, `read()`, `write()`).
 
-Algorithms should be packaged in a way that makes it easy for readers to put them into larger programs.
+Algorithms should be packaged in a way that would make it easy for readers to integrate them into larger programs.
 
 Algorithms should:
 
+- have intuitive class and function names that make their purpose clear to readers,
+- use Python naming conventions and intuitive variable names to ease comprehension,
+- be flexible to take different input values,
+- have Python type hints for their input parameters and return values,
+- raise Python exceptions (`ValueError`, etc.) on erroneous input values,
+- have docstrings with clear explanations and/or URLs to source materials,
+- contain doctests that test both valid and erroneous input values,
+- return all calculation results instead of printing or plotting them.
+
+Algorithms in this repo should not be simple how-to examples for existing Python packages. Instead, they should perform internal calculations or manipulations to convert input values into different output values.
+These calculations or manipulations can use data types, classes, or functions of existing Python packages, but each algorithm in this repo should add unique value.
+
+#### Pre-Commit Plugin
+
 - have intuitive class and function names that make their purpose clear to readers
 - use Python naming conventions and intuitive variable names to ease comprehension
 - be flexible to take different input values
@@ -67,7 +81,7 @@ Algorithms should:
 Algorithms in this repo should not be how-to examples for existing Python packages. Instead, they should perform internal calculations or manipulations to convert input values into different output values.
 Those calculations or manipulations can use data types, classes, or functions of existing Python packages, but each algorithm in this repo should add unique value.
 
-#### Pre-commit plugin
+#### Pre-commit
 
 Use [pre-commit](https://pre-commit.com/#installation) to automatically format your code to match our coding style:
 
@@ -76,7 +90,7 @@ python3 -m pip install pre-commit  # only required the first time
 pre-commit install
 ```
 
-That's it! The plugin will run every time you commit any changes. If any errors are found during the run, fix them and commit those changes. You can even run the plugin manually on all files:
+That's it! Pre-commit will run every time you commit any changes. If any errors are found during the run, fix them and commit those changes. You can even run the plugin manually on all files:
 
 ```bash
 pre-commit run --all-files --show-diff-on-failure
@@ -118,12 +132,13 @@ We want your work to be readable by others; therefore, we encourage you to note
   The following are considered to be bad and may be requested to be improved:
 
   ```python
-  x = x + 2  # increased by 2
+  x += 2  # increased by 2
   ```
 
-  This is too trivial. Comments are expected to be explanatory. For comments, you can write them above, on, or below a line of code, as long as you are consistent within the same piece of code.
+  This is too trivial. Comments should not merely repeat what the code already says. Comments should explain ___why___ we are doing things. Comments on the same line as code should never cause the line to wrap (> 88 characters per line).
+Comments which are not on the same line as code should appear ___before___ the code they describe. "First tell the reader ___why___ with comments and then show them ___how___ with code."
 
-  We encourage you to put docstrings inside your functions, but please pay attention to the indentation of docstrings. The following is a good example:
+  We require you to put docstrings inside your functions, but please pay attention to the indentation of docstrings. The following is a good example:
 
   ```python
   def sum_ab(a, b):