Merge branch 'master' into docs-prompt-docstring

Author: Jarvis-J-Jacob

.github/workflows/build.yml

@@ -21,17 +21,14 @@ jobs:
           allow-prereleases: true
       - run: uv sync --group=test
       - name: Run tests
-        # TODO: #8818 Re-enable quantum tests
         run: uv run --with=pytest-run-parallel pytest
           --iterations=8 --parallel-threads=auto
           --ignore=computer_vision/cnn_classification.py
           --ignore=docs/conf.py
           --ignore=dynamic_programming/k_means_clustering_tensorflow.py
-          --ignore=machine_learning/local_weighted_learning/local_weighted_learning.py
           --ignore=machine_learning/lstm/lstm_prediction.py
           --ignore=neural_network/input_data.py
           --ignore=project_euler/
-          --ignore=quantum/q_fourier_transform.py
           --ignore=scripts/validate_solutions.py
           --ignore=web_programming/current_stock_price.py
           --ignore=web_programming/fetch_anime_and_play.py

.pre-commit-config.yaml

@@ -21,26 +21,21 @@ repos:
     hooks:
       - id: auto-walrus
 
-  - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.12.7
-    hooks:
-      - id: uv-lock
-
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.16.1
-    hooks:
-      - id: ruff-check
-      - id: ruff-format
-
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.3
     hooks:
       - id: codespell
         additional_dependencies:
           - tomli
 
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.5
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.26.0
+    rev: v2.28.1
     hooks:
       - id: pyproject-fmt
 
@@ -52,8 +47,13 @@ repos:
         language: script
         pass_filenames: false
 
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.12.7
+    hooks:
+      - id: uv-lock
+
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.25
+    rev: "0.26"
     hooks:
       - id: validate-pyproject
 

AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and their humans) contributing to
+**TheAlgorithms/Python**. This complements — and never overrides —
+[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first.
+
+This repository is educational: implementations should be clear and correct
+rather than maximally optimized. Every change goes through CI and the
+`algorithms-keeper` bot, both of which reject non-conforming PRs automatically.
+
+## Before opening a pull request
+
+- **Check at least one box in the PR description.** The `algorithms-keeper`
+  bot **closes any PR whose "Describe your change" section has no checked
+  box** (`* [x]`). Fill in the template that ships in
+  `.github/pull_request_template.md` and tick every item that applies before
+  you submit — this is the single most common reason automated PRs get closed.
+- **One algorithm file per PR.** Split unrelated changes into separate PRs to
+  keep review focused.
+- **Don't change code and its doctests in the same PR.** If you're only
+  updating tests, say so and touch nothing else.
+
+## Code conventions (enforced by CI)
+
+- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`).
+  Run `uvx pre-commit run --all-files` locally to catch everything CI will.
+- **Type hints:** annotate every function parameter and return value with
+  [type hints](https://docs.python.org/3/library/typing.html).
+- **Doctests:** every function needs at least one
+  [doctest](https://docs.python.org/3/library/doctest.html) that passes under
+  `python -m doctest -v your_file.py` (and `pytest`).
+- **Naming:** filenames are all-lowercase with underscores (no spaces or
+  dashes); functions and variables follow standard Python naming.
+- **Placement:** new files go inside an existing directory.
+- **References:** new algorithms include a URL to Wikipedia or a comparable
+  explanation.
+
+## Running the suite locally
+
+This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no
+`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx`
+runs a tool in a throwaway environment without polluting yours:
+
+```bash
+uvx pre-commit run --all-files                       # ruff, formatting, hooks
+uvx pytest your_module/your_file.py --doctest-modules
+```
+
+(`uv run pytest ...` works too if you'd rather use the project's locked
+environment.)
+
+Some directories are intentionally skipped in CI (`--ignore` entries in
+`.github/workflows/build.yml`), usually because a heavy dependency lacks a
+wheel for the CPython version the repo currently targets. Check that list
+before assuming a file is untested.
+
+## Good agent behavior
+
+- Keep diffs minimal and scoped to the stated change.
+- Preserve existing style and structure; prefer clarity over cleverness.
+- Never fabricate doctest output — run it and paste the real result.
+- If CI is red, read the log and fix the cause rather than re-running blindly.

CONTRIBUTING.md

@@ -108,7 +108,7 @@ 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 = 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.
@@ -148,7 +148,7 @@ We want your work to be readable by others; therefore, we encourage you to note
   The use of the Python built-in `input()` function is __not__ encouraged:
 
   ```python
-  input('Enter your input:')
+  input("Enter your input:")
   # Or even worse...
   input = eval(input("Enter your input: "))
   ```

DIRECTORY.md

@@ -1,6 +1,7 @@
 
 ## Audio Filters
   * [Butterworth Filter](audio_filters/butterworth_filter.py)
+  * [Equal Loudness Filter](audio_filters/equal_loudness_filter.py)
   * [Iir Filter](audio_filters/iir_filter.py)
   * [Show Response](audio_filters/show_response.py)
 
@@ -451,9 +452,11 @@
   * [Time And Half Pay](financial/time_and_half_pay.py)
 
 ## Fractals
+  * [Barnsley Fern](fractals/barnsley_fern.py)
   * [Julia Sets](fractals/julia_sets.py)
   * [Koch Snowflake](fractals/koch_snowflake.py)
   * [Mandelbrot](fractals/mandelbrot.py)
+  * [Sierpinski Carpet](fractals/sierpinski_carpet.py)
   * [Sierpinski Triangle](fractals/sierpinski_triangle.py)
   * [Vicsek](fractals/vicsek.py)
 
@@ -843,8 +846,10 @@
   * [Validate Sudoku Board](matrix/validate_sudoku_board.py)
 
 ## Networking Flow
+  * [Dinic](networking_flow/dinic.py)
   * [Ford Fulkerson](networking_flow/ford_fulkerson.py)
   * [Minimum Cut](networking_flow/minimum_cut.py)
+  * [Push Relabel](networking_flow/push_relabel.py)
 
 ## Neural Network
   * Activation Functions
@@ -1372,6 +1377,7 @@
   * [Split](strings/split.py)
   * [String Switch Case](strings/string_switch_case.py)
   * [Strip](strings/strip.py)
+  * [Suffix Automaton](strings/suffix_automaton.py)
   * [Text Justification](strings/text_justification.py)
   * [Title](strings/title.py)
   * [Top K Frequent Words](strings/top_k_frequent_words.py)

machine_learning/local_weighted_learning/local_weighted_learning.py

@@ -50,13 +50,13 @@ def weight_matrix(point: np.ndarray, x_train: np.ndarray, tau: float) -> np.ndar
         m x m weight matrix around the prediction point, where m is the size of
         the training set
     >>> weight_matrix(
-    ...     np.array([1., 1.]),
-    ...     np.array([[16.99, 10.34], [21.01,23.68], [24.59,25.69]]),
-    ...     0.6
-    ... )
-    array([[1.43807972e-207, 0.00000000e+000, 0.00000000e+000],
-           [0.00000000e+000, 0.00000000e+000, 0.00000000e+000],
-           [0.00000000e+000, 0.00000000e+000, 0.00000000e+000]])
+    ...     np.array([16.99, 10.34]),
+    ...     np.array([[16.99, 10.34], [21.01, 23.68], [24.59, 25.69]]),
+    ...     5,
+    ... ).round(4)
+    array([[1.    , 0.    , 0.    ],
+           [0.    , 0.0206, 0.    ],
+           [0.    , 0.    , 0.0028]])
     """
     m = len(x_train)  # Number of training samples
     weights = np.eye(m)  # Initialize weights as identity matrix
@@ -83,13 +83,13 @@ def local_weight(
     Returns:
         ndarray of local weights
     >>> local_weight(
-    ...     np.array([1., 1.]),
-    ...     np.array([[16.99, 10.34], [21.01,23.68], [24.59,25.69]]),
+    ...     np.array([16.99, 10.34]),
+    ...     np.array([[16.99, 10.34], [21.01, 23.68], [24.59, 25.69]]),
     ...     np.array([[1.01, 1.66, 3.5]]),
-    ...     0.6
-    ... )
-    array([[0.00873174],
-           [0.08272556]])
+    ...     5,
+    ... ).round(5)
+    array([[0.02572],
+           [0.05552]])
     """
     weight_mat = weight_matrix(point, x_train, tau)
     weight = np.linalg.inv(x_train.T @ weight_mat @ x_train) @ (
@@ -116,9 +116,9 @@ def local_weight_regression(
     >>> local_weight_regression(
     ...     np.array([[16.99, 10.34], [21.01, 23.68], [24.59, 25.69]]),
     ...     np.array([[1.01, 1.66, 3.5]]),
-    ...     0.6
-    ... )
-    array([1.07173261, 1.65970737, 3.50160179])
+    ...     5,
+    ... ).round(5)
+    array([1.01094, 1.98589, 3.42233])
     """
     y_pred = np.zeros(len(x_train))  # Initialize array of predictions
     for i, item in enumerate(x_train):

pyproject.toml

@@ -9,7 +9,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "beautifulsoup4>=4.12.3",
+  "beautifulsoup4>=4.15",
   "cython>=3.1.2",
   "fake-useragent>=1.5.1",
   "httpx>=0.28.1",
@@ -21,6 +21,7 @@ dependencies = [
   "opencv-python>=4.10.0.84",
   "pandas>=2.2.3",
   "pillow>=11.3",
+  "qiskit>=2",
   "rich>=13.9.4",
   "scikit-learn>=1.5.2",
   "scipy>=1.16.2",

quantum/q_fourier_transform.py

@@ -1,27 +1,34 @@
 """
-Build the quantum fourier transform (qft) for a desire
-number of quantum bits using Qiskit framework. This
-experiment run in IBM Q simulator with 10000 shots.
-This circuit can be use as a building block to design
-the Shor's algorithm in quantum computing. As well as,
-quantum phase estimation among others.
-.
+Build the quantum Fourier transform (QFT) for a desired
+number of qubits using the Qiskit framework.
+
+This circuit can be used as a building block to design
+Shor's algorithm in quantum computing, as well as
+quantum phase estimation, among others.
+
+The circuit is simulated with Qiskit's built-in, pure-Python
+``BasicSimulator`` (no compiled ``qiskit-aer`` backend required),
+so it runs anywhere Qiskit itself installs.
+
 References:
 https://en.wikipedia.org/wiki/Quantum_Fourier_transform
-https://qiskit.org/textbook/ch-algorithms/quantum-fourier-transform.html
+https://quantum.cloud.ibm.com/docs/en/api/qiskit/qiskit.circuit.library.QFT
 """
 
 import math
 
 import numpy as np
 import qiskit
-from qiskit import Aer, ClassicalRegister, QuantumCircuit, QuantumRegister, execute
+from qiskit import ClassicalRegister, QuantumCircuit, QuantumRegister, transpile
+from qiskit.providers.basic_provider import BasicSimulator
 
 
 def quantum_fourier_transform(number_of_qubits: int = 3) -> qiskit.result.counts.Counts:
     """
-    # >>> quantum_fourier_transform(2)
-    # {'00': 2500, '01': 2500, '11': 2500, '10': 2500}
+    Build and simulate the quantum Fourier transform applied to the all-zero
+    state ``|0...0>``.  The QFT maps ``|0...0>`` to a uniform superposition, so
+    every computational-basis outcome is (up to shot noise) equally likely.
+
     # quantum circuit for number_of_qubits = 3:
                                                ┌───┐
     qr_0: ──────■──────────────────────■───────┤ H ├─X─
@@ -31,13 +38,20 @@ def quantum_fourier_transform(number_of_qubits: int = 3) -> qiskit.result.counts
     qr_2: ┤ H ├─■────────■───────────────────────────X─
           └───┘
     cr: 3/═════════════════════════════════════════════
+
     Args:
-        n : number of qubits
+        number_of_qubits : number of qubits
+
     Returns:
-        qiskit.result.counts.Counts: distribute counts.
+        qiskit.result.counts.Counts: measurement counts over 10,000 shots.
 
-    >>> quantum_fourier_transform(2)
-    {'00': 2500, '01': 2500, '10': 2500, '11': 2500}
+    The simulation is seeded, so the set of observed outcomes is reproducible:
+
+    >>> counts = quantum_fourier_transform(2)
+    >>> sorted(counts)
+    ['00', '01', '10', '11']
+    >>> sum(counts.values())
+    10000
     >>> quantum_fourier_transform(-1)
     Traceback (most recent call last):
         ...
@@ -82,9 +96,12 @@ def quantum_fourier_transform(number_of_qubits: int = 3) -> qiskit.result.counts
 
     # measure all the qubits
     quantum_circuit.measure(qr, cr)
-    # simulate with 10000 shots
-    backend = Aer.get_backend("qasm_simulator")
-    job = execute(quantum_circuit, backend, shots=10000)
+
+    # simulate with 10000 shots on the pure-Python BasicSimulator; seed the run
+    # so the observed outcomes are reproducible for the doctest above.
+    backend = BasicSimulator()
+    transpiled_circuit = transpile(quantum_circuit, backend)
+    job = backend.run(transpiled_circuit, shots=10_000, seed_simulator=42)
 
     return job.result().get_counts(quantum_circuit)
 

sorts/pancake_sort.py

@@ -8,8 +8,13 @@
 python pancake_sort.py
 """
 
+from collections.abc import Sequence
+from typing import TypeVar
 
-def pancake_sort(arr):
+T = TypeVar("T")
+
+
+def pancake_sort[T](arr: Sequence[T]) -> list[T]:
     """Sort Array with Pancake Sort.
     :param arr: Collection containing comparable items
     :return: Collection ordered in ascending order of items