Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/unsw-ceem/ceem-python-template

Template repo for CEEM Python projects
https://github.com/unsw-ceem/ceem-python-template

Last synced: about 1 month ago
JSON representation

Template repo for CEEM Python projects

Awesome Lists containing this project

README 

        
# UNSW CEEM Python Package Template



Replace the heading above with `your_package`.



## How do I use this template?



1. Hit "*Use this template*" in the top right of this page

2. Work through as much of the [basic](https://github.com/UNSW-CEEM/ceem-python-template#basic), [intermediate](https://github.com/UNSW-CEEM/ceem-python-template#intermediate) and [advanced](https://github.com/UNSW-CEEM/ceem-python-template#advanced) steps as you like.

3. Edit this README and make sure you update `your_package`, `your_name` and `licence_type`.



### References



Nothing helps as much as examples.

- [This](https://www.marwandebbiche.com/posts/python-package-tooling/) is a great guide that provides a brief overview of all the tools we use in this template.

- All of the tooling has been implemented in [`ispypsa`](https://github.com/Open-ISP/ISPyPSA)



## Usage



### Basic



#### Updating repo info



1. [Choose a license](https://choosealicense.com/), and add the `LICENSE` file to the repo

2. Update your [code of conduct](CONDUCT.md)

3. Update the [*Get Started!* section](CONTRIBUTING.md#get-started) of the [contributing guidelines](CONTRIBUTING.md)

    - Note that this currently has steps you would use to install various dependency groups that are being used by [`nemseer`](https://github.com/UNSW-CEEM/NEMSEER)

4. (Optional) [Make your software citeable](https://citation-file-format.github.io/)



#### UV



UV is used for dependency management, dependency resolution and can also be used as a 

build tool.



1. Install [`uv`](https://github.com/astral-sh/uv)

    - Edit the project info in [`pyproject.toml`](pyproject.toml), or delete it and 

      use `uv init` to start from scratch (if you are proceeding to the next few 

      sections, it is best not to delete the existig `pyproject.toml`)

    - You can add dependencies in the [`pyproject.toml`](pyproject.toml) or use the command line:

      - You can add a core dependency via `uv add`, e.g. `uv add pandas` 

      - You can add dependencies to a group (adding to a group is optional) using 

        `uv add pytest --group test`

      - You can install the dependencies from `uv.lock`, including optional groups, 

        using `uv sync --group test`

      - You can update dependencies and create a `uv.lock` file using `uv lock`

    - Run scripts with `uv run`

    - **Commit `uv.lock` to version control**



#### Testing



1. To install testing dependencies, use `uv sync` as this install dev dependencies 

   by default.

2. Put your tests in `tests/`

3. Run your tests by running `pytest` (`uv run pytest`) in the project directory

4. Test coverage will be in `tests/htmlcov/index.html` 



### Intermediate



#### Linters, Auto-formatting and `pre-commit`



Because code shouldn't look awful. We will be using `isort` (import sorting), `flake8` (python linter) and `black` (an autoformatter) via [`pre-commit`](https://pre-commit.com/).



`pre-commit` streamlines creating [pre-commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks), which are run prior to a commit being accepted by git (locally). This way, your code won't be committed if there are style issues (some of which will be automatically addressed, after which you must stage any further changes).



1. Install the required packages using `uv run pre-commit install`

2. (Optional) Configure any additional pre-commit hooks in the [YAML](.pre-commit-config.yaml)

3. To run manually, you can run `uvx ruff check --fix` and `uvx ruff format`. 

   Alternatively, these hooks will run as you try and commit changes



#### Automated testing and publishing to PyPI



Both of these can be achieved via [GitHub Actions](https://github.com/features/actions).



Note that some testing config is specified in the [`pyproject.toml`](pyproject.toml).



1. The workflow is located [here](.github/workflows/cicd.yml).

    1. Automatically runs linting and autoformatting as above

    2. If that passes, then runs your code tests across Mac and Ubuntu for a couple of Python versions

    3. If a [GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) is created based on a Git tag, it will build the package and upload to PyPI

        - To get this to work, you will need to setup your github repository as 

          trusted publisher

2. Uncomment the lines specified. This should allow the workflow to run on a push, pull-request or when manually triggered. Note that publishing to PyPI is only triggered on a release

3. Activate the workflow. Do this by navigating to the Actions tab, selecting `...` and activating it.



### Advanced



If you've made it this far, well done. Prepare for the most tricky bit: documentation



This section is a WIP. We will add to it as we come across good resources.



#### Documentation



Documentation is located in the docs folder.



This project uses:



1. [Sphinx](https://www.sphinx-doc.org/en/master/index.html) to generate documentation. Sphinx is based on reStructuredText.

    - We use several Sphinx extensions that make using Sphinx easier

      - [`autodoc`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) which will help you automatically generate the documentation from the docstrings in your code

      - [`napoleon`](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) which lets you write docstrings in your code using NumPy or Google style docstrings (as opposed to reStructuredText)

    - Sphinx is configured in [`conf.py`](docs/source/conf.py)

2. [MyST](https://myst-parser.readthedocs.io/en/latest/intro.html), a parser which optionally lets you write your documentation using Markdown. If you know Markdown, this can reduce, but not eliminate, the need for reStructuredText.

3. [readthedocs](https://readthedocs.org/) to host our documentation online. You'll need to link RtD to your repo (see [here](https://docs.readthedocs.io/en/stable/tutorial/)). Settings can be configured in the [YAML](.readthedocs.yaml)



##### Gotcha: clearing your browser cache



If you make changes to your docs, successfully build it locally (see below) or on RtD and then see that no change has been made, your browser may be caching the old version of the docs. Clear your browser cache and then try again.



##### Building locally



First, install the packages required for buildings docs using `uv sync`



You can test whether your documentation builds locally by using the commands offered by the [Makefile](./docs/Makefile). To do this, change directory to `docs` and run `make` to see build options. The easiest option is `make html`.



##### Sphinx tutorials



There is a fair bit to learn to be able to write docs. Even if you use MyST, you will need to learn about [roles and directives](https://sphinx-intro-tutorial.readthedocs.io/en/latest/sphinx_roles.html).



Here are some tutorials:

- [A tutorial prepared for PyCon 2021](https://sphinx-intro-tutorial.readthedocs.io/en/latest/index.html)

- [The official Sphinx tutorial](https://www.sphinx-doc.org/en/master/tutorial/index.html)



##### Examples



The source folder in this template repo contains basics for making docs. There is also an example of the markdown file used to generate the [API section of the `nemseer` docs](docs/source/nemseer_example.md).



 You can also refer to:

  - [nempy's docs](https://nempy.readthedocs.io/en/latest/)

  - [nemseer's docs](https://nemseer.readthedocs.io/en/latest/)



#### Tool Config



- `pytest`, `isort` and `mypy` (not included) can be configured in the [pyproject.toml](pyproject.toml)

- See relevant sections above for config for `pre-commit`, `read-the-docs` and Sphinx



## Contributing



Interested in contributing? Check out the [contributing guidelines](CONTRIBUTING.md), which also includes steps to install `your_package` for development.



Please note that this project is released with a [Code of Conduct](CONDUCT.md). By contributing to this project, you agree to abide by its terms.



## License



`your_package` was created by `your_name`. It is licensed under the terms of the `licence_type`.



## Credits



This template was created using [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/), the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter) and using Marwan Debbiche's excellent [walkthrough](https://www.marwandebbiche.com/posts/python-package-tooling/)