You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+11-12Lines changed: 11 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -55,8 +55,8 @@ examples/ # Example code demonstrating use of the project
55
55
Don't forget to configure your `.env` file with the required environment variables.
56
56
57
57
Notes:
58
-
* .env.example is provided as a template.
59
-
* .env is excluded from version control, so feel free to add secret values.
58
+
1. .env.example is provided as a template.
59
+
2. .env is excluded from version control, so feel free to add secret values.
60
60
61
61
### update dependencies and create virtual environment
62
62
@@ -117,9 +117,8 @@ uv run nox -s act
117
117
```
118
118
119
119
Notes:
120
-
121
-
- Workflow defined in `.github/workflows/*.yml`
122
-
- test-and-report.yml calls all build steps defined in noxfile.py
120
+
1. Workflow defined in `.github/workflows/*.yml`
121
+
2. test-and-report.yml calls all build steps defined in noxfile.py
123
122
124
123
### Docker
125
124
@@ -147,10 +146,10 @@ uv run nox -s update_from_template
147
146
148
147
## Pull Request Guidelines
149
148
150
-
- Before starting to write code read the [code style guide](CODE_STYLE.md) document for mandatory coding style
151
-
guidelines.
152
-
-**Pre-Commit Hooks:** We use pre-commit hooks to ensure code quality. Please install the pre-commit hooks by running `uv run pre-commit install`. This ensure all tests, linting etc. pass locally before you can commit.
153
-
-**Squash Commits:** Before submitting a pull request, please squash your commits into a single commit.
154
-
-**Branch Naming:** Use descriptive branch names like `feature/your-feature` or `fix/issue-number`.
155
-
-**Testing:** Ensure new features have appropriate test coverage.
156
-
-**Documentation:** Update documentation to reflect any changes or new features.
149
+
1. Before starting to write code read the [code style guide](CODE_STYLE.md) document for mandatory coding style
150
+
guidelines.
151
+
2.**Pre-Commit Hooks:** We use pre-commit hooks to ensure code quality. Please install the pre-commit hooks by running `uv run pre-commit install`. This ensure all tests, linting etc. pass locally before you can commit.
152
+
3.**Squash Commits:** Before submitting a pull request, please squash your commits into a single commit.
153
+
4.**Branch Naming:** Use descriptive branch names like `feature/your-feature` or `fix/issue-number`.
154
+
5.**Testing:** Ensure new features have appropriate test coverage.
155
+
6.**Documentation:** Update documentation to reflect any changes or new features.
Example project scaffolded and kept up to date with OE Python Template
47
-
(oe-python-template).
46
+
Example project scaffolded and kept up to date with OE Python Template (oe-python-template).
47
+
48
+
This [Copier](https://copier.readthedocs.io/en/stable/) template enables you to quickly generate a Python package with fully functioning build and test automation.
49
+
Projects generated from this template can be [easily updated](https://copier.readthedocs.io/en/stable/updating/) to benefit from improvements and new features of the template.
50
+
51
+
Features:
52
+
1. Package management with [uv](https://github.com/astral-sh/uv)
53
+
2. Code formatting with [Ruff](https://github.com/astral-sh/ruff)
54
+
3. Linting with [Ruff](https://github.com/astral-sh/ruff)
55
+
4. Static type checking with [mypy](https://mypy.readthedocs.io/en/stable/)
56
+
5. Complete set of [pre-commit](https://pre-commit.com/) hooks including [detect-secrets](https://github.com/Yelp/detect-secrets) and [pygrep](https://github.com/pre-commit/pygrep-hooks)
57
+
6. Unit and E2E testing with [pytest](https://docs.pytest.org/en/stable/) including parallel test execution
58
+
7. Matrix testing in multiple environments with [nox](https://nox.thea.codes/en/stable/)
59
+
8. Test coverage reported with [Codecov](https://codecov.io/) and published as release artifact
60
+
9. CI/CD pipeline automated with [GitHub Actions](https://github.com/features/actions)
61
+
10. CI/CD pipeline can be run locally with [act](https://github.com/nektos/act)
62
+
11. Code quality and security checks with [SonarQube](https://www.sonarsource.com/products/sonarcloud) and [GitHub CodeQL](https://codeql.github.com/)
63
+
12. Dependency monitoring with [pip-audit](https://pypi.org/project/pip-audit/), [Renovate](https://github.com/renovatebot/renovate), and [GitHub Dependabot](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide)
64
+
13. Licenses of dependencies extracted with [pip-licenses](https://pypi.org/project/pip-licenses/) and published as release artifacts in CSV and JSON format for compliance checks
65
+
14. Software Bill of Materials (SBOM) generated with [cyclonedx-python](https://github.com/CycloneDX/cyclonedx-python) and published as release artifact
66
+
15. Version and release management with [bump-my-version](https://callowayproject.github.io/bump-my-version/)
67
+
16. Changelog and release notes generated with [git-cliff](https://git-cliff.org/)
68
+
17. Documentation generated with [Sphinx](https://www.sphinx-doc.org/en/master/) including reference documentation and PDF export
69
+
18. Documentation published to [Read The Docs](https://readthedocs.org/)
70
+
19. Interactive OpenAPI specification with [Swagger](https://swagger.io/)
71
+
20. Python package published to [PyPI](https://pypi.org/)
72
+
21. Docker images published to [Docker.io](https://hub.docker.com/) and [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) with [artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds)
73
+
22. One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
74
+
23. Settings for use with [VSCode](https://code.visualstudio.com/)
75
+
24. Settings and custom instructions for use with [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
76
+
77
+
The generated project includes code, documentation and configuration of a fully functioning demo-application and service, which can be used as a starting point for your own project.
78
+
1. Service architecture suitable for use as shared library
79
+
2. Validation with [pydantic](https://docs.pydantic.dev/)
80
+
3. Command-line interface (CLI) with [Typer](https://typer.tiangolo.com/)
81
+
4. Versioned Web API with [FastAPI](https://fastapi.tiangolo.com/)
82
+
5.[Interactive Jupyter notebook](https://jupyter.org/) and [reactive Marimo notebook](https://marimo.io/)
83
+
6. Simple Web UI with [Streamlit](https://streamlit.io/)
84
+
7. Configuration to run the CLI and API in a Docker container including setup for [Docker Compose](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-docker-compose/)
85
+
8. Documentation including badges, setup instructions, contribution guide and security policy
86
+
87
+
Explore [here](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example) for what's generated out of the box.
88
+
89
+
## Generate a new project
90
+
91
+
This template is designed to be used with the [copier](https://copier.readthedocs.io/en/stable/) project generator. It allows you to create a new project based on this template and customize it according to your needs.
92
+
To generate a new project, follow these steps:
93
+
94
+
**Step 1**: Install uv package manager and copier. Copy the following code into your terminal and execute it.
95
+
```shell
96
+
if [[ "$OSTYPE"=="darwin"* ]];then# Install dependencies for macOS X
97
+
if!command -v brew &> /dev/null;then## Install Homebrew if not present
if!command -v uvx &> /dev/null;then# Install uv package manager if not present
104
+
curl -LsSf https://astral.sh/uv/install.sh | sh
105
+
source$HOME/.local/bin/env
106
+
fi
107
+
uv tool install copier # Install copier as global tool
108
+
```
109
+
110
+
**Step 2**: [Create an empty repository on GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository), clone to your local machine, and change into it's directory.
**Step 4**: Perform initial commit and push. Copy the following code into your terminal and execute it.
118
+
```shell
119
+
git add .
120
+
git commit -m "feat: Initial commit"
121
+
git push
122
+
```
123
+
124
+
Visit your GitHub repository and check the Actions tab. The CI workflow should already be running! The workflow will fail at the SonarQube step, as this external service is not yet configured for our new repository.
48
125
49
-
Use Cases:
126
+
**Step 5**: Follow the [instructions](SERVICE_CONNECTIONS.md) to wire up
127
+
external services such as CloudCov, SonarQube Cloud, Read The Docs, Docker.io, and Streamlit Community Cloud.
50
128
51
-
1. Dummy CLI application and service demonstrating example usage of the
52
-
directory structure and build pipeline generated by oe-python-template
129
+
**Step 6**: Release the first versions
130
+
```shell
131
+
./n bump
132
+
```
133
+
Notes:
134
+
1. You can remove this section post having successfully generated your project.
135
+
2. The following sections refer to the dummy application and service provided by this template.
136
+
Use them as inspiration and adapt them to your own project.
53
137
54
138
## Overview
55
139
56
-
Adding OE Python Template Example to your project as a dependency is easy.
140
+
Adding OE Python Template Example to your project as a dependency is easy. See below for usage examples.
57
141
58
142
```shell
59
143
uv add oe-python-template-example # add dependency to your project
If you still prefer pip over the modern and fast package manager
65
-
[uv](https://github.com/astral-sh/uv), you can install the library like this:
146
+
If you don't have uv installed follow [these instructions](https://docs.astral.sh/uv/getting-started/installation/). If you still prefer pip over the modern and fast package manager [uv](https://github.com/astral-sh/uv), you can install the library like this:
147
+
66
148
67
149
```shell
68
150
pip install oe-python-template-example # add dependency to your project
69
151
```
70
152
71
-
Executing the command line interface (CLI) in an isolated Python environment is
72
-
just as easy:
153
+
Executing the command line interface (CLI) in an isolated Python environment is just as easy:
73
154
74
155
```shell
75
-
uvx oe-python-template-example hello-world # prints "Hello, world! [..]"
76
-
uvx oe-python-template-example serve # serves webservice API
77
-
uvx oe-python-template-example serve --port=4711 # serves webservice API on port 4711
156
+
uvx oe-python-template-example hello-world # prints "Hello, world! [..]"
157
+
uvx oe-python-template-example serve # serves web API
158
+
uvx oe-python-template-example serve --port=4711 # serves web API on port 4711
78
159
```
79
160
80
161
Notes:
162
+
1. The API is versioned, mounted at `/api/v1` resp. `/api/v2`
163
+
2. While serving the web API go to [http://127.0.0.1:8000/api/v1/hello-world](http://127.0.0.1:8000/api/v1/hello-world) to see the respons of the `hello-world` operation.
164
+
3. Interactive documentation is provided at [http://127.0.0.1:8000/api/docs](http://127.0.0.1:8000/api/docs)
81
165
82
-
- The API is versioned, mounted at `/api/v1` resp. `/api/v2`
This project is designed with operational excellence in mind, using modern Python tooling and practices. It includes:
181
+
182
+
1. Various examples demonstrating usage:
183
+
a. [Simple Python script](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/blob/main/examples/script.py)
184
+
b. [Streamlit web application](https://oe-python-template-example.streamlit.app/) deployed on [Streamlit Community Cloud](https://streamlit.io/cloud)
185
+
c. [Jupyter](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/blob/main/examples/notebook.ipynb) and [Marimo](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/blob/main/examples/notebook.py) notebook
186
+
2.[Complete reference documentation](https://oe-python-template-example.readthedocs.io/en/latest/reference.html) on Read the Docs
187
+
3.[Transparent test coverage](https://app.codecov.io/gh/helmut-hoffer-von-ankershoffen/oe-python-template-example) including unit and E2E tests (reported on Codecov)
188
+
4. Matrix tested with [multiple python versions](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/blob/main/noxfile.py) to ensure compatibility (powered by [Nox](https://nox.thea.codes/en/stable/))
189
+
5. Compliant with modern linting and formatting standards (powered by [Ruff](https://github.com/astral-sh/ruff))
190
+
6. Up-to-date dependencies (monitored by [Renovate](https://github.com/renovatebot/renovate) and [Dependabot](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/security/dependabot))
191
+
7.[A-grade code quality](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template-example) in security, maintainability, and reliability with low technical debt and codesmell (verified by SonarQube)
192
+
8. Additional code security checks using [CodeQL](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/security/code-scanning)
193
+
9.[Security Policy](SECURITY.md)
194
+
10.[License](LICENSE) compliant with the Open Source Initiative (OSI)
195
+
11. 1-liner for installation and execution of command line interface (CLI) via [uv(x)](https://github.com/astral-sh/uv) or [Docker](https://hub.docker.com/r/helmuthva/oe-python-template-example/tags)
196
+
12. Setup for developing inside a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) included (supports VSCode and GitHub Codespaces)
197
+
137
198
138
199
## Usage Examples
139
200
140
-
The following examples run from source. Clone this repository first using
201
+
The following examples run from source - clone this repository using
0 commit comments