Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .devcontainer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,15 @@ This is **Devcontainer** configuration to provide a consistent development envir

## Usage

1. Install [**Docker** ](https://www.docker.com/get-started/) and [**Visual Studio Code**](https://code.visualstudio.com/)
1. Install [**Docker**](https://www.docker.com/get-started/) and [**Visual Studio Code**](https://code.visualstudio.com/)
2. Install the **Remote - Containers** extension in VS Code

- Do `CTRL+P`, paste this command and press `Enter`

```shell
ext install ms-vscode-remote.remote-containers
```

3. Open this repository in VS Code
4. When prompted, click **"Reopen in Container"**
5. Wait for the environment to build and initialize
Expand Down
2 changes: 2 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,5 @@ updates:
directory: "/"
schedule:
interval: "daily"
cooldown:
default-days: 7
9 changes: 4 additions & 5 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,16 @@
### Describe your change:


### Describe your change

* [ ] Add an algorithm?
* [ ] Fix a bug or typo in an existing algorithm?
* [ ] Add or change doctests? -- Note: Please avoid changing both code and tests in a single pull request.
* [ ] Documentation change?

### Checklist:
### Checklist

* [ ] I have read [CONTRIBUTING.md](https://github.com/TheAlgorithms/Python/blob/master/CONTRIBUTING.md).
* [ ] This pull request is all my own work -- I have not plagiarized.
* [ ] I know that pull requests will not be merged if they fail the automated tests.
* [ ] This PR only changes one algorithm file. To ease review, please open separate PRs for separate algorithms.
* [ ] This PR only changes one algorithm file. To ease review, please open separate PRs for separate algorithms.
* [ ] All new Python files are placed inside an existing directory.
* [ ] All filenames are in all lowercase characters with no spaces or dashes.
* [ ] All functions and variable names follow Python naming conventions.
Expand Down
2 changes: 1 addition & 1 deletion .github/skills/code-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ flagged. Also, paste the concrete command you ran.

Emit exactly these headings so reviews are comparable and easy to automate:

```
```text
### Is this an algorithm? — <yes/no + one-line why>
### Duplicate / prior-art check — <#NNNN | none found>
### Coding style — <pass | issues: …>
Expand Down
4 changes: 2 additions & 2 deletions .github/skills/new-pull-request/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ clear, kind, tested, type-hinted, mergeable contribution.
Make sure that the local `master` branch is synced with `upstream/master` before
creating a new pull request.

Create a new clearly named branch for the pull request. Pull request changes must
Create a new clearly named branch for the pull request. Pull request changes must
not be made or submitted on the `master` branch.

Never hand-edit or revert the `uv.lock` file. If you add a legitimate
Expand All @@ -19,7 +19,7 @@ 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. Any repo maintainer can undo this if you @mention them on the closed pull request.

### 1. Before contributing / Is this an algorithm?

Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: astral-sh/setup-uv@v7
with:
enable-cache: true
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/devcontainer_ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: devcontainers/ci@v0.3
with:
push: never
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/directory_writer.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ jobs:
- uses: actions/checkout@v7
with:
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-python@v7
with:
python-version-file: .python-version
Expand Down
6 changes: 5 additions & 1 deletion .github/workflows/hacktoberfest_prep.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: actions/setup-python@v7
with:
python-version-file: .python-version
Expand Down Expand Up @@ -96,4 +98,6 @@ jobs:
echo "Open tracker PR already exists; force-push updated it in place."
fi
- name: Propagate the script's exit code
run: exit ${{ steps.update.outputs.exit_code }}
env:
UPDATE_EXIT_CODE: ${{ steps.update.outputs.exit_code }}
run: exit ${UPDATE_EXIT_CODE}
4 changes: 4 additions & 0 deletions .github/workflows/project_euler.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: astral-sh/setup-uv@v7
- uses: actions/setup-python@v7
with:
Expand All @@ -26,6 +28,8 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: astral-sh/setup-uv@v7
- uses: actions/setup-python@v7
with:
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/ruff.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: astral-sh/setup-uv@v7
- run: uvx ruff check --output-format=github .
2 changes: 2 additions & 0 deletions .github/workflows/sphinx.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ jobs:
runs-on: ubuntu-24.04-arm
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: astral-sh/setup-uv@v7
- uses: actions/setup-python@v7
with:
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/ty.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ jobs:
continue-on-error: true
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: astral-sh/setup-uv@v7
with:
enable-cache: true
Expand Down
8 changes: 8 additions & 0 deletions .github/zizmor.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
rules:
excessive-permissions:
disable: true
unpinned-uses:
disable: true
# config:
# policies:
# actions/*: ref-pin
31 changes: 11 additions & 20 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -28,16 +28,23 @@ repos:
additional_dependencies:
- tomli

- repo: https://github.com/tox-dev/pyproject-fmt
rev: v2.29.4
hooks:
- id: pyproject-fmt

- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.16.6
hooks:
- id: ruff-check
- id: ruff-format

- repo: https://github.com/tox-dev/pyproject-fmt
rev: v2.29.3
- repo: https://github.com/rvben/rumdl-pre-commit
rev: v0.2.69
hooks:
- id: pyproject-fmt
- id: rumdl-fmt
- id: rumdl
args: [--fix]

- repo: local
hooks:
Expand All @@ -48,27 +55,11 @@ repos:
pass_filenames: false

- repo: https://github.com/astral-sh/uv-pre-commit
rev: 0.12.10
rev: 0.12.11
hooks:
- id: uv-lock

- repo: https://github.com/abravalheri/validate-pyproject
rev: "0.26"
hooks:
- id: validate-pyproject

# - repo: https://github.com/pre-commit/mirrors-mypy
# rev: v1.20.0
# hooks:
# - id: mypy
# args:
# - --explicit-package-bases
# - --ignore-missing-imports
# - --install-types
# - --non-interactive

- repo: https://github.com/pre-commit/mirrors-prettier
rev: v4.0.0-alpha.8
hooks:
- id: prettier
types_or: [toml, yaml]
53 changes: 32 additions & 21 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,9 @@ __Improving comments__ and __writing proper tests__ are also highly welcome.

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.
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

Expand All @@ -33,40 +35,47 @@ __Do not__ create an issue to contribute an algorithm. Please submit a pull requ

Please help us keep our issue list small by adding `Fixes #{$ISSUE_NUMBER}` to the description of pull requests that resolve open issues.
For example, if your pull request fixes issue #10, then please add the following to its description:
```

```text
Fixes #10
```

GitHub will use this tag to [auto-close the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if and when the PR is merged.

#### What is an Algorithm?

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()`).

- 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()`).

Algorithms should be packaged in a way that makes it easy for readers to put 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 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.
- 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 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

Use [pre-commit](https://pre-commit.com/#installation) to automatically format your code to match our coding style:

```bash
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:

```bash
Expand All @@ -78,14 +87,15 @@ pre-commit run --all-files --show-diff-on-failure
We want your work to be readable by others; therefore, we encourage you to note the following:

- Please write in free-threaded Python 3.14t+. For instance: `print()` is a function in Python 3, so `print "Hello"` will *not* work, but `print("Hello")` will.
- Please focus hard on the naming of functions, classes, and variables. Help your reader by using __descriptive names__ that can help you to remove redundant comments.

- Please focus hard on the naming of functions, classes, and variables. Help your reader by using __descriptive names__ that can help you to remove redundant comments.
- Single-letter variable names are *old school*, so please avoid them unless their life only spans a few lines.
- Expand acronyms because `gcd()` is hard to understand but `greatest_common_divisor()` is not.
- Please follow the [Python Naming Conventions](https://pep8.org/#prescriptive-naming-conventions) so variable_names and function_names should be lower_case, CONSTANTS in UPPERCASE, ClassNames should be CamelCase, etc.

- We encourage the use of Python [f-strings](https://realpython.com/python-f-strings/#f-strings-a-new-and-improved-way-to-format-strings-in-python) where they make the code easier to read.

- Please consider running [__ruff format__](https://docs.astral.sh/ruff/formatter/) on your Python file(s) before submitting your pull request. This is not yet a requirement, but it does make your code more readable and automatically aligns it with much of [PEP 8](https://peps.python.org/pep-0008/). To use it,
- Please consider running [__ruff format__](https://docs.astral.sh/ruff/formatter/) on your Python file(s) before submitting your pull request. This is not yet a requirement, but it does make your code more readable and automatically aligns it with much of [PEP 8](https://peps.python.org/pep-0008/). To use it,

```bash
python3 -m pip install ruff # only required the first time
Expand Down Expand Up @@ -123,7 +133,7 @@ We want your work to be readable by others; therefore, we encourage you to note
return a + b
```

- Write tests (especially [__doctests__](https://docs.python.org/3/library/doctest.html)) to illustrate and verify your work. We highly encourage the use of _doctests on all functions_.
- Write tests (especially [__doctests__](https://docs.python.org/3/library/doctest.html)) to illustrate and verify your work. We highly encourage the use of *doctests on all functions*.

```python
def sum_ab(a, b):
Expand Down Expand Up @@ -159,7 +169,7 @@ We want your work to be readable by others; therefore, we encourage you to note
starting_value = int(input("Please enter a starting value: ").strip())
```

The use of [Python type hints](https://docs.python.org/3/library/typing.html) is encouraged for function parameters and return values. Our CI runs [ty](https://docs.astral.sh/ty/) as an informational check that does not block merges yet, so you may want to run it locally before making your submission.
The use of [Python type hints](https://docs.python.org/3/library/typing.html) is encouraged for function parameters and return values. Our CI runs [ty](https://docs.astral.sh/ty/) as an informational check that does not block merges yet, so you may want to run it locally before making your submission.

```bash
python3 -m pip install ty # only required the first time
Expand All @@ -171,14 +181,16 @@ We want your work to be readable by others; therefore, we encourage you to note
return a + b
```

Instructions on how to install ty can be found [here](https://docs.astral.sh/ty/installation/). Please use the command `ty check` to test all files or `ty check path/to/file.py` to test a specific file.
[Install ty](https://docs.astral.sh/ty/installation/) and then pslease use the command `ty check` to test all files or `ty check path/to/file.py` to test a specific file.

- [__List comprehensions and generators__](https://docs.python.org/3/tutorial/datastructures.html#list-comprehensions) are preferred over the use of `lambda`, `map`, `filter`, `reduce` but the important thing is to demonstrate the power of Python in code that is easy to read and maintain.

- Avoid importing external libraries for basic algorithms. Only use those libraries for complicated algorithms.

- If you need a third-party module that is not already listed in __pyproject.toml__, please add it to the `dependencies` there as part of your submission. The `uv-lock` pre-commit hook will update `uv.lock` to match.

#### Other Requirements for Submissions

- If you are submitting code in the `project_euler/` directory, please also read [the dedicated Guideline](https://github.com/TheAlgorithms/Python/blob/master/project_euler/README.md) before contributing to our Project Euler library.
- The file extension for code files should be `.py`. Jupyter Notebooks should be submitted to [TheAlgorithms/Jupyter](https://github.com/TheAlgorithms/Jupyter).
- Strictly use snake_case (underscore_separated) in your file_name, as it will be easy to parse in the future using scripts.
Expand All @@ -189,7 +201,6 @@ We want your work to be readable by others; therefore, we encourage you to note
- Do not update the README.md or DIRECTORY.md file, which will be periodically autogenerated by our GitHub Actions processes.
- Add a corresponding explanation to [Algorithms-Explanation](https://github.com/TheAlgorithms/Algorithms-Explanation) (Optional but recommended).
- Our CI runs [__ty__](https://docs.astral.sh/ty/) on every pull request as an informational check that does not block merges yet, so we encourage you to add [__Python type hints__](https://docs.python.org/3/library/typing.html) where `ty` recommends to do so.

- Most importantly,
- __Be consistent in the use of these guidelines when submitting.__
- __Join__ us on [Discord](https://discord.com/invite/c7MnfGFGa6) and [Gitter](https://gitter.im/TheAlgorithms/community) __now!__
Expand Down
4 changes: 4 additions & 0 deletions DIRECTORY.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@
* [Count 1S Brian Kernighan Method](bit_manipulation/count_1s_brian_kernighan_method.py)
* [Count Number Of One Bits](bit_manipulation/count_number_of_one_bits.py)
* [Excess 3 Code](bit_manipulation/excess_3_code.py)
* [Fast Walsh Hadamard Transform](bit_manipulation/fast_walsh_hadamard_transform.py)
* [Find Previous Power Of Two](bit_manipulation/find_previous_power_of_two.py)
* [Find Unique Number](bit_manipulation/find_unique_number.py)
* [Gray Code Sequence](bit_manipulation/gray_code_sequence.py)
Expand Down Expand Up @@ -765,6 +766,7 @@
* [Juggler Sequence](maths/juggler_sequence.py)
* [Karatsuba](maths/karatsuba.py)
* [Kth Lexicographic Permutation](maths/kth_lexicographic_permutation.py)
* [Laplace Transformation](maths/laplace_transformation.py)
* [Largest Of Very Large Numbers](maths/largest_of_very_large_numbers.py)
* [Least Common Multiple](maths/least_common_multiple.py)
* [Line Intersection](maths/line_intersection.py)
Expand All @@ -787,6 +789,7 @@
* [Adams Bashforth](maths/numerical_analysis/adams_bashforth.py)
* [Bisection](maths/numerical_analysis/bisection.py)
* [Bisection 2](maths/numerical_analysis/bisection_2.py)
* [Brent Method](maths/numerical_analysis/brent_method.py)
* [Integration By Simpson Approx](maths/numerical_analysis/integration_by_simpson_approx.py)
* [Intersection](maths/numerical_analysis/intersection.py)
* [Nevilles Method](maths/numerical_analysis/nevilles_method.py)
Expand Down Expand Up @@ -838,6 +841,7 @@
* [Hexagonal Numbers](maths/series/hexagonal_numbers.py)
* [Logarithmic Series](maths/series/logarithmic_series.py)
* [P Series](maths/series/p_series.py)
* [Sieve Of Atkin](maths/sieve_of_atkin.py)
* [Sieve Of Eratosthenes](maths/sieve_of_eratosthenes.py)
* [Sigmoid](maths/sigmoid.py)
* [Signum](maths/signum.py)
Expand Down
Loading
Loading