diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..634594e --- /dev/null +++ b/.editorconfig @@ -0,0 +1,11 @@ +# http://editorconfig.org + +root = true + +[*] +indent_style = space +indent_size = 4 +trim_trailing_whitespace = true +insert_final_newline = true +charset = utf-8 +end_of_line = lf diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..2410a54 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,21 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly + - package-ecosystem: pip + directory: "/.github/workflows" + schedule: + interval: weekly + - package-ecosystem: pip + directory: "/docs" + schedule: + interval: weekly + - package-ecosystem: pip + directory: "/" + schedule: + interval: weekly + versioning-strategy: lockfile-only + allow: + - dependency-type: "all" \ No newline at end of file diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 0000000..82bb9b9 --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,66 @@ +--- +# Labels names are important as they are used by Release Drafter to decide +# regarding where to record them in changelog or if to skip them. +# +# The repository labels will be automatically configured using this file and +# the GitHub Action https://github.com/marketplace/actions/github-labeler. +- name: breaking + description: Breaking Changes + color: bfd4f2 +- name: bug + description: Something isn't working + color: d73a4a +- name: build + description: Build System and Dependencies + color: bfdadc +- name: ci + description: Continuous Integration + color: 4a97d6 +- name: dependencies + description: Pull requests that update a dependency file + color: 0366d6 +- name: documentation + description: Improvements or additions to documentation + color: 0075ca +- name: duplicate + description: This issue or pull request already exists + color: cfd3d7 +- name: enhancement + description: New feature or request + color: a2eeef +- name: github_actions + description: Pull requests that update Github_actions code + color: "000000" +- name: good first issue + description: Good for newcomers + color: 7057ff +- name: help wanted + description: Extra attention is needed + color: 008672 +- name: invalid + description: This doesn't seem right + color: e4e669 +- name: performance + description: Performance + color: "016175" +- name: python + description: Pull requests that update Python code + color: 2b67c6 +- name: question + description: Further information is requested + color: d876e3 +- name: refactoring + description: Refactoring + color: ef67c4 +- name: removal + description: Removals and Deprecations + color: 9ae7ea +- name: style + description: Style + color: c120e5 +- name: testing + description: Testing + color: b1fc6f +- name: wontfix + description: This will not be worked on + color: ffffff \ No newline at end of file diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml new file mode 100644 index 0000000..a27413f --- /dev/null +++ b/.github/release-drafter.yml @@ -0,0 +1,39 @@ +name-template: '$RESOLVED_VERSION' +tag-template: 'v$RESOLVED_VERSION' + +categories: + - title: '🚀 Features' + labels: + - 'feat' + - title: '🐛 Bug Fixes' + labels: + - 'fix' + - title: 'Other updates' + labels: + - 'refactor' + - 'chore' + - 'docs' + - 'perf' + - 'test' + +change-template: '- $TITLE @$AUTHOR (#$NUMBER)' +change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks. + +version-resolver: + major: + labels: + - 'major' + minor: + labels: + - 'minor' + patch: + labels: + - 'patch' + default: patch + +template: | + ## Changes + + $CHANGES + + Special thanks to: $CONTRIBUTORS \ No newline at end of file diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..eb72df4 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,75 @@ +name: Build + +on: [push, pull_request] + +jobs: + test: + + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: ["ubuntu-latest"] + python_version: ['3.9'] + + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python_version }} + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install hatch + hatch env create + - name: Lint and typecheck + run: | + hatch run lint:lint-check + - name: Run Tests + run: | + hatch run test:pytest + - uses: codecov/codecov-action@v4 + with: + token: ${{ secrets.CODECOV_TOKEN }} + fail_ci_if_error: true + verbose: true + + release: + runs-on: ubuntu-latest + environment: release + needs: test + if: startsWith(github.ref, 'refs/tags/') + permissions: + contents: write + id-token: write + + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.9' + - name: Install dependencies + shell: bash + run: | + python -m pip install --upgrade pip + pip install hatch + - name: Build + run: | + hatch build + - name: Publish 📦 to Test PyPI + if: startsWith(github.ref, 'refs/heads/main') + uses: pypa/gh-action-pypi-publish@release/v1 + with: + skip_existing: true + user: __token__ + password: ${{ secrets.TEST_PYPI_SECRECT }} + packages-dir: dist/ + repository-url: https://test.pypi.org/legacy/ + - name: Publish 📦 to PyPI + if: startsWith(github.ref, 'refs/heads/main') + uses: pypa/gh-action-pypi-publish@release/v1 + with: + user: __token__ + password: ${{ secrets.PYPI_SECRECT }} + packages-dir: dist/ diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..dc9aab6 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,56 @@ +name: Build documentation + +on: + push: + branches: + - main + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +# Default to bash +defaults: + run: + shell: bash + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.9' + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install hatch + hatch env create docs + - name: Build + run: hatch run docs:build-check + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./site + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/draft.yml b/.github/workflows/draft.yml new file mode 100644 index 0000000..f8aff60 --- /dev/null +++ b/.github/workflows/draft.yml @@ -0,0 +1,19 @@ +name: Release Drafter + +on: + push: + branches: + - main + +jobs: + update-draft: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + # Drafts your next Release notes as Pull Requests are merged into "main" + - uses: release-drafter/release-drafter@v6 + with: + disable-autolabeler: true + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml new file mode 100644 index 0000000..e30242c --- /dev/null +++ b/.github/workflows/labeler.yml @@ -0,0 +1,25 @@ +name: Labeler + +on: + push: + branches: + - main + - master + +permissions: + actions: read + contents: read + security-events: write + pull-requests: write + +jobs: + labeler: + runs-on: ubuntu-latest + steps: + - name: Check out the repository + uses: actions/checkout@v4 + + - name: Run Labeler + uses: crazy-max/ghaction-github-labeler@v5.0.0 + with: + skip-delete: true \ No newline at end of file diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..2330995 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,41 @@ +name: Tests + +on: + push: + branches: ["main"] + pull_request: + branches: ["main"] + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + cancel-in-progress: true + +defaults: + run: + shell: bash + +jobs: + tests: + runs-on: ${{ matrix.os }} + + strategy: + matrix: + os: [ubuntu-latest, macos-latest] + python-version: ["3.9", "3.10", "3.11"] + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python_version }} + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install hatch + hatch env create + - name: Lint and typecheck + run: | + hatch run lint:lint-check + - name: Run Tests + run: | + hatch run test:pytest \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1b80eab --- /dev/null +++ b/.gitignore @@ -0,0 +1,115 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +env/ +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +.hypothesis/ +.pytest_cache/ +junit/ +junit.xml +test.db + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# pyenv +.python-version + +# celery beat schedule file +celerybeat-schedule + +# SageMath parsed files +*.sage.py + +# dotenv +.env + +# virtualenv +.venv +venv/ +ENV/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ + +# OS files +.DS_Store +.vscode/ + +# pdm +.pdm-python + +# ruff +.ruff_cache/* \ No newline at end of file diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..2047f8b --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,34 @@ +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + - id: check-added-large-files + - id: check-merge-conflict + - id: check-shebang-scripts-are-executable + - id: check-docstring-first + - id: debug-statements + - id: check-ast + - id: check-json + - id: check-toml + - id: check-xml + - id: check-yaml + args: ['--unsafe'] # needed for !! tags in mkdocs.yml + - id: end-of-file-fixer + - id: mixed-line-ending + args: ['--fix=auto'] # replace 'auto' with 'lf' to enforce Linux/Mac line endings or 'crlf' for Windows + +# Ruff replaces black, flake8, autoflake, isort and more +- repo: https://github.com/charliermarsh/ruff-pre-commit + rev: 'v0.3.4' # make sure this is always consistent with hatch configs + hooks: + - id: ruff + - id: ruff-format + args: [--check, --config, ./pyproject.toml] + +- repo: https://github.com/pre-commit/mirrors-mypy + rev: 'v1.9.0' # make sure this is always consistent with hatch configs + hooks: + - id: mypy + args: ["--install-types", "--non-interactive"] + additional_dependencies: [types-tabulate, types-cachetools] \ No newline at end of file diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..93ecc10 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,3 @@ +# Contributors + +* [Saikat Karmakar](https://github.com/aviksaikat) \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..24df65e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,6 @@ +# Changelog + +## Version 0.0.1 (development) + +- First pre-alpha +- ... \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9dc744f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,170 @@ +# Contributing + +Welcome to the contributor guide of mantaray py. + +This document focuses on getting any potential contributor familiarized with +the development processes, but [other kinds of contributions] are also appreciated. + +If you are new to using [git] or have never collaborated in a project previously, +please have a look at [contribution-guide.org]. Other resources are also +listed in the excellent [guide created by FreeCodeCamp] [^contrib1]. + +Please notice, all users and contributors are expected to be **open, +considerate, reasonable, and respectful**. When in doubt, +[Python Software Foundation's Code of Conduct] is a good reference in terms of +behavior guidelines. + +## Issue Reports + +If you experience bugs or general issues with mantaray py, please have a look +on the [issue tracker]. +If you don't see anything useful there, please feel free to fire an issue report. + +!!! tip + Please don't forget to include the closed issues in your search. + Sometimes a solution was already reported, and the problem is considered + **solved**. + +New issue reports should include information about your programming environment +(e.g., operating system, Python version) and steps to reproduce the problem. +Please try also to simplify the reproduction steps to a very minimal example +that still illustrates the problem you are facing. By removing other factors, +you help us to identify the root cause of the issue. + +## Documentation improvements + +You can help improve the documentation of mantaray py by making them more readable +and coherent, or by adding missing information and correcting mistakes. + +This documentation uses [mkdocs] as its main documentation compiler. +This means that the docs are kept in the same repository as the project code, and +that any documentation update is done in the same way was a code contribution. + +!!! tip + Please notice that the [GitHub web interface] provides a quick way for + proposing changes. While this mechanism can be tricky for normal code contributions, + it works perfectly fine for contributing to the docs, and can be quite handy. + + If you are interested in trying this method out, please navigate to + the `docs` folder in the source [repository], find which file you + would like to propose changes and click in the little pencil icon at the + top, to open [GitHub's code editor]. Once you finish editing the file, + please write a message in the form at the bottom of the page describing + which changes have you made and what are the motivations behind them and + submit your proposal. + +When working on documentation changes in your local machine, you can +build and serve them using [hatch] with `hatch run docs:build` and +`hatch run docs:serve`, respectively. + +## Code Contributions + +### Submit an issue + +Before you work on any non-trivial code contribution it's best to first create +a report in the [issue tracker] to start a discussion on the subject. +This often provides additional considerations and avoids unnecessary work. + +### Clone the repository + +1. Create a user account on GitHub if you do not already have one. + +2. Fork the project [repository]: click on the *Fork* button near the top of the + page. This creates a copy of the code under your account on GitHub. + +3. Clone this copy to your local disk: + + ```console + git clone git@github.com:YourLogin/mantaray-py.git + cd mantaray-py + ``` + +4. Make sure [hatch] is installed using [pipx]: + + ```console + pipx install hatch + ``` + +5. \[only once\] install [pre-commit] hooks in the default environment with: + + ```console + hatch run pre-commit install + ``` + +### Implement your changes + +1. Create a branch to hold your changes: + + ```console + git checkout -b my-feature + ``` + + and start making changes. Never work on the main branch! + +2. Start your work on this branch. Don't forget to add [docstrings] in [Google style] + to new functions, modules and classes, especially if they are part of public APIs. + +3. Add yourself to the list of contributors in `AUTHORS.md`. + +4. When you’re done editing, do: + + ```console + git add + git commit + ``` + + to record your changes in [git]. + + Please make sure to see the validation messages from [pre-commit] and fix + any eventual issues. + This should automatically use [flake8]/[black] to check/fix the code style + in a way that is compatible with the project. + + !!! info + Don't forget to add unit tests and documentation in case your + contribution adds a feature and is not just a bugfix. + + Moreover, writing an [descriptive commit message] is highly recommended. + In case of doubt, you can check the commit history with: + ``` + git log --graph --decorate --pretty=oneline --abbrev-commit --all + ``` + to look for recurring communication patterns. + +5. Please check that your changes don't break any unit tests with + `hatch run test:cov` or `hatch run test:no-cov` to run the unitest with + or without coverage reports, respectively. + +### Submit your contribution + +1. If everything works fine, push your local branch to the remote server with: + + ```console + git push -u origin my-feature + ``` + +2. Go to the web page of your fork and click "Create pull request" + to send your changes for review. + + Find more detailed information in [creating a PR]. You might also want to open + the PR as a draft first and mark it as ready for review after the feedbacks + from the continuous integration (CI) system or any required fixes. + +[^contrib1]: Even though, these resources focus on open source projects and + communities, the general ideas behind collaborating with other developers + to collectively create software are general and can be applied to all sorts + of environments, including private companies and proprietary code bases. + +[black]: https://pypi.org/project/black/ +[contribution-guide.org]: http://www.contribution-guide.org/ +[creating a PR]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request +[docstrings]: https://peps.python.org/pep-0257/ +[flake8]: https://flake8.pycqa.org/en/stable/ +[git]: https://git-scm.com +[github web interface]: https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository +[other kinds of contributions]: https://opensource.guide/how-to-contribute +[pre-commit]: https://pre-commit.com/ +[pipx]: https://pypa.github.io/pipx/ +[python software foundation's code of conduct]: https://www.python.org/psf/conduct/ +[Google style]: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings +[guide created by FreeCodeCamp]: https://github.com/FreeCodeCamp/how-to-contribute-to-open-source \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..cf7f8d5 --- /dev/null +++ b/LICENSE @@ -0,0 +1,32 @@ + + +BSD License + +Copyright (c) 2024, Saikat Karmakar +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or + other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from this + software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, +INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY +OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +OF THE POSSIBILITY OF SUCH DAMAGE. + diff --git a/README.md b/README.md new file mode 100644 index 0000000..25e1def --- /dev/null +++ b/README.md @@ -0,0 +1,73 @@ +# mantaray py + +

