Skip to content

Commit

Permalink
docs: update readme to reflect changes and to prepare v1 release
Browse files Browse the repository at this point in the history
  • Loading branch information
MultifokalHirn committed Nov 15, 2023
1 parent c9c0276 commit 795f791
Show file tree
Hide file tree
Showing 4 changed files with 159 additions and 85 deletions.
88 changes: 88 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
---
name: Tox

on:
# push:
# branches: ["main"]
# pull_request:
# branches: ["main"]
# paths-ignore:
# - "docs/**"
# - "mypyc/doc/**"
# - "**/*.rst"
# - "**/*.md"
# - .gitignore
# - CREDITS
# - LICENSE
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: true

jobs:
build:
runs-on: ubuntu-latest
strategy:
max-parallel: 1
fail-fast: true
matrix:
include:
- name: Test suite with py38-ubuntu
python: "3.8"
arch: x64
os: ubuntu-latest
toxenv: py
tox_extra_args: "-n 2"
- name: Test suite with py39-ubuntu
python: "3.9"
arch: x64
os: ubuntu-latest
toxenv: py
tox_extra_args: "-n 2"
- name: Test suite with py310-ubuntu
python: "3.10"
arch: x64
os: ubuntu-latest
toxenv: py
tox_extra_args: "-n 2"
- name: Test suite with py311-ubuntu
python: "3.11"
arch: x64
os: ubuntu-latest
toxenv: py
tox_extra_args: "-n 2"
- name: Test suite with py312-ubuntu
python: "3.12"
arch: x64
os: ubuntu-latest
toxenv: py
tox_extra_args: "-n 2"
name: ${{ matrix.name }}
env:
TOX_SKIP_MISSING_INTERPRETERS: False
# Rich (pip)
FORCE_COLOR: 1
# Tox
PY_COLORS: 1
# Mypy (see https://github.com/python/mypy/issues/7771)
TERM: xterm-color
MYPY_FORCE_COLOR: 1
MYPY_FORCE_TERMINAL_WIDTH: 200
# Pytest
PYTEST_ADDOPTS: --color=yes
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python }}
architecture: ${{ matrix.arch }}
- name: Install tox
run: pip install setuptools==68.2.2 tox==4.11.0
- name: Setup tox environment
run: tox run -e ${{ matrix.toxenv }} --notest
- name: Test
run: tox run -e ${{ matrix.toxenv }} --skip-pkg-install -- ${{ matrix.tox_extra_args }}
2 changes: 1 addition & 1 deletion .github/workflows/python-checks.yaml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
name: Test
name: All Checks

