oe-python-template-example 0.5.0__tar.gz → 0.5.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/PKG-INFO +11 -119
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/README.md +10 -118
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/pyproject.toml +2 -2
- oe_python_template_example-0.5.2/src/oe_python_template_example/system/_gui.py +26 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/system/_service.py +7 -3
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_gui.py +1 -1
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_process.py +2 -1
- oe_python_template_example-0.5.0/src/oe_python_template_example/system/_gui.py +0 -20
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/.gitignore +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/LICENSE +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/__init__.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/api.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/cli.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/constants.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/hello/__init__.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/hello/_api.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/hello/_cli.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/hello/_constants.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/hello/_gui.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/hello/_models.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/hello/_service.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/hello/_settings.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/system/__init__.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/system/_api.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/system/_cli.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/system/_settings.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/.vendored/bottle.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/__init__.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_api.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_cli.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_console.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_constants.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_di.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_health.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_log.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_logfire.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_notebook.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_sentry.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_service.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/_settings.py +0 -0
- {oe_python_template_example-0.5.0 → oe_python_template_example-0.5.2}/src/oe_python_template_example/utils/boot.py +0 -0
@@ -1,6 +1,6 @@
|
|
1
1
|
Metadata-Version: 2.4
|
2
2
|
Name: oe-python-template-example
|
3
|
-
Version: 0.5.
|
3
|
+
Version: 0.5.2
|
4
4
|
Summary: 🧠 Example project scaffolded and kept up to date with OE Python Template (oe-python-template).
|
5
5
|
Project-URL: Homepage, https://oe-python-template-example.readthedocs.io/en/latest/
|
6
6
|
Project-URL: Documentation, https://oe-python-template-example.readthedocs.io/en/latest/
|
@@ -119,137 +119,29 @@ Description-Content-Type: text/markdown
|
|
119
119
|
---
|
120
120
|
|
121
121
|
|
122
|
-
Example project scaffolded and kept up to date with OE Python Template
|
123
|
-
|
124
|
-
### Scaffolding
|
125
|
-
|
126
|
-
This [Copier](https://copier.readthedocs.io/en/stable/) template enables you to quickly generate (scaffold) a Python package with fully functioning build and test automation:
|
127
|
-
|
128
|
-
1. 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.
|
129
|
-
2. During project generation, you can flexibly configure naming of the Python distribution, import package, main author, GitHub repository, organization, and many other aspects to match your specific requirements (see [copier.yml](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/copier.yml) for all available options).
|
130
|
-
|
131
|
-
### Development Infrastructure
|
132
|
-
|
133
|
-
Projects generated with this template come with a comprehensive development toolchain and quality assurance framework that supports the entire software development lifecycle - from coding and testing to documentation, release management, and compliance auditing. This infrastructure automates routine tasks, enforces code quality standards, and streamlines the path to production:
|
134
|
-
|
135
|
-
1. Linting with [Ruff](https://github.com/astral-sh/ruff)
|
136
|
-
2. Static type checking with [mypy](https://mypy.readthedocs.io/en/stable/)
|
137
|
-
3. 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)
|
138
|
-
4. Unit and E2E testing with [pytest](https://docs.pytest.org/en/stable/) including parallel test execution
|
139
|
-
5. Matrix testing in multiple environments with [nox](https://nox.thea.codes/en/stable/)
|
140
|
-
6. Test coverage reported with [Codecov](https://codecov.io/) and published as release artifact
|
141
|
-
7. CI/CD pipeline automated with [GitHub Actions](https://github.com/features/actions) with parallel and reusable workflows, including scheduled testing, release automation, and multiple reporting channels and formats
|
142
|
-
8. CI/CD pipeline can be run locally with [act](https://github.com/nektos/act)
|
143
|
-
9. Code quality and security checks with [SonarQube](https://www.sonarsource.com/products/sonarcloud) and [GitHub CodeQL](https://codeql.github.com/)
|
144
|
-
10. Dependency monitoring and vulnerability scanning with [pip-audit](https://pypi.org/project/pip-audit/), [trivy](https://trivy.dev/latest/), [Renovate](https://github.com/renovatebot/renovate), and [GitHub Dependabot](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide)
|
145
|
-
11. Error monitoring and profiling with [Sentry](https://sentry.io/) (optional)
|
146
|
-
12. Logging and metrics with [Logfire](https://logfire.dev/) (optional)
|
147
|
-
13. Prepared for uptime monitoring and scheduled tests with [betterstack](https://betterstack.com/) or alternatives
|
148
|
-
14. Licenses of dependencies extracted with [pip-licenses](https://pypi.org/project/pip-licenses/), matched with allow list, and published as release artifacts in CSV and JSON format for further compliance checks
|
149
|
-
15. Generation of attributions from extracted licenses
|
150
|
-
16. Software Bill of Materials (SBOM) generated in [CycloneDX](https://cyclonedx.org/) and [SPDX](https://spdx.dev/) formats with [cyclonedx-python](https://github.com/CycloneDX/cyclonedx-python) resp. [trivy](https://trivy.dev/latest/), published as release artifacts
|
151
|
-
17. Version and release management with [bump-my-version](https://callowayproject.github.io/bump-my-version/)
|
152
|
-
18. Changelog and release notes generated with [git-cliff](https://git-cliff.org/)
|
153
|
-
19. Documentation generated with [Sphinx](https://www.sphinx-doc.org/en/master/) including reference documentation for the library, CLI, and API
|
154
|
-
20. Documentation published to [Read The Docs](https://readthedocs.org/) including generation of PDF and single page HTML versions
|
155
|
-
21. Documentation including dynamic badges, setup instructions, contribution guide and security policy
|
156
|
-
22. Interactive OpenAPI specification with [Swagger](https://swagger.io/)
|
157
|
-
23. Python package published to [PyPI](https://pypi.org/)
|
158
|
-
24. Multi-stage build of fat (all extras) and slim (no extras) multi-arch (arm64 and amd64) Docker images, running non-root within immutable container
|
159
|
-
25. 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)
|
160
|
-
26. One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
|
161
|
-
27. Settings for use with [VSCode](https://code.visualstudio.com/)
|
162
|
-
28. Settings and custom instructions for use with [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
|
163
|
-
29. API deployed as serverless function to [Vercel](https://vercel.com/) (optional)
|
164
|
-
|
165
|
-
### Multi-head Application Features
|
166
|
-
|
167
|
-
Beyond development tooling, projects generated with this template include the code, documentation, and configuration of a fully functioning service and multi-head application. This reference implementation serves as a starting point for your own business logic with modern patterns and enterprise practices already in place:
|
168
|
-
|
169
|
-
1. Usable as library with "Hello" module exposing a simple service that can say "Hello, world!" and echo utterances.
|
170
|
-
2. Comfortable command-line interface (CLI) with [Typer](https://typer.tiangolo.com/)
|
171
|
-
3. Versioned webservice API with [FastAPI](https://fastapi.tiangolo.com/)
|
172
|
-
4. Cross-platform Graphical User Interface (GUI) with
|
173
|
-
[NiceGUI](https://nicegui.io/) running in a browser or native window
|
174
|
-
5. [Interactive Jupyter notebook](https://jupyter.org/) and [reactive Marimo notebook](https://marimo.io/)
|
175
|
-
6. Simple Web UI with [Streamlit](https://streamlit.io/)
|
176
|
-
7. Modular architecture auto-discovers and registers services, CLI commands, API routes and GUI pages exposed by domain modules
|
177
|
-
8. Validation and settings management with [pydantic](https://docs.pydantic.dev/)
|
178
|
-
9. System module providing aggregate health and info to the runtime, compiled settings, and further info provided by domain modules
|
179
|
-
10. Health and Info available via command, webservice API (info passsword protected) and GUI
|
180
|
-
11. Flexible logging and instrumentation, including support for [Sentry](https://sentry.io/) and [Logfire](https://logfire.dev/)
|
181
|
-
12. Hello service demonstrates use of custom real time metrics collected via Logfire
|
182
|
-
13. 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/)
|
183
|
-
|
184
|
-
Explore [here](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example) for what's generated out of the box. While this template comes with multiple application interfaces ("heads") - Library, CLI, API, GUI, notebooks, and Streamlit; running native and within Docker - they're included to demonstrate capabilities and provide implementation patterns. You're expected to use this as a foundation, keeping only the interfaces relevant to your project's requirements. The modular architecture makes it easy to:
|
185
|
-
|
186
|
-
1. Remove unnecessary interfaces to simplify your codebase
|
187
|
-
2. Adapt existing interfaces to your specific use cases
|
188
|
-
3. Focus on your core business logic without reimplementing infrastructure
|
189
|
-
4. Add new interfaces while leveraging the existing patterns
|
190
|
-
|
191
|
-
|
192
|
-
## Generate a new project
|
193
|
-
|
194
|
-
To generate, build and release a fully functioning project in a few minutes, follow these 5 steps:
|
195
|
-
|
196
|
-
**Step 1**: Execute the following command to install or update tooling.
|
197
|
-
```shell
|
198
|
-
# Install Homebrew, uv package manager, copier and further dev tools
|
199
|
-
curl -LsSf https://raw.githubusercontent.com/helmut-hoffer-von-ankershoffen/oe-python-template/HEAD/install.sh | sh
|
200
|
-
```
|
201
|
-
|
202
|
-
**Step 2**: [Create a 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.
|
203
|
-
|
204
|
-
**Step 3**: Execute the following command to generate a new project based on this template.
|
205
|
-
```shell
|
206
|
-
# Ensure to stand in your freshly created git repository before executing this command
|
207
|
-
copier copy --trust gh:helmut-hoffer-von-ankershoffen/oe-python-template .
|
208
|
-
```
|
209
|
-
|
210
|
-
**Step 4**: Execute the following commands to push your initial commit to GitHub.
|
211
|
-
```shell
|
212
|
-
git add .
|
213
|
-
git commit -m "chore: Initial commit"
|
214
|
-
git push
|
215
|
-
```
|
216
|
-
|
217
|
-
Check the [Actions tab](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/actions) of your GitHub repository: The CI/CD workflow of your project is already running!
|
218
|
-
|
219
|
-
The workflow will fail at the SonarQube step, as this external service is not yet configured for our new repository. We will configure SonarQube and other services in the next step!
|
220
|
-
|
221
|
-
Notes:
|
222
|
-
1. Check out [this manual](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) on how to set up signed commits
|
223
|
-
|
224
|
-
**Step 5**: Follow the [instructions](SERVICE_CONNECTIONS.md) to wire up
|
225
|
-
external services such as CloudCov, SonarQube Cloud, Read The Docs, Docker.io, and Streamlit Community Cloud.
|
226
|
-
|
227
|
-
**Step 6**: Release the first version of your project
|
228
|
-
```shell
|
229
|
-
make bump
|
230
|
-
```
|
231
|
-
Notes:
|
232
|
-
1. You can remove the above sections - from "Scaffolding" to this notes - post having successfully generated your project.
|
233
|
-
2. The following sections refer to the dummy application and service generated into the `tests` and `src` folder by this template.
|
234
|
-
Use the documentation and code as inspiration, adapt to your business logic, or remove and start documenting and coding from scratch.
|
235
|
-
|
122
|
+
Example project scaffolded and kept up to date with OE Python Template
|
123
|
+
(oe-python-template).
|
236
124
|
|
237
125
|
## Overview
|
238
126
|
|
239
|
-
Adding OE Python Template Example to your project as a dependency is easy. See
|
127
|
+
Adding OE Python Template Example to your project as a dependency is easy. See
|
128
|
+
below for usage examples.
|
240
129
|
|
241
130
|
```shell
|
242
131
|
uv add oe-python-template-example # add dependency to your project
|
243
132
|
```
|
244
133
|
|
245
|
-
If you don't have uv installed follow
|
246
|
-
|
134
|
+
If you don't have uv installed follow
|
135
|
+
[these instructions](https://docs.astral.sh/uv/getting-started/installation/).
|
136
|
+
If you still prefer pip over the modern and fast package manager
|
137
|
+
[uv](https://github.com/astral-sh/uv), you can install the library like this:
|
247
138
|
|
248
139
|
```shell
|
249
140
|
pip install oe-python-template-example # add dependency to your project
|
250
141
|
```
|
251
142
|
|
252
|
-
Executing the command line interface (CLI) in an isolated Python environment is
|
143
|
+
Executing the command line interface (CLI) in an isolated Python environment is
|
144
|
+
just as easy:
|
253
145
|
|
254
146
|
```shell
|
255
147
|
uvx oe-python-template-example hello world # prints "Hello, world! [..]"
|
@@ -45,137 +45,29 @@
|
|
45
45
|
---
|
46
46
|
|
47
47
|
|
48
|
-
Example project scaffolded and kept up to date with OE Python Template
|
49
|
-
|
50
|
-
### Scaffolding
|
51
|
-
|
52
|
-
This [Copier](https://copier.readthedocs.io/en/stable/) template enables you to quickly generate (scaffold) a Python package with fully functioning build and test automation:
|
53
|
-
|
54
|
-
1. 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.
|
55
|
-
2. During project generation, you can flexibly configure naming of the Python distribution, import package, main author, GitHub repository, organization, and many other aspects to match your specific requirements (see [copier.yml](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/copier.yml) for all available options).
|
56
|
-
|
57
|
-
### Development Infrastructure
|
58
|
-
|
59
|
-
Projects generated with this template come with a comprehensive development toolchain and quality assurance framework that supports the entire software development lifecycle - from coding and testing to documentation, release management, and compliance auditing. This infrastructure automates routine tasks, enforces code quality standards, and streamlines the path to production:
|
60
|
-
|
61
|
-
1. Linting with [Ruff](https://github.com/astral-sh/ruff)
|
62
|
-
2. Static type checking with [mypy](https://mypy.readthedocs.io/en/stable/)
|
63
|
-
3. 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)
|
64
|
-
4. Unit and E2E testing with [pytest](https://docs.pytest.org/en/stable/) including parallel test execution
|
65
|
-
5. Matrix testing in multiple environments with [nox](https://nox.thea.codes/en/stable/)
|
66
|
-
6. Test coverage reported with [Codecov](https://codecov.io/) and published as release artifact
|
67
|
-
7. CI/CD pipeline automated with [GitHub Actions](https://github.com/features/actions) with parallel and reusable workflows, including scheduled testing, release automation, and multiple reporting channels and formats
|
68
|
-
8. CI/CD pipeline can be run locally with [act](https://github.com/nektos/act)
|
69
|
-
9. Code quality and security checks with [SonarQube](https://www.sonarsource.com/products/sonarcloud) and [GitHub CodeQL](https://codeql.github.com/)
|
70
|
-
10. Dependency monitoring and vulnerability scanning with [pip-audit](https://pypi.org/project/pip-audit/), [trivy](https://trivy.dev/latest/), [Renovate](https://github.com/renovatebot/renovate), and [GitHub Dependabot](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide)
|
71
|
-
11. Error monitoring and profiling with [Sentry](https://sentry.io/) (optional)
|
72
|
-
12. Logging and metrics with [Logfire](https://logfire.dev/) (optional)
|
73
|
-
13. Prepared for uptime monitoring and scheduled tests with [betterstack](https://betterstack.com/) or alternatives
|
74
|
-
14. Licenses of dependencies extracted with [pip-licenses](https://pypi.org/project/pip-licenses/), matched with allow list, and published as release artifacts in CSV and JSON format for further compliance checks
|
75
|
-
15. Generation of attributions from extracted licenses
|
76
|
-
16. Software Bill of Materials (SBOM) generated in [CycloneDX](https://cyclonedx.org/) and [SPDX](https://spdx.dev/) formats with [cyclonedx-python](https://github.com/CycloneDX/cyclonedx-python) resp. [trivy](https://trivy.dev/latest/), published as release artifacts
|
77
|
-
17. Version and release management with [bump-my-version](https://callowayproject.github.io/bump-my-version/)
|
78
|
-
18. Changelog and release notes generated with [git-cliff](https://git-cliff.org/)
|
79
|
-
19. Documentation generated with [Sphinx](https://www.sphinx-doc.org/en/master/) including reference documentation for the library, CLI, and API
|
80
|
-
20. Documentation published to [Read The Docs](https://readthedocs.org/) including generation of PDF and single page HTML versions
|
81
|
-
21. Documentation including dynamic badges, setup instructions, contribution guide and security policy
|
82
|
-
22. Interactive OpenAPI specification with [Swagger](https://swagger.io/)
|
83
|
-
23. Python package published to [PyPI](https://pypi.org/)
|
84
|
-
24. Multi-stage build of fat (all extras) and slim (no extras) multi-arch (arm64 and amd64) Docker images, running non-root within immutable container
|
85
|
-
25. 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)
|
86
|
-
26. One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
|
87
|
-
27. Settings for use with [VSCode](https://code.visualstudio.com/)
|
88
|
-
28. Settings and custom instructions for use with [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
|
89
|
-
29. API deployed as serverless function to [Vercel](https://vercel.com/) (optional)
|
90
|
-
|
91
|
-
### Multi-head Application Features
|
92
|
-
|
93
|
-
Beyond development tooling, projects generated with this template include the code, documentation, and configuration of a fully functioning service and multi-head application. This reference implementation serves as a starting point for your own business logic with modern patterns and enterprise practices already in place:
|
94
|
-
|
95
|
-
1. Usable as library with "Hello" module exposing a simple service that can say "Hello, world!" and echo utterances.
|
96
|
-
2. Comfortable command-line interface (CLI) with [Typer](https://typer.tiangolo.com/)
|
97
|
-
3. Versioned webservice API with [FastAPI](https://fastapi.tiangolo.com/)
|
98
|
-
4. Cross-platform Graphical User Interface (GUI) with
|
99
|
-
[NiceGUI](https://nicegui.io/) running in a browser or native window
|
100
|
-
5. [Interactive Jupyter notebook](https://jupyter.org/) and [reactive Marimo notebook](https://marimo.io/)
|
101
|
-
6. Simple Web UI with [Streamlit](https://streamlit.io/)
|
102
|
-
7. Modular architecture auto-discovers and registers services, CLI commands, API routes and GUI pages exposed by domain modules
|
103
|
-
8. Validation and settings management with [pydantic](https://docs.pydantic.dev/)
|
104
|
-
9. System module providing aggregate health and info to the runtime, compiled settings, and further info provided by domain modules
|
105
|
-
10. Health and Info available via command, webservice API (info passsword protected) and GUI
|
106
|
-
11. Flexible logging and instrumentation, including support for [Sentry](https://sentry.io/) and [Logfire](https://logfire.dev/)
|
107
|
-
12. Hello service demonstrates use of custom real time metrics collected via Logfire
|
108
|
-
13. 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/)
|
109
|
-
|
110
|
-
Explore [here](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example) for what's generated out of the box. While this template comes with multiple application interfaces ("heads") - Library, CLI, API, GUI, notebooks, and Streamlit; running native and within Docker - they're included to demonstrate capabilities and provide implementation patterns. You're expected to use this as a foundation, keeping only the interfaces relevant to your project's requirements. The modular architecture makes it easy to:
|
111
|
-
|
112
|
-
1. Remove unnecessary interfaces to simplify your codebase
|
113
|
-
2. Adapt existing interfaces to your specific use cases
|
114
|
-
3. Focus on your core business logic without reimplementing infrastructure
|
115
|
-
4. Add new interfaces while leveraging the existing patterns
|
116
|
-
|
117
|
-
|
118
|
-
## Generate a new project
|
119
|
-
|
120
|
-
To generate, build and release a fully functioning project in a few minutes, follow these 5 steps:
|
121
|
-
|
122
|
-
**Step 1**: Execute the following command to install or update tooling.
|
123
|
-
```shell
|
124
|
-
# Install Homebrew, uv package manager, copier and further dev tools
|
125
|
-
curl -LsSf https://raw.githubusercontent.com/helmut-hoffer-von-ankershoffen/oe-python-template/HEAD/install.sh | sh
|
126
|
-
```
|
127
|
-
|
128
|
-
**Step 2**: [Create a 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.
|
129
|
-
|
130
|
-
**Step 3**: Execute the following command to generate a new project based on this template.
|
131
|
-
```shell
|
132
|
-
# Ensure to stand in your freshly created git repository before executing this command
|
133
|
-
copier copy --trust gh:helmut-hoffer-von-ankershoffen/oe-python-template .
|
134
|
-
```
|
135
|
-
|
136
|
-
**Step 4**: Execute the following commands to push your initial commit to GitHub.
|
137
|
-
```shell
|
138
|
-
git add .
|
139
|
-
git commit -m "chore: Initial commit"
|
140
|
-
git push
|
141
|
-
```
|
142
|
-
|
143
|
-
Check the [Actions tab](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/actions) of your GitHub repository: The CI/CD workflow of your project is already running!
|
144
|
-
|
145
|
-
The workflow will fail at the SonarQube step, as this external service is not yet configured for our new repository. We will configure SonarQube and other services in the next step!
|
146
|
-
|
147
|
-
Notes:
|
148
|
-
1. Check out [this manual](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) on how to set up signed commits
|
149
|
-
|
150
|
-
**Step 5**: Follow the [instructions](SERVICE_CONNECTIONS.md) to wire up
|
151
|
-
external services such as CloudCov, SonarQube Cloud, Read The Docs, Docker.io, and Streamlit Community Cloud.
|
152
|
-
|
153
|
-
**Step 6**: Release the first version of your project
|
154
|
-
```shell
|
155
|
-
make bump
|
156
|
-
```
|
157
|
-
Notes:
|
158
|
-
1. You can remove the above sections - from "Scaffolding" to this notes - post having successfully generated your project.
|
159
|
-
2. The following sections refer to the dummy application and service generated into the `tests` and `src` folder by this template.
|
160
|
-
Use the documentation and code as inspiration, adapt to your business logic, or remove and start documenting and coding from scratch.
|
161
|
-
|
48
|
+
Example project scaffolded and kept up to date with OE Python Template
|
49
|
+
(oe-python-template).
|
162
50
|
|
163
51
|
## Overview
|
164
52
|
|
165
|
-
Adding OE Python Template Example to your project as a dependency is easy. See
|
53
|
+
Adding OE Python Template Example to your project as a dependency is easy. See
|
54
|
+
below for usage examples.
|
166
55
|
|
167
56
|
```shell
|
168
57
|
uv add oe-python-template-example # add dependency to your project
|
169
58
|
```
|
170
59
|
|
171
|
-
If you don't have uv installed follow
|
172
|
-
|
60
|
+
If you don't have uv installed follow
|
61
|
+
[these instructions](https://docs.astral.sh/uv/getting-started/installation/).
|
62
|
+
If you still prefer pip over the modern and fast package manager
|
63
|
+
[uv](https://github.com/astral-sh/uv), you can install the library like this:
|
173
64
|
|
174
65
|
```shell
|
175
66
|
pip install oe-python-template-example # add dependency to your project
|
176
67
|
```
|
177
68
|
|
178
|
-
Executing the command line interface (CLI) in an isolated Python environment is
|
69
|
+
Executing the command line interface (CLI) in an isolated Python environment is
|
70
|
+
just as easy:
|
179
71
|
|
180
72
|
```shell
|
181
73
|
uvx oe-python-template-example hello world # prints "Hello, world! [..]"
|
@@ -1,6 +1,6 @@
|
|
1
1
|
[project]
|
2
2
|
name = "oe-python-template-example"
|
3
|
-
version = "0.5.
|
3
|
+
version = "0.5.2"
|
4
4
|
description = "🧠 Example project scaffolded and kept up to date with OE Python Template (oe-python-template)."
|
5
5
|
readme = "README.md"
|
6
6
|
authors = [
|
@@ -290,7 +290,7 @@ source = ["src/"]
|
|
290
290
|
|
291
291
|
|
292
292
|
[tool.bumpversion]
|
293
|
-
current_version = "0.5.
|
293
|
+
current_version = "0.5.2"
|
294
294
|
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
|
295
295
|
serialize = ["{major}.{minor}.{patch}"]
|
296
296
|
search = "{current_version}"
|
@@ -0,0 +1,26 @@
|
|
1
|
+
"""Homepage (index) of GUI."""
|
2
|
+
|
3
|
+
from ..utils import BasePageBuilder, __project_name__, __version__ # noqa: TID252
|
4
|
+
from ._service import Service
|
5
|
+
|
6
|
+
|
7
|
+
class PageBuilder(BasePageBuilder):
|
8
|
+
@staticmethod
|
9
|
+
def register_pages() -> None:
|
10
|
+
from nicegui import run, ui # noqa: PLC0415
|
11
|
+
|
12
|
+
@ui.page("/info")
|
13
|
+
async def page_info() -> None:
|
14
|
+
"""Homepage of GUI."""
|
15
|
+
ui.label(f"{__project_name__} v{__version__}").mark("LABEL_VERSION")
|
16
|
+
spinner = ui.spinner("dots", size="lg", color="red")
|
17
|
+
properties = {
|
18
|
+
"content": {"json": "Loading ..."},
|
19
|
+
"readOnly": True,
|
20
|
+
}
|
21
|
+
editor = ui.json_editor(properties).mark("JSON_EDITOR_INFO")
|
22
|
+
ui.link("Home", "/").mark("LINK_HOME")
|
23
|
+
info = await run.cpu_bound(Service().info, True, True)
|
24
|
+
properties["content"] = {"json": info}
|
25
|
+
editor.update()
|
26
|
+
spinner.delete()
|
@@ -31,6 +31,10 @@ from ._settings import Settings
|
|
31
31
|
|
32
32
|
log = get_logger(__name__)
|
33
33
|
|
34
|
+
# Note: There is multiple measurements and network calls
|
35
|
+
MEASURE_INTERVAL_SECONDS = 5
|
36
|
+
NETWORK_TIMEOUT = 5
|
37
|
+
|
34
38
|
|
35
39
|
class RuntimeDict(TypedDict, total=False):
|
36
40
|
"""Type for runtime information dictionary."""
|
@@ -103,7 +107,7 @@ class Service(BaseService):
|
|
103
107
|
return token == self._settings.token.get_secret_value()
|
104
108
|
|
105
109
|
@staticmethod
|
106
|
-
def _get_public_ipv4(timeout: int =
|
110
|
+
def _get_public_ipv4(timeout: int = NETWORK_TIMEOUT) -> str | None:
|
107
111
|
"""Get the public IPv4 address of the system.
|
108
112
|
|
109
113
|
Args:
|
@@ -157,8 +161,8 @@ class Service(BaseService):
|
|
157
161
|
bootdatetime = boottime()
|
158
162
|
vmem = psutil.virtual_memory()
|
159
163
|
swap = psutil.swap_memory()
|
160
|
-
cpu_percent = psutil.cpu_percent(interval=
|
161
|
-
cpu_times_percent = psutil.cpu_times_percent(interval=
|
164
|
+
cpu_percent = psutil.cpu_percent(interval=MEASURE_INTERVAL_SECONDS)
|
165
|
+
cpu_times_percent = psutil.cpu_times_percent(interval=MEASURE_INTERVAL_SECONDS)
|
162
166
|
|
163
167
|
rtn: InfoDict = {
|
164
168
|
"package": {
|
@@ -163,7 +163,7 @@ class GUILocalFilePicker:
|
|
163
163
|
self.drives_toggle = ui.toggle(drives, value=drives[0], on_change=self.update_drive)
|
164
164
|
|
165
165
|
def update_drive(self) -> None:
|
166
|
-
self.path = Path(self.drives_toggle.value).expanduser()
|
166
|
+
self.path = Path(str(self.drives_toggle.value)).expanduser()
|
167
167
|
self.update_grid()
|
168
168
|
|
169
169
|
def update_grid(self) -> None:
|
@@ -2,7 +2,6 @@
|
|
2
2
|
|
3
3
|
from pathlib import Path
|
4
4
|
|
5
|
-
import psutil
|
6
5
|
from pydantic import BaseModel
|
7
6
|
|
8
7
|
|
@@ -28,6 +27,8 @@ def get_process_info() -> ProcessInfo:
|
|
28
27
|
Returns:
|
29
28
|
ProcessInfo: Object containing process information.
|
30
29
|
"""
|
30
|
+
import psutil # noqa: PLC0415
|
31
|
+
|
31
32
|
current_process = psutil.Process()
|
32
33
|
parent = current_process.parent()
|
33
34
|
|
@@ -1,20 +0,0 @@
|
|
1
|
-
"""Homepage (index) of GUI."""
|
2
|
-
|
3
|
-
from ..utils import BasePageBuilder, __project_name__, __version__ # noqa: TID252
|
4
|
-
from ._service import Service
|
5
|
-
|
6
|
-
|
7
|
-
class PageBuilder(BasePageBuilder):
|
8
|
-
@staticmethod
|
9
|
-
def register_pages() -> None:
|
10
|
-
from nicegui import ui # noqa: PLC0415
|
11
|
-
|
12
|
-
@ui.page("/info")
|
13
|
-
def page_info() -> None:
|
14
|
-
"""Homepage of GUI."""
|
15
|
-
ui.label(f"{__project_name__} v{__version__}").mark("LABEL_VERSION")
|
16
|
-
ui.json_editor({
|
17
|
-
"content": {"json": Service().info(True, True)},
|
18
|
-
"readOnly": True,
|
19
|
-
}).mark("JSON_EDITOR_INFO")
|
20
|
-
ui.link("Home", "/").mark("LINK_HOME")
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|