Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/larsrollik/templatepy

Template repository for python packages
https://github.com/larsrollik/templatepy

build-system bumpversion community linting package pre-commit pypi python template zenodo zenodo-upload

Last synced: 3 months ago
JSON representation

Template repository for python packages

Host: GitHub
URL: https://github.com/larsrollik/templatepy
Owner: larsrollik
License: bsd-3-clause
Created: 2021-05-24T20:01:57.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2024-02-23T13:59:32.000Z (11 months ago)
Last Synced: 2024-04-25T13:40:43.365Z (9 months ago)
Topics: build-system, bumpversion, community, linting, package, pre-commit, pypi, python, template, zenodo, zenodo-upload
Language: Python
Homepage:
Size: 75.2 KB
Stars: 4
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        [//]: # (Links)

[Github-flavored markdown]: https://github.github.com/gfm

[manifest]: https://packaging.python.org/en/latest/guides/using-manifest-in

[packaging]: https://packaging.python.org/en/latest/tutorials/packaging-projects

[setup.cfg]: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html

[bump2version]: (https://github.com/c4urself/bump2version

[pre-commit]: https://pre-commit.com

[black]: https://github.com/psf/black

[pypi]: pypi.org

[test.pypi]: test.pypi.org

[Zenodo]: https://zenodo.org

[contribution guidelines]: https://github.com/larsrollik/templatepy/blob/main/CONTRIBUTING.md

[issues]: https://github.com/larsrollik/templatepy/issues

[BSD 3-Clause License]: https://github.com/larsrollik/templatepy/blob/main/LICENSE

[Github]: https://github.com/larsrollik/templatepy/settings/secrets/actions/new

[release]: https://github.com/larsrollik/templatepy/releases/new

[//]: # (Badges)

[![Contributions](https://img.shields.io/badge/Contributions-Welcome-brightgreen.svg)](https://github.com/larsrollik/templatepy/blob/main/CONTRIBUTING.md)

[![DOI](https://zenodo.org/badge/370470893.svg)](https://zenodo.org/badge/latestdoi/370470893)

[![Website](https://img.shields.io/website?up_message=online&url=https%3A%2F%2Fgithub.com/larsrollik/templatepy)](https://github.com/larsrollik/templatepy)

[![PyPI](https://img.shields.io/pypi/v/templatepy.svg)](https://pypi.org/project/templatepy)

[![Wheel](https://img.shields.io/pypi/wheel/templatepy.svg)](https://pypi.org/project/templatepy)

![CI](https://github.com/larsrollik/templatepy/workflows/tests/badge.svg)

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)

[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)

# templatepy

Template repo for python repositories & PyPi integration

---

**Version: "0.0.3"**

## Usage

1. **Change** files according to overview in `TODO` below

2. **Develop** package...

3. **Install** package:

   - static/normal install: `pip install .`

   - editable install:`pip install -e .`

   - dev install: `pip install -e .[dev]` (some terminals require to escape brackets with ` \ ` as `\[`, esp. zsh)

## File overview

#### General

- `LICENSE`: license text

- `README.md`: [Github-flavored markdown] file

- `templatepy`: placeholder folder for any python package that is configured for install via `setup.cfg` and `pyproject.toml`

  - `__init__.py`: contains basic package info and example function that is called by console entrypoint (see `setup.cfg`)

  - `example.data.file.config`: a file to demonstrate that data files are included based on `setup.cfg` criteria

  - `example.data.file.test-extension-yu48`: a file to demonstrate data exclusion via `setup.py`

#### Testing

- `tests`: placeholder folder for unit/integration tests and associated data

- `pytest.ini`: config for testing framework with `pytest` and `coverage` plugin (`pytest-cov`)

#### Packaging system (see: [packaging] and [setup.cfg])

  - `MANIFEST.in`: [manifest] file describes included/excluded files for build

  - `pyproject.toml`:

    - specifies build system: this replaces the usual `setup.py` architecture for setuptools

    - config for [black] code formatter

  - `setup.cfg`:

    - package specification and install dependencies

    - config for `flake8` formatting (see pre-commit)

  - `setup.py`: legacy file (see notes on new build-system below)

#### Code maintenance (linting/formatting/github)

- `.pre-commit-config.yaml`: use [pre-commit] to run code formatting (e.g. with [black] and `flake8`) and PEP compliance checks

  - Install pre-commit hook with `pre-commit install` (Note: only installs it in the current virtual environment)

  - Run it manually with `pre-commit run --all` or leave it to run on commit (requires to re-stage changed files!)

- `.github`: folder that contains github automation workflows and issues templates

- `.gitignore`: ignored files/folders in git tools

- `.bumpversion.cfg`:  config for [bump2version]

## TODO for **adapting** template to new project

- [ ] Change package name:

  - (1) `templatepy` folder

  - (2) README.md

  - (3) `name` argument in `setup.cfg`

  - (4) `.github/workflows` files

  - (5) `setup.cfg`: `[bumpversion:file:templatepy/__init__.py]`

- [ ] Change details about project author, etc. in `setup.cfg`, `README.md`, and `templatepy/__init__.py`

- [ ] Change license holder in `LICENSE`

- [ ] Change `README` badge paths at top

- [ ] Verify inclusions/exclusions of installable files/folders in `MANIFEST.in` and `setup.cfg`

- [ ] Check `.gitignore` contains relevant criteria

- [ ] Add all version string locations to `setup.cfg`/bump2version field.

  - Use same syntax as for `[bumpversion:file:PACKAGEFOLDER/__init__.py]` line to describe how to find version on version increment

- [ ] To upload to [pypi]: see below for workflow

- [ ] To upload to [Zenodo] if repo is a publication:

  - (1) Connect Zenodo to Github account

  - (2) Flip switch on zenodo view of repo - **NOTE**: Zenodo can only copy from **public** repos

  - (3) Create new release version of github repo (manual or via `.github/workflows/CI.yaml`)

  - (4) Wait! Zenodo view with DOI assignment should update within about a minute

  - (5) Add DOI badge to `README` file

## Workflow for (automatically) uploading package to [pypi] or [test.pypi]

- (1) On [pypi], make new API key for repo or general

- (2) On [Github], in repository settings add a new **actions secret** named `TWINE_API_KEY` and copy in the pypi API key

- (3) Create a new [release] manually on github or by triggering the github workflow with a version without release extension (e.g. `x.y.z`)

## Notes

#### New(er) build system with `pyproject.toml` and `setup.cfg`

- `pip`

  - tested with `pip install .  --use-feature=in-tree-build` for forward-compatibility with `pip 21.3`

  - keeping empty `setup.py` for enabling install in editable mode `-e` as this still requires such a file

  - added `wheel` as build-system dependency for compatibility with pip that does not implement `PEP 517`

- `setup.cfg`/`setup.py` might be fully replaced with `pyproject.toml`. 

[See this discussion](https://stackoverflow.com/questions/44878600/is-setup-cfg-deprecated) about 

[PEP-426](https://peps.python.org/pep-0426/), 

[PEP-517](https://peps.python.org/pep-0517), 

[PEP-518](https://peps.python.org/pep-0518)

## Contributing

Contributions are very welcome!

Please see the [contribution guidelines] or check out the [issues]

## License

This software is released under the **[BSD 3-Clause License]**