on:
push:
Expand Down
138 changes: 59 additions & 79 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,100 +1,94 @@
[![Github Actions](https://github.com/MultifokalHirn/python_template_repo/workflows/Tests/badge.svg)](https://github.com/MultifokalHirn/python_template_repo/actions)
[![Tests](https://github.com/MultifokalHirn/python_template_repo/actions/workflows/python-checks.yaml/badge.svg?branch=main)](https://github.com/MultifokalHirn/python_template_repo/actions/workflows/python-checks.yaml)
![GitHub last commit](https://img.shields.io/github/last-commit/MultifokalHirn/python_template_repo)
![GitHub issues](https://img.shields.io/github/issues/MultifokalHirn/python_template_repo)
![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/MultifokalHirn/python_template_repo)

<div align="center">
<p style="font-size:22px"> 🏗️ This project is currently under construction 🏗️ </p>
<br>
</div>

<!-- omit in toc -->

# Python Project Template
>
> Check out the [Roadmap](#roadmap) for planned features

This is my personal template for a python project containing everything needed to start developing.
This is [my](https://github.com/MultifokalHirn) personal template for a python project containing everything needed to start developing.

## Features

<!-- ![constr](https://img.shields.io/badge/🏗️-under%20construction-FFD43B) -->
**Great Base Setup for Python Development**

### Python Development

![py3](https://img.shields.io/badge/-python>=3.8.1-3776AB?logo=python&logoColor=FFFFFF&style=flat-square)
![py3](https://img.shields.io/badge/python->=3.8.1%20<=3.12.0-3776AB?logo=python&logoColor=FFFFFF&style=flat-square)
![pdm](https://img.shields.io/badge/depedency_manager-pdm-blueviolet?logoColor=FFFFFF&style=flat-square)
![pytest](https://img.shields.io/badge/testing-pytest-0A9EDC?logo=pytest&logoColor=FFFFFF&style=flat-square)
![pytest](https://img.shields.io/badge/test%20suite-pytest-0A9EDC?logo=pytest&logoColor=FFFFFF&style=flat-square)
![ruff](https://img.shields.io/badge/linter-ruff-006400?&style=flat-square)
![mypy](https://img.shields.io/badge/typechecker-mypy-blue?&style=flat-square)
![flake8](https://img.shields.io/badge/linter-flake8-006400?&style=flat-square)
![isort](https://img.shields.io/badge/autofix-isort-yellow?&style=flat-square)
<!-- ![isort](https://img.shields.io/badge/isort-blue?&style=flat-square) -->

<!-- ![mypy](https://img.shields.io/badge/mypy-checked-blue?&style=flat-square)
[![mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/) -->

<!-- - `pdm` for dependency management
- packages for:
- linting and static analysis with `flake8` and `mypy`
- auto-fixing with `autopep8` and `isort`
- `pytest` for testing -->
- Code base skeleton with [`src/`](./src/) and [`tests/`](./tests/) folders

### CI, CD, and Dev Tooling
**Development and CI tools already Set Up**

![make](https://img.shields.io/badge/Makefile-FFFFFF?logo=gnu&logoColor=A42E2B&style=flat-square)
![docker](https://img.shields.io/badge/-Docker-FFFFFF?logo=docker&style=flat-square)
![ghactions](https://img.shields.io/badge/Github_Actions-FFFFFF?logo=githubactions&style=flat-square)
![conventionalcommits](https://img.shields.io/badge/Conventional%20Commits-FFFFFF?logo=conventionalcommits&style=flat-square)
<!-- ![docker](https://img.shields.io/badge/-Docker-FFFFFF?logo=docker&style=flat-square) -->
<!-- [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=flat-square)](https://github.com/pre-commit/pre-commit&style=flat-square) -->
<!-- [![conventional-commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg&style=flat-square)](https://conventionalcommits.org&style=flat-square) -->

### Sensible Configuration
<!--
- [`pyenv`](./.python-version)-->

<!-- [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) -->

<!-- - `semantic-release` for automated versioning and changelog generation -->
<!-- - `commitizen` for version control and changelog generation -->

<!-- omit in toc
## Table of Contents
-->

**Sensible Configuration out of the Box**

![pyproject](https://img.shields.io/badge/pyproject.toml-000000?logo=python&style=flat-square)
![precommit](https://img.shields.io/badge/.pre--commit--config.yaml-000000?logo=precommit&style=flat-square)
![editorconfig](https://img.shields.io/badge/-.editorconfig-000000?logo=editorconfig&style=flat-square)
![visualstudiocode](https://img.shields.io/badge/-.vscode/-000000?logo=visualstudiocode&logoColor=007ACC&style=flat-square)
![templates](https://img.shields.io/badge/Templates-000000?logo=github&logoColor=FFFFFF&style=flat-square)

<!-- - [`Makefile`](./Makefile) for easy setup, testing, linting, etc.
- docker-compose for easy setup of dev environment
- Configuration for
- python packages in [`pyproject.toml`](./pyproject.toml) and [`setup.cfg`](./setup.cfg)
- VSCode in [`.vscode/`](./.vscode)
- `pre-commit` hooks in [`.pre-commit-config.yaml`](./.pre-commit-config.yaml)
- [`pyenv`](./.python-version)
- Templates for [Issues](./.github/ISSUE_TEMPLATE.md) and [PRs](./.github/PULL_REQUEST_TEMPLATE.md) on GitHub
- and more... -->
## Getting Started

<!-- [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) -->
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for information on how to setup and contribute to this project.

<!-- - GitHub Actions for
- linting & testing -->
<!-- - `semantic-release` for automated versioning and changelog generation -->
<!-- - `commitizen` for version control and changelog generation -->
### Quickstart

<!-- omit in toc
## Table of Contents
-->
``` bash
git clone https://github.com/MultifokalHirn/python_template_repo.git
cd python_template_repo/

make bootstrap # sets up dev environment and installs dependencies
make dev # sets up dev environment and installs dependencies
make ci # runs auto-fixes, linters and tests
make run # starts the application
```

## Roadmap

### v1 Release

- [x] [`Makefile`](./Makefile) for easy setup, testing, linting, etc.
- [x] set up github actions for testing and linting
- [ ] set up github actions for semantic versioning
- [x] Configuration for python packages in [`pyproject.toml`](./pyproject.toml) and [`setup.cfg`](./setup.cfg)
- [x] Configuration for VSCode in [`.vscode/`](./.vscode)
- [x] Configuration for `pre-commit` hooks in [`.pre-commit-config.yaml`](./.pre-commit-config.yaml)
- [x] Templates for [Issues](./.github/ISSUE_TEMPLATE.md) and [PRs](./.github/PULL_REQUEST_TEMPLATE.md) on GitHub
- [ ] set up dependabot
- [ ] set up commitizen
- [ ] set up Dockerfile and docker-compose
- [ ] set up devcontainer
- [ ] set up coverage reporting
- [ ] set up semantic-release

### Demo Project

- [ ] create demo project to showcase best practices and features

### Ideas for v2 Release

- [ ] set up tox for testing with multiple python versions
- [ ] set up Dockerfile
- [ ] docker-compose for easy setup of dev environment
- [ ] set up devcontainer
- [ ] set up commitizen
- [ ] set up coverage reporting
- [ ] set up semantic-release
- [ ] set up github actions for semantic versioning

### Improve Documentation

- [ ] document project structure
Expand All @@ -104,23 +98,6 @@ This is my personal template for a python project containing everything needed t
### Ideas for the Future

- [ ] find out how to sync templates with projects that use them?
- [ ] check out tools like tox & nox
- [ ] check out pylint

## Getting Started

See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for information on how to setup and contribute to this project.

### Quickstart

``` bash
git clone https://github.com/MultifokalHirn/python_template_repo.git
cd python_template_repo/

make install # sets up dev environment and installs dependencies
make ci # runs auto-fixes, linters and tests
make run # starts the application
```

## "Why don't you use X?"

Expand All @@ -132,16 +109,19 @@ If you have any suggestions for improvements, or tools to check out, please [fil

### Tried and Decided Against

- `poetry`
- `black`
- ...
- `poetry` - using `pdm` instead because of bad experience with `poetry`
- `flake8` - replaced by `ruff``
- `autopep8` - replaced by `ruff``
- `isort` - replaced by `ruff``
- `black` - I like configuring stuff

### Currently Testing

- `tox` - `nox` seems to be more popular, but `tox` seems to be more mature

### Want to try

- `pylint`
- `tox`
- `nox`
- ....
- tba

## Troubleshooting

Expand Down
16 changes: 11 additions & 5 deletions tox.ini
Original file line number Diff line number Diff line change
@@ -1,24 +1,31 @@
[tox]
min_version = 4.0
envlist =
; py38,
py38,
; py39,
; py310,
py311,
py312,
isolated_build = true
; dependencies:
; override:
; - pip install tox tox-pyenv
; - pyenv install --skip-existing 3.8.16 3.10.9 3.11.6 3.12.0
; - pyenv local 3.12.0

[testenv]
; groups = ; Dependency groups in pyproject.toml
; base
; test
; test
; deps = ; Additional dependencies, it will be installed into the library path via normal pip method
; flake8

deps =
-rrequirements.txt
-rrequirements-dev.txt
commands =
pytest tests/
python3 -m ruff check src/ tests/ --config-file=pyproject.toml
python3 -m pytest tests/

[testenv:type]
description = type check ourselves
Expand All @@ -27,5 +34,4 @@ passenv =
MYPY_FORCE_COLOR
MYPY_FORCE_TERMINAL_WIDTH
commands =
python runtests.py self
python -m mypy --config-file pyproject.toml src/ tests/
python3 -m mypy --config-file=pyproject.toml src/ tests/

0 comments on commit 795f791

Please sign in to comment.