diff --git a/.autorc b/.autorc new file mode 100644 index 0000000..89cd40f --- /dev/null +++ b/.autorc @@ -0,0 +1,7 @@ +{ + "onlyPublishWithReleaseLabel": true, + "baseBranch": "main", + "author": "bot ", + "noVersionPrefix": true, + "plugins": ["git-tag"] +} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ad616ab --- /dev/null +++ b/.gitignore @@ -0,0 +1,166 @@ +# Ruff +.ruff_cache + +# Mac +.DS_Store + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# 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/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +# poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/#use-with-ide +.pdm.toml + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +.idea/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..9678e80 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,56 @@ +fail_fast: false + +repos: +- repo: https://github.com/python-poetry/poetry + rev: 1.8.0 + hooks: + - id: poetry-check + +- repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.3.3 + hooks: + - id: ruff + - id: ruff-format + +- repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.9.0 + hooks: + - id: mypy + args: [--ignore-missing-imports] +- repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks + rev: v2.12.0 + hooks: + - id: pretty-format-yaml + args: + - --autofix + - --indent=2 + - id: pretty-format-toml + exclude: ^poetry.lock$ + args: + - --autofix + - --indent=2 + - --no-sort + +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: check-case-conflict + - id: end-of-file-fixer + - id: trailing-whitespace + - id: pretty-format-json + args: + - --autofix + - --indent=4 + - --no-sort-keys + - id: check-merge-conflict + - id: check-yaml + - id: check-json + - id: check-toml + +- repo: local + hooks: + - id: yaml-file-extension + name: Prefer .yaml over .yml. + entry: YAML files must have .yaml extension. + language: fail + files: \.yml$ diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..dd8d95f --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,101 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or + advances of any kind - Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email + address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +fabiocat@mit.edu. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3cf01f7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,12 @@ +# pipepal pull request guidelines + +Pull requests are always welcome, and we appreciate any help you give. Note that a code of conduct applies to all spaces managed by the pipepal project, including issues and pull requests. Please see the [Code of Conduct](CODE_OF_CONDUCT.md) for details. + +When submitting a pull request, we ask you to check the following: + +1. **Unit tests**, **documentation**, and **code style** are in order. + See the Continuous Integration for up to date information on the current code style, tests, and any other requirements. + + It is also OK to submit work in progress if you're unsure of what this exactly means, in which case you'll likely be asked to make some further changes. + +2. The contributed code will be **licensed under the same [license](LICENSE) as the rest of the repository**, If you did not write the code yourself, you must ensure the existing license is compatible and include the license information in the contributed files, or obtain permission from the original author to relicense the contributed code. diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..6b8b53b --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,68 @@ +Apache License +Version 2.0, January 2004 +http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + +"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. + +"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. + +"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. + +"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. + +"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. + +"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. + +"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). + +"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. + +"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." + +"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. + +2. Grant of Copyright License. + +Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. + +Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. + +4. Redistribution. + +You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: + + You must give any other recipients of the Work or Derivative Works a copy of this License; and + You must cause any modified files to carry prominent notices stating that You changed the files; and + You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and + If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. + +You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. + +5. Submission of Contributions. + +Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. + +6. Trademarks. + +This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. + +Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. + +In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. + +While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS diff --git a/README.md b/README.md new file mode 100644 index 0000000..4fff411 --- /dev/null +++ b/README.md @@ -0,0 +1,110 @@ +# The Sensein's python package template repo + +Welcome to the [Sensein](https://sensein.group/) python template repo! +This template is here to help you kick off your projects with a clean and efficient setup. +It's inspired by the [python template by the Child Mind Institute](https://github.com/childmindresearch/template-python-repository) (thanks you!). Our version diverges in its setup process and in both the variety and quantity of automated features included. + +Just follow these steps, and you'll be on your way: +1. **Choose a unique package name:** First off, you need a cool name for your package. To make sure it's not already taken on PyPI, head over to `https://pypi.org/project/YOUR_PACKAGE_NAME/`. If you get a "Not Found" page, you're likely good to go! + +2. **Use this template:** Go to the GitHub page for this template. You'll find a "Use this template" button on the top right. Click it to start setting up your project with the template's structure. + +3. **Configure your project:** During the setup, you'll specify some basics like your project's name and whether it's public or private. You will be able to change this info in the future, no pressure! + +4. **Add GitHub Secrets:** For automated processes, add these secrets to your GitHub repo: + +- `PYPI_TOKEN`: Your token for PyPI, allowing GitHub Actions to publish your package. +- `AUTO_ORG_TOKEN`: A token for automated organization actions (this is useful for using [auto](https://github.com/intuit/auto) for automatic changelog generation). +- `CODECOV_TOKEN`: Your [Codecov](https://about.codecov.io/) token for reporting code coverage. + +To obtain these tokens: +- For `PYPI_TOKEN`, log in to your PyPI account, go to your account settings, and create an API token. Alternatively, ask the admin of your organization to do so. +- `AUTO_ORG_TOKEN` is a personal access token from GitHub, used for actions requiring organization-level permissions. Generate one in your GitHub settings under Developer settings > Personal access tokens. Alternatively, if the repo is under your organization GitHub, please, ask the admin of your organization to provide one. +- For `CODECOV_TOKEN`, sign up or log in to Codecov, add your repository, and you'll be provided with a token. + +To add these tokens: +Go to your repository on GitHub, click on "Settings" > "Secrets" > "Actions", then click on "New repository secret". Name your secret (e.g., `PYPI_TOKEN`) and paste the token value. Repeat this for each token. + +5. **Clone the repo:** Once your repository is set up, clone it to your local machine. + +6. **Replace placeholders with custom values**: Please, run `python template_setup.py --package-name YOUR_PACKAGE_NAME --package-repo-without-git-extension YOUR_PACKAGE_REPO --github-nickname YOUR_GITHUB_NICKNAME --codecov-token CODECOV_GRAPHICS_TOKEN --email YOUR_EMAIL`. +For example, `python template_setup.py --package-name pipepal --package-repo-without-git-extension https://github.com/fabiocat93/pipepal --github-nickname fabiocat93 --codecov-token IQR1RCYMAA --email fabiocat@mit.edu`. This will replace some placeholders in the entire directory (including folder names, file names, file content) with your custom info: +- YOUR_PACKAGE_NAME (e.g., `pipepal`) +- YOUR_PACKAGE_REPO (e.g., `https://github.com/sensein/pipepal`) +- YOUR_GITHUB_NICKNAME (e.g., `sensein`) +- CODECOV_GRAPHICS_TOKEN (e.g.,`ABC0DEFGHI`) +- YOUR_EMAIL (e.g., `sensein@mit.edu`) +It will also enable GitHub custom automation and delete the `template_setup.py` (you won't need that anymore). + +7. **Adjust `pyproject.toml`:** Please, double-check `pyproject.toml` and update it with some custom info, if needed (i.e., `description`, `authors`, `maintainers`, `description`, `homepage`, `repository`, `keywords`, and `classifiers`). No need to touch `version`. This will be automatically handled by the package. + +8. **Update README.md:** Replace the content of this README.md with information specific to your project. + +9. **Install poetry:** Poetry is a fantastic tool for managing dependencies and packaging. If you haven't installed it yet, check out their [documentation](https://python-poetry.org/docs/) for guidance. It's pretty straightforward. + +10. **Verify poetry setup:** Run `poetry --help` to ensure everything is set up correctly. To verify that the project folder is all in order, you can run `poetry check`. + +11. **Install dependencies:** Get all your project's dependencies in place by running `poetry install --with dev`. + +12. **Secure your package name:** Even if you're not quite ready to publish, consider securing your package name on PyPI. You can do this by publishing a dummy version (0.0.1) of your package with `poetry publish --build`. + +13. **Commit and push:** Now's the time to add (e.g., `git add .`) and commit (e.g., `git commit -m "here goes a wonderful message"`) your changes. Consider adding a tag for your initial version (recommended), like `git tag 0.0.1`, then push it all to GitHub with `git push --tags` and `git push origin main`. + +14. **Check GitHub actions:** If your push was successful, it'll trigger some GitHub Actions like code quality checks and tests. Make sure everything passes! + +15. **Work in dev branch:** For future changes, create a `dev` branch and make your updates there. Use pull requests to merge these changes into the main branch. + +16. **Releasing new versions:** If you want to release a new version of your package, add a "release" label to your pull request. This will trigger all the necessary actions to update the version tag, create a changelog, release the new version, and even create/update your package documentation. + +17. **Set up API documentation:** After your first successful pull request, set up your API documentation website. Go to your repository's settings, find the GitHub Pages section, and select `docs` as the source. You'll get a link to your API docs. + +18. **[Bonus] Customize issue and pull request remplates:** Optionally, you can customize your issue and pull request remplates from the `.github` folder. + +That's it! With these steps, you're well on your way to creating an awesome Python package. Keep up the great work, and **happy coding**! + + +# The ```YOUR_PACKAGE_NAME``` repo + +[![Build](YOUR_PACKAGE_REPO/actions/workflows/test.yaml/badge.svg?branch=main)](YOUR_PACKAGE_REPO/actions/workflows/test.yaml?query=branch%3Amain) +[![codecov](https://codecov.io/gh/YOUR_GITHUB_NICKNAME/YOUR_PACKAGE_NAME/branch/main/graph/badge.svg?token=CODECOV_GRAPHICS_TOKEN)](https://codecov.io/gh/YOUR_GITHUB_NICKNAME/YOUR_PACKAGE_NAME) +[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) + +[![PyPI](https://img.shields.io/pypi/v/YOUR_PACKAGE_NAME.svg)](https://pypi.org/project/YOUR_PACKAGE_NAME/) +[![Python Version](https://img.shields.io/pypi/pyversions/YOUR_PACKAGE_NAME)](https://pypi.org/project/YOUR_PACKAGE_NAME) +[![License](https://img.shields.io/pypi/l/YOUR_PACKAGE_NAME)](https://opensource.org/licenses/Apache-2.0) + +[![pages](https://img.shields.io/badge/api-docs-blue)](https://YOUR_GITHUB_NICKNAME.github.io/YOUR_PACKAGE_NAME) + +Welcome to the ```YOUR_PACKAGE_NAME``` repo! This is a Python package for doing incredible stuff. + +**Caution:**: this package is still under development and may change rapidly over the next few weeks. + +## Features +- A few +- Cool +- Things +- These may include a wonderful CLI interface. + +## Installation +Install this package via : + +```sh +pip install YOUR_PACKAGE_NAME +``` + +Or get the newest development version via: + +```sh +pip install git+YOUR_PACKAGE_REPO.git +``` + +## Quick start +```Python +from YOUR_PACKAGE_NAME.app import hello_world + +hello_world() +``` + +## To do: +- [ ] A +- [ ] lot diff --git a/docs_style/pdoc-theme/syntax-highlighting.css b/docs_style/pdoc-theme/syntax-highlighting.css new file mode 100644 index 0000000..84e5ca5 --- /dev/null +++ b/docs_style/pdoc-theme/syntax-highlighting.css @@ -0,0 +1,156 @@ + +/* auto-generated, see templates/README.md */ +pre { line-height: 125%; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 20px; } +.pdoc-code .hll { background-color: #ffffcc } +.pdoc-code { background: #f8f8f8; } +.pdoc-code .c { color: #3D7B7B; font-style: italic } /* Comment */ +.pdoc-code .err { border: 1px solid #FF0000 } /* Error */ +.pdoc-code .k { color: #008000; font-weight: bold } /* Keyword */ +.pdoc-code .o { color: #666666 } /* Operator */ +.pdoc-code .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */ +.pdoc-code .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */ +.pdoc-code .cp { color: #9C6500 } /* Comment.Preproc */ +.pdoc-code .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */ +.pdoc-code .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */ +.pdoc-code .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */ +.pdoc-code .gd { color: #A00000 } /* Generic.Deleted */ +.pdoc-code .ge { font-style: italic } /* Generic.Emph */ +.pdoc-code .gr { color: #E40000 } /* Generic.Error */ +.pdoc-code .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.pdoc-code .gi { color: #008400 } /* Generic.Inserted */ +.pdoc-code .go { color: #717171 } /* Generic.Output */ +.pdoc-code .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.pdoc-code .gs { font-weight: bold } /* Generic.Strong */ +.pdoc-code .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.pdoc-code .gt { color: #0044DD } /* Generic.Traceback */ +.pdoc-code .kc { color: #008000; font-weight: bold } /* Keyword.Constant */ +.pdoc-code .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ +.pdoc-code .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ +.pdoc-code .kp { color: #008000 } /* Keyword.Pseudo */ +.pdoc-code .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ +.pdoc-code .kt { color: #B00040 } /* Keyword.Type */ +.pdoc-code .m { color: #666666 } /* Literal.Number */ +.pdoc-code .s { color: #BA2121 } /* Literal.String */ +.pdoc-code .na { color: #687822 } /* Name.Attribute */ +.pdoc-code .nb { color: #008000 } /* Name.Builtin */ +.pdoc-code .nc { color: #0000FF; font-weight: bold } /* Name.Class */ +.pdoc-code .no { color: #880000 } /* Name.Constant */ +.pdoc-code .nd { color: #AA22FF } /* Name.Decorator */ +.pdoc-code .ni { color: #717171; font-weight: bold } /* Name.Entity */ +.pdoc-code .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */ +.pdoc-code .nf { color: #0000FF } /* Name.Function */ +.pdoc-code .nl { color: #767600 } /* Name.Label */ +.pdoc-code .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.pdoc-code .nt { color: #008000; font-weight: bold } /* Name.Tag */ +.pdoc-code .nv { color: #19177C } /* Name.Variable */ +.pdoc-code .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.pdoc-code .w { color: #bbbbbb } /* Text.Whitespace */ +.pdoc-code .mb { color: #666666 } /* Literal.Number.Bin */ +.pdoc-code .mf { color: #666666 } /* Literal.Number.Float */ +.pdoc-code .mh { color: #666666 } /* Literal.Number.Hex */ +.pdoc-code .mi { color: #666666 } /* Literal.Number.Integer */ +.pdoc-code .mo { color: #666666 } /* Literal.Number.Oct */ +.pdoc-code .sa { color: #BA2121 } /* Literal.String.Affix */ +.pdoc-code .sb { color: #BA2121 } /* Literal.String.Backtick */ +.pdoc-code .sc { color: #BA2121 } /* Literal.String.Char */ +.pdoc-code .dl { color: #BA2121 } /* Literal.String.Delimiter */ +.pdoc-code .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ +.pdoc-code .s2 { color: #BA2121 } /* Literal.String.Double */ +.pdoc-code .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */ +.pdoc-code .sh { color: #BA2121 } /* Literal.String.Heredoc */ +.pdoc-code .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */ +.pdoc-code .sx { color: #008000 } /* Literal.String.Other */ +.pdoc-code .sr { color: #A45A77 } /* Literal.String.Regex */ +.pdoc-code .s1 { color: #BA2121 } /* Literal.String.Single */ +.pdoc-code .ss { color: #19177C } /* Literal.String.Symbol */ +.pdoc-code .bp { color: #008000 } /* Name.Builtin.Pseudo */ +.pdoc-code .fm { color: #0000FF } /* Name.Function.Magic */ +.pdoc-code .vc { color: #19177C } /* Name.Variable.Class */ +.pdoc-code .vg { color: #19177C } /* Name.Variable.Global */ +.pdoc-code .vi { color: #19177C } /* Name.Variable.Instance */ +.pdoc-code .vm { color: #19177C } /* Name.Variable.Magic */ +.pdoc-code .il { color: #666666 } /* Literal.Number.Integer.Long */ + +@media (prefers-color-scheme: dark) { + /* monokai color scheme, see pdoc/template/README.md */ + pre { line-height: 125%; } + span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 20px; } + .pdoc-code .hll { background-color: #49483e } + .pdoc-code { background: #272822; color: #f8f8f2 } + .pdoc-code .c { color: #75715e } /* Comment */ + .pdoc-code .err { color: #960050; background-color: #1e0010 } /* Error */ + .pdoc-code .esc { color: #f8f8f2 } /* Escape */ + .pdoc-code .g { color: #f8f8f2 } /* Generic */ + .pdoc-code .k { color: #66d9ef } /* Keyword */ + .pdoc-code .l { color: #ae81ff } /* Literal */ + .pdoc-code .n { color: #f8f8f2 } /* Name */ + .pdoc-code .o { color: #f92672 } /* Operator */ + .pdoc-code .x { color: #f8f8f2 } /* Other */ + .pdoc-code .p { color: #f8f8f2 } /* Punctuation */ + .pdoc-code .ch { color: #75715e } /* Comment.Hashbang */ + .pdoc-code .cm { color: #75715e } /* Comment.Multiline */ + .pdoc-code .cp { color: #75715e } /* Comment.Preproc */ + .pdoc-code .cpf { color: #75715e } /* Comment.PreprocFile */ + .pdoc-code .c1 { color: #75715e } /* Comment.Single */ + .pdoc-code .cs { color: #75715e } /* Comment.Special */ + .pdoc-code .gd { color: #f92672 } /* Generic.Deleted */ + .pdoc-code .ge { color: #f8f8f2; font-style: italic } /* Generic.Emph */ + .pdoc-code .gr { color: #f8f8f2 } /* Generic.Error */ + .pdoc-code .gh { color: #f8f8f2 } /* Generic.Heading */ + .pdoc-code .gi { color: #a6e22e } /* Generic.Inserted */ + .pdoc-code .go { color: #66d9ef } /* Generic.Output */ + .pdoc-code .gp { color: #f92672; font-weight: bold } /* Generic.Prompt */ + .pdoc-code .gs { color: #f8f8f2; font-weight: bold } /* Generic.Strong */ + .pdoc-code .gu { color: #75715e } /* Generic.Subheading */ + .pdoc-code .gt { color: #f8f8f2 } /* Generic.Traceback */ + .pdoc-code .kc { color: #66d9ef } /* Keyword.Constant */ + .pdoc-code .kd { color: #66d9ef } /* Keyword.Declaration */ + .pdoc-code .kn { color: #f92672 } /* Keyword.Namespace */ + .pdoc-code .kp { color: #66d9ef } /* Keyword.Pseudo */ + .pdoc-code .kr { color: #66d9ef } /* Keyword.Reserved */ + .pdoc-code .kt { color: #66d9ef } /* Keyword.Type */ + .pdoc-code .ld { color: #e6db74 } /* Literal.Date */ + .pdoc-code .m { color: #ae81ff } /* Literal.Number */ + .pdoc-code .s { color: #e6db74 } /* Literal.String */ + .pdoc-code .na { color: #a6e22e } /* Name.Attribute */ + .pdoc-code .nb { color: #f8f8f2 } /* Name.Builtin */ + .pdoc-code .nc { color: #a6e22e } /* Name.Class */ + .pdoc-code .no { color: #66d9ef } /* Name.Constant */ + .pdoc-code .nd { color: #a6e22e } /* Name.Decorator */ + .pdoc-code .ni { color: #f8f8f2 } /* Name.Entity */ + .pdoc-code .ne { color: #a6e22e } /* Name.Exception */ + .pdoc-code .nf { color: #a6e22e } /* Name.Function */ + .pdoc-code .nl { color: #f8f8f2 } /* Name.Label */ + .pdoc-code .nn { color: #f8f8f2 } /* Name.Namespace */ + .pdoc-code .nx { color: #a6e22e } /* Name.Other */ + .pdoc-code .py { color: #f8f8f2 } /* Name.Property */ + .pdoc-code .nt { color: #f92672 } /* Name.Tag */ + .pdoc-code .nv { color: #f8f8f2 } /* Name.Variable */ + .pdoc-code .ow { color: #f92672 } /* Operator.Word */ + .pdoc-code .w { color: #f8f8f2 } /* Text.Whitespace */ + .pdoc-code .mb { color: #ae81ff } /* Literal.Number.Bin */ + .pdoc-code .mf { color: #ae81ff } /* Literal.Number.Float */ + .pdoc-code .mh { color: #ae81ff } /* Literal.Number.Hex */ + .pdoc-code .mi { color: #ae81ff } /* Literal.Number.Integer */ + .pdoc-code .mo { color: #ae81ff } /* Literal.Number.Oct */ + .pdoc-code .sa { color: #e6db74 } /* Literal.String.Affix */ + .pdoc-code .sb { color: #e6db74 } /* Literal.String.Backtick */ + .pdoc-code .sc { color: #e6db74 } /* Literal.String.Char */ + .pdoc-code .dl { color: #e6db74 } /* Literal.String.Delimiter */ + .pdoc-code .sd { color: #e6db74 } /* Literal.String.Doc */ + .pdoc-code .s2 { color: #e6db74 } /* Literal.String.Double */ + .pdoc-code .se { color: #ae81ff } /* Literal.String.Escape */ + .pdoc-code .sh { color: #e6db74 } /* Literal.String.Heredoc */ + .pdoc-code .si { color: #e6db74 } /* Literal.String.Interpol */ + .pdoc-code .sx { color: #e6db74 } /* Literal.String.Other */ + .pdoc-code .sr { color: #e6db74 } /* Literal.String.Regex */ + .pdoc-code .s1 { color: #e6db74 } /* Literal.String.Single */ + .pdoc-code .ss { color: #e6db74 } /* Literal.String.Symbol */ + .pdoc-code .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */ + .pdoc-code .fm { color: #a6e22e } /* Name.Function.Magic */ + .pdoc-code .vc { color: #f8f8f2 } /* Name.Variable.Class */ + .pdoc-code .vg { color: #f8f8f2 } /* Name.Variable.Global */ + .pdoc-code .vi { color: #f8f8f2 } /* Name.Variable.Instance */ + .pdoc-code .vm { color: #f8f8f2 } /* Name.Variable.Magic */ +} diff --git a/docs_style/pdoc-theme/theme.css b/docs_style/pdoc-theme/theme.css new file mode 100644 index 0000000..b86b093 --- /dev/null +++ b/docs_style/pdoc-theme/theme.css @@ -0,0 +1,44 @@ +/* pdoc color scheme (see also: examples/dark-mode) */ +:root { + --pdoc-background: #fff; +} + +.pdoc { + --text: #212529; + --muted: #6c757d; + --link: #3660a5; + --link-hover: #1659c5; + --code: #f8f8f8; + --active: #fff598; + + --accent: #eee; + --accent2: #c1c1c1; + + --nav-hover: rgba(255, 255, 255, 0.5); + --name: #0066BB; + --def: #008800; + --annotation: #007020; +} + +@media (prefers-color-scheme: dark) { + :root { + --pdoc-background: #212529; + } + + .pdoc { + --text: #f7f7f7; + --muted: #9d9d9d; + --link: #58a6ff; + --link-hover: #3989ff; + --code: #333; + --active: #555; + + --accent: #343434; + --accent2: #555; + + --nav-hover: rgba(0, 0, 0, 0.1); + --name: #77C1FF; + --def: #0cdd0c; + --annotation: #00c037; + } +} diff --git a/github/ISSUE_TEMPLATE/bug_report.yaml b/github/ISSUE_TEMPLATE/bug_report.yaml new file mode 100644 index 0000000..8722b69 --- /dev/null +++ b/github/ISSUE_TEMPLATE/bug_report.yaml @@ -0,0 +1,47 @@ +name: Bug Report +description: This is a template for reporting a bug. +# If you want to enable automatic linking to projects, +# uncomment the following line and replace the project ID +# with the ID of your project. +# projects: ["pipepal"] +title: 'Bug: ' +labels: [bug] +body: +- type: textarea + id: description + attributes: + label: Description + description: Please provide a clear and concise description of the bug. + placeholder: Describe the bug here + validations: + required: true +- type: textarea + id: steps-to-reproduce + attributes: + label: Steps to Reproduce + description: Please provide detailed steps to reproduce the bug. + placeholder: Describe the steps to reproduce the bug here. + validations: + required: true +- type: textarea + id: expected-results + attributes: + label: Expected Results + description: Please describe what you expected to happen. + placeholder: Describe the expected results here. + validations: + required: true +- type: textarea + id: actual-results + attributes: + label: Actual Results + description: Please describe what actually happened. + placeholder: Describe the actual results here. + validations: + required: true +- type: textarea + id: additional-notes + attributes: + label: Additional Notes + description: Add any additional notes or context here. + placeholder: Add additional notes here. diff --git a/github/ISSUE_TEMPLATE/development_task.yaml b/github/ISSUE_TEMPLATE/development_task.yaml new file mode 100644 index 0000000..5881a3d --- /dev/null +++ b/github/ISSUE_TEMPLATE/development_task.yaml @@ -0,0 +1,32 @@ +name: Development Task +description: This is a template for a development task +# If you want to enable automatic linking to projects, +# uncomment the following line and replace the project ID +# with the ID of your project. +# projects: ["pipepal"] +title: 'Task: ' +labels: [task] +body: +- type: textarea + id: description + attributes: + label: Description + description: What is the task about? Why is it needed? What is the current state, if any? + placeholder: Describe the task here + validations: + required: true +- type: textarea + id: tasks + attributes: + label: Tasks + description: What are the concrete (sub-)tasks that need to be performed? + placeholder: Describe the tasks here. + value: '- [ ] Task 1' + validations: + required: true +- type: textarea + id: freeform-notes + attributes: + label: Freeform Notes + description: Add any additional notes here. + placeholder: Add notes here. diff --git a/github/ISSUE_TEMPLATE/general.yaml b/github/ISSUE_TEMPLATE/general.yaml new file mode 100644 index 0000000..2ee53e9 --- /dev/null +++ b/github/ISSUE_TEMPLATE/general.yaml @@ -0,0 +1,17 @@ +name: Other +description: This is a template for reporting a general issue. +# If you want to enable automatic linking to projects, +# uncomment the following line and replace the project ID +# with the ID of your project. +# projects: ["pipepal"] +title: '' +labels: [other] +body: +- type: textarea + id: description + attributes: + label: Text + description: Please, provide a clear and concise piece of information. + placeholder: Please, provide a clear and concise piece of information. + validations: + required: false \ No newline at end of file diff --git a/github/ISSUE_TEMPLATE/support_request.yaml b/github/ISSUE_TEMPLATE/support_request.yaml new file mode 100644 index 0000000..743fd4b --- /dev/null +++ b/github/ISSUE_TEMPLATE/support_request.yaml @@ -0,0 +1,47 @@ +name: Support Request +description: This is a template for submitting a support request. +# If you want to enable automatic linking to projects, +# uncomment the following line and replace the project ID +# with the ID of your project. +# projects: ["pipepal"] +title: 'Support: ' +labels: [question] +body: +- type: textarea + id: issue-description + attributes: + label: Issue Description + description: Please provide a clear and concise description of the issue you are facing. + placeholder: Describe the issue here + validations: + required: true +- type: textarea + id: environment-details + attributes: + label: Environment Details + description: Please provide details about your environment, including system specifications, software versions, etc. + placeholder: Describe your environment details here. + validations: + required: false +- type: textarea + id: attempted-solutions + attributes: + label: Attempted Solutions + description: Describe any steps you have already taken to resolve the issue. + placeholder: Describe any attempted solutions here. + validations: + required: false +- type: textarea + id: reproduction-steps + attributes: + label: Reproduction Steps + description: If applicable, provide steps to reproduce the issue. + placeholder: Describe the steps to reproduce the issue, if applicable. + validations: + required: false +- type: textarea + id: additional-notes + attributes: + label: Additional Notes + description: Add any other context or screenshots about the support request here. + placeholder: Add additional notes or screenshots here. diff --git a/github/PULL_REQUEST_TEMPLATE/advanced.md b/github/PULL_REQUEST_TEMPLATE/advanced.md new file mode 100644 index 0000000..9ebd8e9 --- /dev/null +++ b/github/PULL_REQUEST_TEMPLATE/advanced.md @@ -0,0 +1,26 @@ +# Advanced Pull Request Template + +## Description +Briefly describe the changes you've made. + +## Related Issue(s) +Link any related issues here. + +## Motivation and Context +Explain why these changes are necessary and what problem they solve. + +## How Has This Been Tested? +Describe how you have tested these changes. + +## Screenshots (if appropriate): +Include any relevant screenshots. + +## Types of changes +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to change) + +## Checklist: +- [ ] My code follows the code style of this project. +- [ ] I have added tests to cover my changes. +- [ ] All new and existing tests passed. \ No newline at end of file diff --git a/github/PULL_REQUEST_TEMPLATE/basic.md b/github/PULL_REQUEST_TEMPLATE/basic.md new file mode 100644 index 0000000..48fbe48 --- /dev/null +++ b/github/PULL_REQUEST_TEMPLATE/basic.md @@ -0,0 +1,4 @@ +# Basic Pull Request Template + +## Description +Briefly describe the changes you've made. \ No newline at end of file diff --git a/github/dependabot.yaml b/github/dependabot.yaml new file mode 100644 index 0000000..aef7525 --- /dev/null +++ b/github/dependabot.yaml @@ -0,0 +1,27 @@ +# Please see the documentation for all configuration options: +# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates + +# Dependabot configuration for updating dependencies and GitHub Actions +version: 2 +updates: + # Configuration for Python package updates using pip + - package-ecosystem: pip + directory: "/" + schedule: + interval: monthly + open-pull-requests-limit: 5 + groups: + production-dependencies: + dependency-type: production + development-dependencies: + dependency-type: development + + # Configuration for GitHub Actions updates + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: monthly + open-pull-requests-limit: 5 + +# Enable automatic security updates +security_updates: true \ No newline at end of file diff --git a/github/workflows/docs.yaml b/github/workflows/docs.yaml new file mode 100644 index 0000000..a9dfefb --- /dev/null +++ b/github/workflows/docs.yaml @@ -0,0 +1,83 @@ +name: Build and Publish Docs + +permissions: + contents: write + pages: write + id-token: write + +on: + release: + types: [published] + +jobs: + build-docs: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest] + python-version: ["3.10"] + include: + - os: ubuntu-latest + python-version: "3.10" + deploy: true # Only deploy from this configuration + outputs: + deploy: ${{ steps.set-deploy-output.outputs.deploy }} + steps: + - uses: actions/checkout@v4 + with: # no need for the history + fetch-depth: 0 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + # Cache Poetry dependencies to speed up builds + - name: Cache Poetry virtualenv + uses: actions/cache@v3 + with: + path: ~/.cache/pypoetry + key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }} + restore-keys: | + ${{ runner.os }}-poetry- + - name: Install dependencies + run: | + python -m pip install poetry + poetry install --with docs + shell: bash + - name: Build docs + run: | + APP_MODULE_NAME=$(ls src -U | head -1) + poetry run pdoc src/"$APP_MODULE_NAME" -o docs -t docs_style/pdoc-theme --docformat google + touch docs/.nojekyll + shell: bash + - name: Determine if deployment is needed + id: set-deploy-output + run: echo "::set-output name=deploy::true" + shell: bash + - uses: actions/upload-artifact@v3 + with: + name: documentation + path: docs + + publish-docs: + needs: build-docs + if: ${{ needs.build-docs.outputs.deploy == 'true' }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest] # For demonstration, other OSes are commented out + python-version: ["3.10"] + include: + - os: ubuntu-latest + python-version: "3.10" + deploy: true # Only deploy from this configuration + steps: + - uses: actions/checkout@v4 + - uses: actions/download-artifact@v3 + with: + name: documentation + path: docs + - uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs + branch: docs diff --git a/github/workflows/publish.yaml b/github/workflows/publish.yaml new file mode 100644 index 0000000..19999d2 --- /dev/null +++ b/github/workflows/publish.yaml @@ -0,0 +1,58 @@ +name: Publish to PyPI + +on: + release: + types: [published] + +jobs: + pypi-release: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest] + python-version: ["3.10"] + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # Includes getting tags + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + - name: Install pipx and ensure it's up to date + run: | + python -m pip install --upgrade pipx + pipx ensurepath + shell: bash + - name: Install poetry + run: pipx install poetry + shell: bash + # Cache Poetry dependencies to speed up builds + - name: Cache Poetry virtualenv + uses: actions/cache@v3 + with: + path: ~/.cache/pypoetry + key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }} + restore-keys: | + ${{ runner.os }}-poetry- + - name: Install poetry dynamic versioning tool + run: pipx inject poetry "poetry-dynamic-versioning[plugin]" + shell: bash + - name: Install dependencies with Poetry + run: poetry install --with dev + shell: bash + - name: Build package + run: poetry build + shell: bash + - name: Configure Poetry PyPI token + run: poetry config pypi-token.pypi ${{ secrets.PYPI_TOKEN }} + shell: bash + - name: Publish to PyPI + env: + POETRY_REQUESTS_TIMEOUT: 120 + run: poetry publish + shell: bash + + + + diff --git a/github/workflows/release.yaml b/github/workflows/release.yaml new file mode 100644 index 0000000..d3b86b7 --- /dev/null +++ b/github/workflows/release.yaml @@ -0,0 +1,46 @@ +name: Auto-release + +on: + # ATM, this is the closest trigger to a PR merging + workflow_run: + workflows: ["Python Tests"] + branches: [main] + types: [completed] + +env: + AUTO_VERSION: v11.1.2 + +jobs: + auto-release: + if: ${{ github.event.workflow_run.conclusion == 'success' }} + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Prepare repository + # Fetch full git history and tags + run: git fetch --unshallow --tags + + - name: Unset header + # checkout@v2 adds a header that makes branch protection report errors + # because the Github action bot is not a collaborator on the repo + run: git config --local --unset http.https://github.com/.extraheader + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.10" + + - name: Download auto + run: | + auto_download_url="$(curl -fsSL https://api.github.com/repos/intuit/auto/releases/tags/$AUTO_VERSION | jq -r '.assets[] | select(.name == "auto-linux.gz") | .browser_download_url')" + wget -O- "$auto_download_url" | gunzip > ~/auto + chmod a+x ~/auto + + - name: Create release + run: | + ~/auto shipit -vv + env: + GH_TOKEN: ${{ secrets.AUTO_ORG_TOKEN }} + diff --git a/github/workflows/test.yaml b/github/workflows/test.yaml new file mode 100644 index 0000000..e6e70cd --- /dev/null +++ b/github/workflows/test.yaml @@ -0,0 +1,110 @@ +name: Python Tests + +on: + push: + branches: + - main + pull_request: + schedule: + - cron: '0 6 1 * *' + +jobs: + unit: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest] # For demonstration, other OSes are commented out: macos-latest, windows-latest + python-version: ["3.11", "3.10"] + steps: + - uses: actions/checkout@v4 + with: # no need for the history + fetch-depth: 1 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + - name: Install pipx and ensure it's up to date + run: | + python -m pip install --upgrade pipx + pipx ensurepath + shell: bash + - name: Install poetry + run: pipx install poetry + shell: bash + # Cache Poetry dependencies to speed up builds + - name: Cache Poetry virtualenv + uses: actions/cache@v3 + with: + path: ~/.cache/pypoetry + key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }} + restore-keys: | + ${{ runner.os }}-poetry- + - name: Install dependencies with Poetry + run: | + poetry install --with dev + shell: bash + - name: Run unit tests + id: run-tests + run: > + poetry run pytest \ + --junitxml=pytest.xml \ + --cov-report=term-missing:skip-covered \ + --cov-report=xml:coverage.xml \ + --cov=src src/tests \ + --log-level=DEBUG \ + --verbose + shell: bash + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v4 + with: + token: ${{ secrets.CODECOV_TOKEN }} + + ruff: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest] # For demonstration, other OSes are commented out: macos-latest, windows-latest + python-version: ["3.11", "3.10"] + steps: + - uses: actions/checkout@v4 + with: # no need for the history + fetch-depth: 1 + - uses: chartboost/ruff-action@v1 + + mypy: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest] # For demonstration, other OSes are commented out: macos-latest, windows-latest + python-version: ["3.11", "3.10"] + steps: + - uses: actions/checkout@v4 + with: # no need for the history + fetch-depth: 1 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + - name: Install pipx and ensure it's up to date + run: | + python -m pip install --upgrade pipx + pipx ensurepath + shell: bash + - name: Install poetry + run: pipx install poetry + shell: bash + # Cache Poetry dependencies to speed up builds + - name: Cache Poetry virtualenv + uses: actions/cache@v3 + with: + path: ~/.cache/pypoetry + key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }} + restore-keys: | + ${{ runner.os }}-poetry- + - name: Install dependencies with Poetry + run: | + poetry install --with dev + shell: bash + - name: Run mypy + run: poetry run mypy . + shell: bash \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..c675fab --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,116 @@ +[tool.poetry] +name = "YOUR_PACKAGE_NAME" +version = "0.0.1" +description = "YOUR_PACKAGE_NAME is a Python package for doing incredible stuff." +authors = [ + "YOUR_GITHUB_NICKNAME ", +] +maintainers = [ + "YOUR_GITHUB_NICKNAME ", +] +license = "Apache-2.0" +readme = "README.md" +homepage = "YOUR_PACKAGE_REPO" +repository = "YOUR_PACKAGE_REPO" +documentation = "https://YOUR_GITHUB_NICKNAME.github.io/YOUR_PACKAGE_NAME" +keywords = ["python", "package", "template"] +classifiers = [ + "Development Status :: 3 - Alpha", + "Programming Language :: Python :: 3.10", + "License :: OSI Approved :: Apache Software License", + "Operating System :: OS Independent" +] +packages = [{include = "YOUR_PACKAGE_NAME", from = "src"}] + +[tool.poetry.dependencies] +python = "^3.10" +click = "^8.1.7" + +[tool.poetry.group.dev] +optional = true +[tool.poetry.group.dev.dependencies] +pytest = "^8.1.1" +mypy = "^1.9.0" +pre-commit = "^3.7.0" +pytest-cov = "^5.0.0" +ruff = "^0.3.4" + +[tool.poetry.group.docs] +optional = true +[tool.poetry.group.docs.dependencies] +pdoc = "^14.4.0" + +[tool.pytest.ini_options] +pythonpath = [ + "src" +] +testpaths = [ + "src/tests" +] + +[tool.mypy] +ignore_missing_imports = true + +[tool.ruff] +exclude = [ + ".bzr", + ".direnv", + ".eggs", + ".git", + ".git-rewrite", + ".hg", + ".mypy_cache", + ".nox", + ".pants.d", + ".pytype", + ".ruff_cache", + ".svn", + ".tox", + ".venv", + "__pypackages__", + "_build", + "buck-out", + "build", + "dist", + "node_modules", + "venv" +] +line-length = 88 +indent-width = 4 +src = ["src"] +target-version = "py310" + +[tool.ruff.lint] +select = ["ANN", "D", "E", "F", "I"] +ignore = [ + "ANN101", # self should not be annotated. + "ANN102" # cls should not be annotated. +] +fixable = ["ALL"] +unfixable = [] +dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$" + +[tool.ruff.lint.pydocstyle] +convention = "google" + +[tool.ruff.lint.per-file-ignores] +"src/tests/**/*.py" = [] + +[tool.poetry.scripts] +YOUR_PACKAGE_NAME-cli = "YOUR_PACKAGE_NAME.cli:main" + +[tool.ruff.format] +quote-style = "double" +indent-style = "space" +skip-magic-trailing-comma = false +line-ending = "auto" + +[tool.poetry-dynamic-versioning] +enable = true +vcs = "git" +style = "pep440" +bump = true +pattern = "default-unprefixed" +[build-system] +requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"] +build-backend = "poetry_dynamic_versioning.backend" \ No newline at end of file diff --git a/src/YOUR_PACKAGE_NAME/__init__.py b/src/YOUR_PACKAGE_NAME/__init__.py new file mode 100644 index 0000000..08ea820 --- /dev/null +++ b/src/YOUR_PACKAGE_NAME/__init__.py @@ -0,0 +1 @@ +""".. include:: ../../README.md""" # noqa: D415 \ No newline at end of file diff --git a/src/YOUR_PACKAGE_NAME/app.py b/src/YOUR_PACKAGE_NAME/app.py new file mode 100644 index 0000000..b457dc5 --- /dev/null +++ b/src/YOUR_PACKAGE_NAME/app.py @@ -0,0 +1,11 @@ +"""This script defines a simple function that prints 'Hello World!' to the console. + +It then calls this function if the script is run as the main program. +""" + +def hello_world() -> None: + """Prints hello world.""" + print("Hello World!") + +if __name__ == "__main__": + hello_world() \ No newline at end of file diff --git a/src/YOUR_PACKAGE_NAME/cli.py b/src/YOUR_PACKAGE_NAME/cli.py new file mode 100644 index 0000000..8f2dae3 --- /dev/null +++ b/src/YOUR_PACKAGE_NAME/cli.py @@ -0,0 +1,17 @@ +"""This module defines CLI commands for the PipePal application.""" + +import click + +from .app import hello_world as hw_function # Renamed to avoid conflict + + +@click.group() +def main() -> None: + """Define the main CLI group.""" + pass + + +@main.command() +def hello_world() -> None: + """Execute the hello_world command from the app module.""" + hw_function() diff --git a/src/tests/test_app.py b/src/tests/test_app.py new file mode 100644 index 0000000..8eb5d7a --- /dev/null +++ b/src/tests/test_app.py @@ -0,0 +1,14 @@ +"""Tests for the app hello_world function.""" +from _pytest.capture import CaptureFixture + +from YOUR_PACKAGE_NAME.app import hello_world + + +def test_hello_world(capsys: CaptureFixture) -> None: + """A test function for hello_world. + + This function uses the capsys fixture to capture stdout and stderr. + """ + hello_world() + captured = capsys.readouterr() # Captures the output of hello_world() + assert "Hello World!\n" == captured.out \ No newline at end of file diff --git a/template_setup.py b/template_setup.py new file mode 100644 index 0000000..34d9aa2 --- /dev/null +++ b/template_setup.py @@ -0,0 +1,140 @@ +import argparse +import os +import sys +from typing import Dict + + +def replace_in_file(file_path: str, replacements: Dict[str, str]) -> None: + """Replace placeholders in the content of a file with given values, skipping binary files. + + Args: + file_path: The path to the file where replacements need to be made. + replacements: A dictionary mapping placeholder strings to their replacement values. + """ + try: + with open(file_path, 'r', encoding='utf-8') as file: + content = file.read() + + original_content = content + for old, new in replacements.items(): + content = content.replace(old, new) + + if content != original_content: + with open(file_path, 'w', encoding='utf-8') as file: + file.write(content) + + except UnicodeDecodeError: + print(f"Skipping binary file: {file_path}") + + +def replace_in_filename(file_path: str, replacements: Dict[str, str]) -> str: + """Replace placeholders in the name of a file and return the new file path. + + Args: + file_path: The path to the file whose name needs to be modified. + replacements: A dictionary mapping placeholder strings to their values. + + Returns: + The new file path after renaming. + """ + directory, filename = os.path.split(file_path) + new_filename = filename + for old, new in replacements.items(): + new_filename = new_filename.replace(old, new) + + new_file_path = os.path.join(directory, new_filename) + if new_file_path != file_path: + os.rename(file_path, new_file_path) + + return new_file_path + +def replace_in_folder_name(dir_path: str, replacements: Dict[str, str]) -> str: + """Replace placeholders in the name of a folder and return the new folder path. + + Args: + dir_path: The path to the directory whose name needs to be modified. + replacements: A dictionary mapping placeholder strings to their replacement values. + + Returns: + The new directory path after renaming. + """ + parent_dir, dir_name = os.path.split(dir_path) + new_dir_name = dir_name + for old, new in replacements.items(): + new_dir_name = new_dir_name.replace(old, new) + + new_dir_path = os.path.join(parent_dir, new_dir_name) + if new_dir_path != dir_path: + os.rename(dir_path, new_dir_path) + return new_dir_path + + return dir_path + +def process_directory(replacements: Dict[str, str]) -> None: + """Recursively process a directory, replacing placeholders. + + Args: + replacements: A dictionary mapping placeholder strings to their values. + """ + for dirpath, dirnames, filenames in os.walk(".", topdown=False): + # Replace placeholders in the files' content and names + for filename in filenames: + file_path = os.path.join(dirpath, filename) + file_path = replace_in_filename(file_path, replacements) + replace_in_file(file_path, replacements) + + # Replace placeholders in the folder names + for dirname in dirnames: + dir_path = os.path.join(dirpath, dirname) + new_dir_path = replace_in_folder_name(dir_path, replacements) + # Update dirnames list to reflect any changes + index = dirnames.index(dirname) + dirnames[index] = os.path.basename(new_dir_path) + +def delete_current_script(): + """Deletes the currently executing script file.""" + script_file = sys.argv[0] # Get the name of the current file + try: + os.remove(script_file) # Attempt to delete the file + except Exception as e: + print(f"Error occurred while trying to delete the script: {e}") + +def rename_github_directory(): + """Renames a directory from 'github' to '.github'.""" + current_name, new_name = "github", ".github" + try: + # Check if the current directory exists + if os.path.exists(current_name): + # Rename the directory + os.rename(current_name, new_name) + print(f"Directory renamed from '{current_name}' to '{new_name}'") + else: + print(f"The directory '{current_name}' does not exist.") + except Exception as e: + print(f"Error renaming directory: {e}") + + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description="Replace placeholders.") + parser.add_argument("--package-name", required=True, help="Package name.") + parser.add_argument("--package-repo-without-git-extension", + required=True, + help="Package repository URL, without .git extension.") + parser.add_argument("--github-nickname", required=True, help="GitHub nickname.") + parser.add_argument("--codecov-token", required=True, help="Codecov graphics token.") + parser.add_argument("--email", required=True, help="Email address.") + + args = parser.parse_args() + + replacements = { + "YOUR_PACKAGE_NAME": args.package_name, + "YOUR_PACKAGE_REPO": args.package_repo_without_git_extension, + "YOUR_GITHUB_NICKNAME": args.github_nickname, + "CODECOV_GRAPHICS_TOKEN": args.codecov_token, + "YOUR_EMAIL": args.email, + } + + process_directory(replacements) + rename_github_directory() + delete_current_script() +