+ Mantaray data structure in Python +

+ +[![build](https://github.com/aviksaikat/mantaray-py/workflows/Build/badge.svg)](https://github.com/aviksaikat/mantaray-py/actions) +[![codecov](https://codecov.io/gh/aviksaikat/mantaray-py/branch/master/graph/badge.svg)](https://codecov.io/gh/aviksaikat/mantaray-py) +[![PyPI version](https://badge.fury.io/py/mantaray-py.svg)](https://badge.fury.io/py/mantaray-py) + +--- + +**Documentation**: https://aviksaikat.github.io/mantaray-py/ + +**Source Code**: https://github.com/aviksaikat/mantaray-py + +--- + +## Development + +### Setup environment + +We use [Hatch](https://hatch.pypa.io/latest/install/) to manage the development environment and production build. Ensure it's installed on your system. + +### Run unit tests + +You can run all the tests with: + +```bash +hatch run test +``` + +### Format the code + +Execute the following command to apply linting and check typing: + +```bash +hatch run lint +``` + +### Publish a new version + +You can bump the version, create a commit and associated tag with one command: + +```bash +hatch version patch +``` + +```bash +hatch version minor +``` + +```bash +hatch version major +``` + +Your default Git text editor will open so you can add information about the release. + +When you push the tag on GitHub, the workflow will automatically publish it on PyPi and a GitHub release will be created as draft. + +## Serve the documentation + +You can serve the Mkdocs documentation with: + +```bash +hatch run docs-serve +``` + +It'll automatically watch for changes in your code. + +## License + +This project is licensed under the terms of the BSD license. diff --git a/codecov.yaml b/codecov.yaml new file mode 100644 index 0000000..058cfb7 --- /dev/null +++ b/codecov.yaml @@ -0,0 +1,9 @@ +coverage: + range: 70..100 + round: down + precision: 1 + status: + project: + default: + target: 90% + threshold: 0.5% diff --git a/docs/authors.md b/docs/authors.md new file mode 100644 index 0000000..14b2eb0 --- /dev/null +++ b/docs/authors.md @@ -0,0 +1,4 @@ + +{% + include-markdown "../AUTHORS.md" +%} diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..e3fe5cf --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,4 @@ + +{% + include-markdown "../CHANGELOG.md" +%} diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..a32dd64 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,4 @@ + +{% + include-markdown "../CONTRIBUTING.md" +%} diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..612c7a5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +--8<-- "README.md" diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 0000000..08ee9f1 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,4 @@ + +{% + include-markdown "../LICENSE" +%} diff --git a/docs/reference/mantaray_py.md b/docs/reference/mantaray_py.md new file mode 100644 index 0000000..df1700d --- /dev/null +++ b/docs/reference/mantaray_py.md @@ -0,0 +1,6 @@ +# Reference + +::: mantaray_py + options: + show_root_heading: false + show_source: false diff --git a/docs/scripts/gen_ref_nav.py b/docs/scripts/gen_ref_nav.py new file mode 100644 index 0000000..47174e8 --- /dev/null +++ b/docs/scripts/gen_ref_nav.py @@ -0,0 +1,39 @@ +"""Generate the code reference pages and navigation. + +Copyright (c) 2019, Timothée Mazzucotelli, ISC License + +Taken from https://github.com/mkdocstrings/mkdocstrings/blob/master/docs/gen_ref_nav.py +""" + +from pathlib import Path + +import mkdocs_gen_files + +nav = mkdocs_gen_files.Nav() + +for path in sorted(Path('src').rglob('*.py')): + module_path = path.relative_to('src').with_suffix('') + doc_path = path.relative_to('src').with_suffix('.md') + full_doc_path = Path('reference', doc_path) + + parts = tuple(module_path.parts) + + if parts[-1] == '__init__': + parts = parts[:-1] + doc_path = doc_path.with_name('index.md') + full_doc_path = full_doc_path.with_name('index.md') + elif parts[-1] == '__main__': + continue + elif parts[-1] == '_version': + continue + + nav[parts] = doc_path.as_posix() + + with mkdocs_gen_files.open(full_doc_path, 'w') as fd: + ident = '.'.join(parts) + fd.write(f'::: {ident}') + + mkdocs_gen_files.set_edit_path(full_doc_path, path) + +with mkdocs_gen_files.open('reference/SUMMARY.md', 'w') as nav_file: + nav_file.writelines(nav.build_literate_nav()) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..cb7f240 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,81 @@ +# Project information +site_name: mantaray py +site_description: Mantaray data structure in Python +site_author: Saikat Karmakar +site_url: https://github.com/aviksaikat/mantaray-py +copyright: 'Copyright © Saikat Karmakar 2024-present' + +# Repository +repo_url: https://github.com/aviksaikat/mantaray-py +repo_name: aviksaikat/mantaray-py + +theme: + name: material + font: + text: Roboto + code: Roboto Mono + icon: + logo: material/library + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: red + accent: red + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: red + accent: red + toggle: + icon: material/brightness-4 + name: Switch to light mode + +markdown_extensions: + - toc: + permalink: true + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + +plugins: + - search + - mkdocstrings: + handlers: + python: + import: + - https://docs.python.org/3.9/objects.inv + options: + docstring_style: google + - gen-files: + scripts: + - docs/scripts/gen_ref_nav.py + +watch: + - docs + - mantaray_py + +# Navigation +nav: + - Home: + - About: index.md + - Changelog: changelog.md + - License: license.md + - Authors: authors.md + - Contributing: contributing.md + - Reference: + - mantaray_py: reference/mantaray_py.md diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..010c824 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,258 @@ +[project] +name = "mantaray-py" +authors = [ + { name = "mantaray-py", email = "king.arthur@camelot.bt" } +] +description = "Mantaray data structure in Python" +readme = "README.md" +dynamic = ["version"] +license = { file = "LICENSE" } +classifiers = [ + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: Implementation :: CPython", + "Programming Language :: Python :: Implementation :: PyPy", +] +requires-python = ">=3.9" +dependencies = [ +] + +[project.urls] +Documentation = "https://aviksaikat.github.io/mantaray-py/" +Source = "https://github.com/aviksaikat/mantaray-py" + +[tool.hatch] + +[tool.hatch.metadata] +allow-direct-references = true + + +############## +# Versioning # +############## + +[tool.hatch.version] +source = "vcs" +raw-options = { version_scheme = "no-guess-dev" } + + +[tool.hatch.build.hooks.vcs] +version-file = "src/mantaray_py/_version.py" + + +################## +# External Tools # +################## + +[tool.mypy] +files = ["mantaray_py"] +exclude = ["build/", "dist/", "docs/", "tests/*"] +disallow_untyped_defs = true +disallow_any_unimported = true +no_implicit_optional = true +check_untyped_defs = true +warn_return_any = true +warn_unused_ignores = true +show_error_codes = true +plugins = ["pydantic.mypy"] + + +[tool.ruff] +target-version = "py39" +line-length = 120 +indent-width = 4 +include = [ + "src/**/*.py", + "src/**/*.pyi", + "tests/**/*.py", + "tests/**/*.pyi" +] + +[tool.ruff.lint] +preview = true # preview features & checks, use with caution +extend-select = [ # features in preview + "W292", # missing-newline-at-end-of-file +] +select = [ + "A", + "ARG", + "B", + "C", + "DTZ", + "E", + "EM", + "F", + "FBT", # Boolean trap + "ICN", + "ISC", + "I", + "N", + "PLC", + "PLE", + "PLR", + "PLW", + "Q", + "RUF", + "S", + "T", + "TID", + "UP", + "W", + "YTT", + "RUF100", # Automatically remove unused # noqa directives +] +ignore = [ + # Allow non-abstract empty methods in abstract base classes + "B027", + # Allow boolean positional values in function calls, like `dict.get(... True)` + "FBT003", + # Ignore checks for possible passwords + "S105", "S106", "S107", + # Ignore complexity + "C901", "PLR0911", "PLR0912", "PLR0913", "PLR0915", + "PLC1901", # empty string comparisons + "PLW2901", # `for` loop variable overwritten + "SIM114", # Combine `if` branches using logical `or` operator + "E203", # Whitespace before :, needed for black compatability and also `ruff format` + "ISC001", # causes unexpected behaviour with formatter +] + + +[tool.ruff.format] +# be more like black +quote-style = "single" + + +[tool.ruff.lint.isort] +known-first-party = ["mantaray_py"] + + +[tool.ruff.lint.flake8-quotes] +inline-quotes = "single" + + +[tool.ruff.lint.flake8-tidy-imports] +ban-relative-imports = "all" + + +[tool.ruff.lint.per-file-ignores] +# Allow print/pprint +"examples/*" = ["T201"] +# Tests can use magic values, assertions, and relative imports +"tests/**/*" = ["PLR2004", "S101", "TID252"] + + +[tool.pytest.ini_options] +addopts = "--cov=src/mantaray_py/ --cov-report=term-missing" + + +[tool.coverage.run] +branch = true +source = ["src/mantaray_py"] +omit = [ + # automatically created by hatch-vcs, not in repo + "_version.py", +] + +[tool.coverage.paths] +source = [ + "src/", + "*/site-packages/", +] + + +##################### +# Environment Setup # +##################### + + +# Default env dendencies +[tool.hatch.envs.default] +dependencies = [ + "pydantic", +] +post-install-commands = ["pre-commit install"] + + +# Lint env dendencies +[tool.hatch.envs.lint] +dependencies = [ + "mypy", + "ruff", +"deptry", +] + + +[tool.hatch.envs.lint.scripts] +typing = [ + "echo \"VERSION: `mypy --version`\"", + "mypy --install-types --non-interactive {args}" +] +lint = [ + "echo \"VERSION: `ruff --version`\"", + "ruff format .", + "ruff check . --fix", + "mypy src/mantaray_py/", +] +lint-check = [ + "echo \"VERSION: `ruff --version`\"", + "ruff format --check .", + "ruff check .", + "mypy src/mantaray_py/", +] + +# Docs env dendencies +[tool.hatch.envs.docs] +dependencies = [ +"mkdocs", + "mkdocs-material", + "mkdocs-gen-files", + "mkdocstrings[python]", + "linkchecker", +] + + +[tool.hatch.envs.docs.scripts] +docs-serve = "mkdocs serve" +docs-build = "mkdocs build --clean --strict" +# --ignore-url=None since the SUMMARY.md file leaves a None in sitemap.xml +validate = "linkchecker --config .linkcheckerrc --ignore-url=/reference --ignore-url=None site" +# https://github.com/linkchecker/linkchecker/issues/678 +build-check = [ + "docs-build", + "validate", +] + +# Testing env dendencies +[tool.hatch.envs.test] +dependencies = [ + "pytest", +"pytest-cov", + +] + + +[tool.hatch.envs.test.scripts] +test = "pytest" +test-cov-xml = "pytest --cov-report=xml" + + +# Replace tox & nox +[[tool.hatch.envs.test.matrix]] +python = ["3.9"] + +######### +# Build # +######### + +[build-system] +requires = ["hatchling", "hatch-vcs"] +build-backend = "hatchling.build" + +[tool.hatch.build.targets.sdist] +exclude = [ + "/.github", +] + +[tool.hatch.build.targets.wheel] +packages = ["src/mantaray_py/"] \ No newline at end of file diff --git a/src/mantaray_py/__init__.py b/src/mantaray_py/__init__.py new file mode 100644 index 0000000..1e3109e --- /dev/null +++ b/src/mantaray_py/__init__.py @@ -0,0 +1,10 @@ +"""Mantaray data structure in Python""" + +from importlib.metadata import PackageNotFoundError, version + +try: + __version__ = version("mantaray-py") +except PackageNotFoundError: # pragma: no cover + __version__ = "unknown" +finally: + del version, PackageNotFoundError diff --git a/src/mantaray_py/py.typed b/src/mantaray_py/py.typed new file mode 100644 index 0000000..e69de29 diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/test_add.py b/tests/test_add.py new file mode 100644 index 0000000..f293f79 --- /dev/null +++ b/tests/test_add.py @@ -0,0 +1,14 @@ +import pytest +from mantaray_py import add + + +@pytest.mark.parametrize( + "a,b,result", + [ + (0, 0, 0), + (1, 1, 2), + (3, 2, 5), + ], +) +def test_add(a: int, b: int, result: int): + assert add(a, b) == result