Initial commit

.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - '*.*.*'
+
+jobs:
+
+  tests:
+    uses: ./.github/workflows/tests.yml
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: [tests]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Poetry
+        run: curl -sSL https://install.python-poetry.org | python - -y
+
+      - name: Update PATH
+        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Check package version and tag are equal
+        run: |
+          if [[ ${{ github.ref_name }} != "$(poetry version --short)" ]]; then
+            echo "Tag = ${{ github.ref_name }} != $(poetry version --short)"
+            exit 1
+          fi
+
+      - name: Build package
+        run: poetry build
+
+      - name: Check if pre-release version
+        id: check_version
+        run: |
+          [[ "$(poetry version --short)" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || echo pre_release=true >> $GITHUB_OUTPUT
+
+      - name: Create GitHub release
+        uses: ncipollo/release-action@v1
+        with:
+          artifacts: "dist/*"
+          token: ${{ secrets.GITHUB_TOKEN }}
+          allowUpdates: true
+          replacesArtifacts: true
+          updateOnlyUnreleased: true
+          generateReleaseNotes: true
+          prerelease: ${{ steps.check_version.outputs.pre_release == 'true' }}
+
+      - name: Publish to PyPI
+        env:
+          POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
+        run: poetry publish

.github/workflows/tests.yml

@@ -0,0 +1,46 @@
+name: Tests
+
+run-name: ${{ github.event.head_commit.message }}
+
+on:
+  workflow_call:
+
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+
+  tests:
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Poetry
+        run: curl -sSL https://install.python-poetry.org | python - -y
+
+      - name: Update PATH
+        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: make dev
+
+      - name: Run checks
+        run: make check_format
+
+      - name: Run tests
+        run: make test

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+__pypackages__/
+build/
+dist/
+.mypy_cache/
+.pytest_cache
+.coverage
+.env
+env/
+venv/
+.idea/
+poetry.lock
+.python-version
+CHANGELOG.md

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2015 Nelson Brochado (aka nbro)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,58 @@
+POETRY := $(shell command -v poetry 2> /dev/null)
+
+.PHONY: help
+help: ## Show this help
+	@egrep -h '\s##\s' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m  %-30s\033[0m %s\n", $$1, $$2}'
+
+.DEFAULT_GOAL := help
+
+.PHONY: poetry_installed
+poetry_installed:
+ifndef POETRY
+	@echo "Poetry does not seem to be installed, but it's required."
+	@echo "You can install it by typing: make install_poetry"
+	@echo "For more details about how you can install poetry, see https://python-poetry.org/"
+	@exit 1
+endif
+
+.PHONY: install_poetry
+install_poetry:  ## Install poetry
+ifndef POETRY
+	curl -sSL https://install.python-poetry.org | python3 -
+endif
+
+.PHONY: dev
+dev: poetry_installed  ## Setup the development environment
+	poetry --version
+	poetry run python --version
+	poetry check || poetry update
+	poetry install --all-extras
+	poetry env info
+	poetry show
+
+.PHONY: test
+test: poetry_installed  ## Run the tests
+	poetry run coverage run -m pytest
+#	poetry run coverage run --source=. -m unittest discover -s tests -v
+	poetry run coverage report
+
+.PHONY: format
+format: poetry_installed  ## Format the code
+	poetry run isort andz tests
+	poetry run black andz tests
+
+.PHONY: check_format
+check_format: poetry_installed  ## Check if the code is formatted
+	poetry run isort --check --diff andz tests
+	poetry run black --check --diff andz tests
+
+.PHONY: check_types
+check_types: poetry_installed  ## Run type-checks
+	poetry run mypy andz
+
+.PHONY: check_style
+check_style: poetry_installed  ## Run style checks
+	poetry run pylint andz tests
+
+.PHONY: check
+check: check_format check_types check_style  ## Run all quality assurance checks

README.md

@@ -0,0 +1,52 @@
+# Algorithms and Data Structures (andz)
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![](https://img.shields.io/badge/stability-experimental-red.svg)](http://www.engr.sjsu.edu/fayad/SoftwareStability/)
+[![Packagist](https://img.shields.io/packagist/l/doctrine/orm.svg?maxAge=2592000)](./LICENSE.md)
+[![Tests](https://github.com/nbro/andz/actions/workflows/tests.yml/badge.svg)](https://github.com/nbro/andz/actions/workflows/tests.yml)
+
+## Introduction
+
+`andz` stands for **a**lgorithms a**n**d **d**ata structure**z**. 
+
+> The `s` was replaced with `z` because  
+> there was already a dummy package called `ands` on PyPI.
+
+In this package, you can find some of the most common algorithms and 
+data structures studied in Computer Science, 
+such as quick-sort or binary-search trees. 
+The algorithms are divided into main categories, 
+such as sorting algorithms or dynamic programming algorithms, but note that
+some algorithms and DS can fall into multiple categories .
+
+> The current main goal of this project is for me to learn more about 
+new algorithms and data structures, but I hope these implementations 
+can also be useful to anyone interested in them.
+
+## Development
+
+I use
+
+- [poetry](https://python-poetry.org/) for development
+- the [`Makefile`](./Makefile) to declare common commands
+- [`pyenv`](https://github.com/pyenv/pyenv) to manage different Python versions locally
+- GitHub Actions for CI/CD
+
+For more info about how to develop, 
+see [`./docs/how_to_develop.md`](docs/how_to_develop.md).
+
+## How to install?
+
+```
+pip install andz
+```
+
+## Documentation
+
+Most modules and functions have been thoroughly documented, 
+so the best way to learn about the algorithms and data structures is 
+to read the source code and the related docstrings and comments.
+
+You can find more documentation under [`docs`](./docs). 
+There you will find the history of the project, 
+development conventions that should be adapted, etc.

andz/__init__.py

@@ -0,0 +1,4 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# File to allow this directory to be treated as a Python package.