# Python project template
A simple template of a Python project, with a rigid file structure, and predisposition for unit testing and release on PyPi.
## Relevant features
- All your project code into a single main package (`aequitas-lib/`)
- All your project tests into a single test package (`test/`)
- Unit testing support via [`unittest`](https://docs.python.org/3/library/unittest.html)
- Automatic testing on all branches via GitHub Actions
- Semi-automatic versioning via Git
- Packaging support via [`setuptools`](https://setuptools.pypa.io/en/latest/setuptools.html)
- Automatic release on [PyPi](https://pypi.org/) via GitHub Actions
- Docker image support via `Dockerfile`
- Automatic release on [DockerHub](https://hub.docker.com/) via GitHub Actions
- Support for semi-automatic development environment management via [Pyenv](https://github.com/pyenv/pyenv)
- Automatic dependencies updates via [Renovate](https://docs.renovatebot.com/)
- Automatic conversion of `TODO` comments into GitHub issues via the `alstr/todo-to-issue-action`
## Project structure
Overview:
```bash
<root directory>
├── aequitas-lib/ # main package (should be named after your project)
│ ├── __init__.py # python package marker
│ └── __main__.py # application entry point
├── test/ # test package (should contain unit tests)
├── .github/ # configuration of GitHub CI
│ └── workflows/ # configuration of GitHub Workflows
│ ├── check.yml # runs tests on multiple OS and versions of Python
│ └── deploy.yml # if check succeeds, and the current branch is one of {main, master}, triggers automatic releas on PyPi
├── MANIFEST.in # file stating what to include/exclude in releases
├── LICENSE # license file (Apache 2.0 by default)
├── pyproject.toml # declares build dependencies
├── renovate.json # configuration of Renovate bot, for automatic dependency updates
├── requirements-dev.txt # declares development dependencies
├── requirements.txt # declares runtime dependencies
├── setup.py # configuration of the package to be released on Pypi
└── Dockerfile # configuration of the Docker image to be realsed on Dockerhub
```
## TODO-list for template usage
1. Use this template to create a new GitHub repository, say `aequitas-lib`
- this name will also be used to identify the package on PyPi
+ so, we suggest choosing a name which has not been used on PyPi, yet
+ we also suggest choosing a name which is a valid Python package name (i.e. `using_snake_case`)
2. Clone the `aequitas-lib` repository
3. Open a shell into your local `aequitas-lib` directory and run
```bash
./rename-template.sh aequitas-lib
```
This will coherently rename the template's project name with the one chosen by you (i.e. `aequitas-lib`, in this example)
4. Commit & push
5. Ensure you like the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html). If you don't, change the content of the `LICENSE` file
6. Ensure the version reported in `.python-version` corresponds to the actual Python version you are willing to use to develop your project
7. Check the Python version and OS tests should be run on in CI, by looking the file `.github/workflows/check.yml`
8. Add your runtime dependencies to `requirements.txt`
+ and development-only dependencies here `requirements-dev.txt`
9. Set your project's release metadata and dependencies by editing `setup.py`
10. Change the assignee for pull-requests for automatic dependency updates by editing `renovate.json`
+ currently defaults to @gciatto
11. Add your PyPi credentials as secrets of the GitHub repository
- `PYPI_USERNAME` (resp. `PYPI_PASSWORD`) for your username (resp. password)
- this may require you to register on PyPi first
12. Generate a GitHub token and add it as a secret of the GitHub repository, named `RELEASE_TOKEN`
- cf. <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic>
- the token must allow pushing to the repository
13. Put your main (resp. test) code in `aequitas-lib/` (resp. `test/`)
## How to do stuff
### Run your code as an application
This will execute the file `aequitas-lib/__main__.py`:
```bash
python -m aequitas-lib
```
### Run unit tests
```bash
python -m unittest discover -s test -t .
```
> Tests are automatically run in CI, on all pushes on all branches.
> There, tests are executed on multiple OS (Win, Mac, Ubuntu) and on multiple Python versions (from `3.8` to `3.11`).
### Restore dev dependencies
```bash
pip install -r requirements-dev.txt
```
### Release a new version on PyPi
> This paragraph is more understandable if the reader has some background about [GitFlow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)
GitHub actions automatically release a new version of `aequitas-lib` on PyPi whenever commits are pushed on either the `main`/`master` or `develop` branches, as well as when new tags are pushed.
Tags are assumed to consist of [semantic versioning](https://semver.org/) strings of the form `Major.Minor.Patch` where `Major`, `Minor`, and `Patch` are non-negative integers.
So, to release version `X.Y.Z`, developers must:
1. tag a commit on the `master`/`main`/`develop` branch, using `X.Y.Z` as the tag label
```bash
git tag -a 'X.Y.Z' -m <a message here describing the version>
```
2. push the tag
```bash
git push --follow-tags
```
3. GitHub Actions will then run tests and, if all of them succeed, release the code on PyPi.
After the release, users will be able to install your code via Pip.
> Non-tagged commits pushed on the `master`/`main`/`develop` branch will trigger __dev releases__.
> Dev releases are automatically tagged as `X.Y.Y.devN`, where
> - `X.Y.Y` is the value of the __most recent__ version tag
> - `N` is the amount of commits following the most recent version tag
Raw data
{
"_id": null,
"home_page": "https://github.com/aequitas-aod/aequitas-lib",
"name": "aequitas-lib",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10.5",
"maintainer_email": "",
"keywords": "aeuitas,horizon2020,xai,bias",
"author": "Panagiotis Kyziropoulos",
"author_email": "panagiotis.kyziropoulos@ucc.ie",
"download_url": "https://files.pythonhosted.org/packages/b2/17/7600eae382847b1cea21adaf73cf4c10488e08e88145b36520c6c51a538e/aequitas-lib-1.0.0.tar.gz",
"platform": "Independant",
"description": "# Python project template\n\nA simple template of a Python project, with a rigid file structure, and predisposition for unit testing and release on PyPi.\n\n## Relevant features\n\n- All your project code into a single main package (`aequitas-lib/`)\n- All your project tests into a single test package (`test/`)\n- Unit testing support via [`unittest`](https://docs.python.org/3/library/unittest.html)\n- Automatic testing on all branches via GitHub Actions\n- Semi-automatic versioning via Git\n- Packaging support via [`setuptools`](https://setuptools.pypa.io/en/latest/setuptools.html)\n- Automatic release on [PyPi](https://pypi.org/) via GitHub Actions\n- Docker image support via `Dockerfile`\n- Automatic release on [DockerHub](https://hub.docker.com/) via GitHub Actions\n- Support for semi-automatic development environment management via [Pyenv](https://github.com/pyenv/pyenv)\n- Automatic dependencies updates via [Renovate](https://docs.renovatebot.com/)\n- Automatic conversion of `TODO` comments into GitHub issues via the `alstr/todo-to-issue-action`\n\n## Project structure \n\nOverview:\n```bash\n<root directory>\n\u251c\u2500\u2500 aequitas-lib/ # main package (should be named after your project)\n\u2502 \u251c\u2500\u2500 __init__.py # python package marker\n\u2502 \u2514\u2500\u2500 __main__.py # application entry point\n\u251c\u2500\u2500 test/ # test package (should contain unit tests)\n\u251c\u2500\u2500 .github/ # configuration of GitHub CI\n\u2502 \u2514\u2500\u2500 workflows/ # configuration of GitHub Workflows\n\u2502 \u251c\u2500\u2500 check.yml # runs tests on multiple OS and versions of Python\n\u2502 \u2514\u2500\u2500 deploy.yml # if check succeeds, and the current branch is one of {main, master}, triggers automatic releas on PyPi\n\u251c\u2500\u2500 MANIFEST.in # file stating what to include/exclude in releases \n\u251c\u2500\u2500 LICENSE # license file (Apache 2.0 by default)\n\u251c\u2500\u2500 pyproject.toml # declares build dependencies\n\u251c\u2500\u2500 renovate.json # configuration of Renovate bot, for automatic dependency updates\n\u251c\u2500\u2500 requirements-dev.txt # declares development dependencies\n\u251c\u2500\u2500 requirements.txt # declares runtime dependencies\n\u251c\u2500\u2500 setup.py # configuration of the package to be released on Pypi\n\u2514\u2500\u2500 Dockerfile # configuration of the Docker image to be realsed on Dockerhub\n```\n\n## TODO-list for template usage\n\n1. Use this template to create a new GitHub repository, say `aequitas-lib`\n - this name will also be used to identify the package on PyPi\n + so, we suggest choosing a name which has not been used on PyPi, yet\n + we also suggest choosing a name which is a valid Python package name (i.e. `using_snake_case`)\n\n2. Clone the `aequitas-lib` repository\n\n3. Open a shell into your local `aequitas-lib` directory and run \n ```bash\n ./rename-template.sh aequitas-lib\n ``` \n \n This will coherently rename the template's project name with the one chosen by you (i.e. `aequitas-lib`, in this example)\n\n4. Commit & push\n\n5. Ensure you like the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html). If you don't, change the content of the `LICENSE` file\n\n6. Ensure the version reported in `.python-version` corresponds to the actual Python version you are willing to use to develop your project\n\n7. Check the Python version and OS tests should be run on in CI, by looking the file `.github/workflows/check.yml`\n\n8. Add your runtime dependencies to `requirements.txt`\n + and development-only dependencies here `requirements-dev.txt`\n\n9. Set your project's release metadata and dependencies by editing `setup.py`\n\n10. Change the assignee for pull-requests for automatic dependency updates by editing `renovate.json`\n + currently defaults to @gciatto\n\n11. Add your PyPi credentials as secrets of the GitHub repository \n - `PYPI_USERNAME` (resp. `PYPI_PASSWORD`) for your username (resp. password)\n - this may require you to register on PyPi first\n\n12. Generate a GitHub token and add it as a secret of the GitHub repository, named `RELEASE_TOKEN`\n - cf. <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic>\n - the token must allow pushing to the repository\n\n13. Put your main (resp. test) code in `aequitas-lib/` (resp. `test/`)\n\n## How to do stuff\n\n### Run your code as an application\n\nThis will execute the file `aequitas-lib/__main__.py`:\n```bash\npython -m aequitas-lib \n```\n\n### Run unit tests\n\n```bash\npython -m unittest discover -s test -t .\n```\n\n> Tests are automatically run in CI, on all pushes on all branches.\n> There, tests are executed on multiple OS (Win, Mac, Ubuntu) and on multiple Python versions (from `3.8` to `3.11`).\n\n### Restore dev dependencies\n\n```bash\npip install -r requirements-dev.txt\n```\n\n### Release a new version on PyPi\n\n> This paragraph is more understandable if the reader has some background about [GitFlow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)\n\nGitHub actions automatically release a new version of `aequitas-lib` on PyPi whenever commits are pushed on either the `main`/`master` or `develop` branches, as well as when new tags are pushed.\n\nTags are assumed to consist of [semantic versioning](https://semver.org/) strings of the form `Major.Minor.Patch` where `Major`, `Minor`, and `Patch` are non-negative integers.\n\nSo, to release version `X.Y.Z`, developers must:\n\n1. tag a commit on the `master`/`main`/`develop` branch, using `X.Y.Z` as the tag label\n ```bash\n git tag -a 'X.Y.Z' -m <a message here describing the version>\n ```\n\n2. push the tag\n ```bash\n git push --follow-tags\n ```\n\n3. GitHub Actions will then run tests and, if all of them succeed, release the code on PyPi.\nAfter the release, users will be able to install your code via Pip.\n\n> Non-tagged commits pushed on the `master`/`main`/`develop` branch will trigger __dev releases__.\n> Dev releases are automatically tagged as `X.Y.Y.devN`, where\n> - `X.Y.Y` is the value of the __most recent__ version tag\n> - `N` is the amount of commits following the most recent version tag \n",
"bugtrack_url": null,
"license": "Apache 2.0 License",
"summary": "Core library of the Aequitas project",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/aequitas-aod/aequitas-lib/issues",
"Homepage": "https://github.com/aequitas-aod/aequitas-lib",
"Source": "https://github.com/aequitas-aod/aequitas-lib"
},
"split_keywords": [
"aeuitas",
"horizon2020",
"xai",
"bias"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b2177600eae382847b1cea21adaf73cf4c10488e08e88145b36520c6c51a538e",
"md5": "529fab4abb67b56010e420b5488e36a1",
"sha256": "9d93861a371766468773a1765930b1f5d759c4464c6058e93cc861bc7a8e6ce8"
},
"downloads": -1,
"filename": "aequitas-lib-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "529fab4abb67b56010e420b5488e36a1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10.5",
"size": 28186,
"upload_time": "2023-10-11T13:46:23",
"upload_time_iso_8601": "2023-10-11T13:46:23.473251Z",
"url": "https://files.pythonhosted.org/packages/b2/17/7600eae382847b1cea21adaf73cf4c10488e08e88145b36520c6c51a538e/aequitas-lib-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-11 13:46:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aequitas-aod",
"github_project": "aequitas-lib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"==",
"1.26.0"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.11.3"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.0.3"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
"==",
"1.2.2"
]
]
}
],
"lcname": "aequitas-lib"
}
JSON
