oe-python-template-example 0.4.0__tar.gz → 0.4.2__tar.gz

{oe_python_template_example-0.4.0 → oe_python_template_example-0.4.2}/.gitignore

@@ -17,6 +17,10 @@ env/
 .secrets.json
 .act-env-secret
 
+# More secrets
+.ssh
+.aws
+
 # Python virtual environment
 venv/
 .venv/
@@ -69,6 +73,7 @@ tmp/
 # Node temps
 node_modules/
 
+
 # AI workflow
 .fixme
 
@@ -80,4 +85,5 @@ node_modules/
 .vercel
 
 
-# Application specific
+
+# Application specific

{oe_python_template_example-0.4.0 → oe_python_template_example-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oe-python-template-example
-Version: 0.4.0
+Version: 0.4.2
 Summary: 🧠 Example project scaffolded and kept up to date with OE Python Template (oe-python-template).
 Project-URL: Homepage, https://oe-python-template-example.readthedocs.io/en/latest/
 Project-URL: Documentation, https://oe-python-template-example.readthedocs.io/en/latest/
@@ -59,15 +59,18 @@ Requires-Dist: opentelemetry-instrumentation-tornado>=0.53b0
 Requires-Dist: opentelemetry-instrumentation-urllib3>=0.53b0
 Requires-Dist: opentelemetry-instrumentation-urllib>=0.53b0
 Requires-Dist: psutil>=7.0.0
-Requires-Dist: pydantic-settings>=2.8.1
+Requires-Dist: pydantic-settings>=2.9.1
 Requires-Dist: pydantic>=2.11.3
-Requires-Dist: sentry-sdk>=2.25.1
+Requires-Dist: sentry-sdk>=2.26.1
 Requires-Dist: typer>=0.15.1
 Requires-Dist: uptime>=3.0.1
+Provides-Extra: app
+Requires-Dist: nicegui>=2.15.0; extra == 'app'
+Requires-Dist: pywebview>=5.4; extra == 'app'
 Provides-Extra: examples
 Requires-Dist: jinja2>=3.1.6; extra == 'examples'
 Requires-Dist: jupyter>=1.1.1; extra == 'examples'
-Requires-Dist: marimo>=0.12.8; extra == 'examples'
+Requires-Dist: marimo>=0.13.0; extra == 'examples'
 Requires-Dist: streamlit>=1.44.1; extra == 'examples'
 Description-Content-Type: text/markdown
 
@@ -151,13 +154,15 @@ Projects generated with this template come with a comprehensive development tool
 17. Changelog and release notes generated with [git-cliff](https://git-cliff.org/)
 18. Documentation generated with [Sphinx](https://www.sphinx-doc.org/en/master/) including reference documentation for the library, CLI, and API
 19. Documentation published to [Read The Docs](https://readthedocs.org/) including generation of PDF and single page HTML versions
-20. Interactive OpenAPI specification with [Swagger](https://swagger.io/)
-21. Python package published to [PyPI](https://pypi.org/)
-22. 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)
-23. One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
-24. Settings for use with [VSCode](https://code.visualstudio.com/)
-25. Settings and custom instructions for use with [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
-26. API deployed as serverless function to [Vercel](https://vercel.com/) (optional)
+20. Documentation including dynamic badges, setup instructions, contribution guide and security policy
+21. Interactive OpenAPI specification with [Swagger](https://swagger.io/)
+22. Python package published to [PyPI](https://pypi.org/)
+23. Multi-stage build of fat and slim (no-extras) Docker images, app running nonroot
+24. Mult-arch 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)
+25. One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
+26. Settings for use with [VSCode](https://code.visualstudio.com/)
+27. Settings and custom instructions for use with [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
+28. API deployed as serverless function to [Vercel](https://vercel.com/) (optional)
 
 ### Application Features
 
@@ -165,17 +170,20 @@ Beyond development tooling, projects generated with this template include the co
 
 1. Usable as library with "Hello" module exposing a simple service that can say "Hello, world!" and echo utterances.
 2. Command-line interface (CLI) with [Typer](https://typer.tiangolo.com/)
-3. Versioned webservice API with [FastAPI](https://fastapi.tiangolo.com/)
-4. [Interactive Jupyter notebook](https://jupyter.org/) and [reactive Marimo notebook](https://marimo.io/)
-5. Simple Web UI with [Streamlit](https://streamlit.io/)
-6. 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/)
+2. Versioned webservice API with [FastAPI](https://fastapi.tiangolo.com/)
+3. Comfortable command-line interface (CLI) with
+   [Typer](https://typer.tiangolo.com/)
+4. Cross-platform Graphical User Interface (GUI) with
+   [NiceGUI](https://nicegui.io/) running in native window
+5. [Interactive Jupyter notebook](https://jupyter.org/) and [reactive Marimo notebook](https://marimo.io/)
+6. Simple Web UI with [Streamlit](https://streamlit.io/)
 7. Validation and settings management with [pydantic](https://docs.pydantic.dev/)
-8. Info command enabling to inspect the runtime, compiled settings, and further info provided dynamically by modules
-9. Health endpoint exposing system health dynamically aggregated from all modules and dependencies
-10. Flexible logging and instrumentation, including support for [Sentry](https://sentry.io/) and [Logfire](https://logfire.dev/) 
-11. Hello service demonstrates use of custom real time metrics collected via Logfire
-12. Modular architecture including auto-registration of services, CLI commands and API routes exposed by modules
-13. Documentation including dynamic badges, setup instructions, contribution guide and security policy
+8. Flexible logging and instrumentation, including support for [Sentry](https://sentry.io/) and [Logfire](https://logfire.dev/) 
+9. Modular architecture including auto-registration of services, CLI commands, API routes and GUI pages exposed by domain modules
+10. System module providing aggregate health and info to the runtime, compiled settings, and further info provided by domain modules
+11. Health and Info available via command, webservice API (info passsword protected) and GUI
+12. Hello service demonstrates use of custom real time metrics collected via Logfire
+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/)
 
 Explore [here](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example) for what's generated out of the box.
 
@@ -242,9 +250,12 @@ pip install oe-python-template-example        # add dependency to your project
 Executing the command line interface (CLI) in an isolated Python environment is just as easy:
 
 ```shell
-uvx oe-python-template-example hello-world       # prints "Hello, world! [..]"
-uvx oe-python-template-example serve             # serves web API
-uvx oe-python-template-example serve --port=4711 # serves web API on port 4711
+uvx oe-python-template-example hello world               # prints "Hello, world! [..]"
+uvx oe-python-template-example hello echo "Lorem Ipsum"  # echos "Lorem Ipsum"
+uvx oe-python-template-example gui                       # opens the graphical user interface (GUI)
+uvx oe-python-template-example system serve              # serves web API
+uvx oe-python-template-example system serve --port=4711  # serves web API on port 4711
+uvx oe-python-template-example system openapi            # serves web API on port 4711
 ```
 
 Notes:
@@ -257,10 +268,11 @@ The CLI provides extensive help:
 
 ```shell
 uvx oe-python-template-example --help                # all CLI commands
-uvx oe-python-template-example hello-world --help    # help for specific command
-uvx oe-python-template-example echo --help
-uvx oe-python-template-example openapi --help
-uvx oe-python-template-example serve --help
+uvx oe-python-template-example hello world --help    # help for specific command
+uvx oe-python-template-example hello echo --help
+uvx oe-python-template-example gui --help
+uvx oe-python-template-example system serve --help
+uvx oe-python-template-example system openapi --help
 ```
 
 
@@ -388,6 +400,7 @@ uvx oe-python-template-example hello world
 uvx oe-python-template-example hello echo --help
 uvx oe-python-template-example hello echo "Lorem"
 uvx oe-python-template-example hello echo "Lorem" --json
+uvx oe-python-template-example gui
 uvx oe-python-template-example system info
 uvx oe-python-template-example system health
 uvx oe-python-template-example system openapi
@@ -472,6 +485,15 @@ echo "Shutting down the API container ..."
 docker compose down
 ```
 
+#### Slim
+
+The default Docker image includes all extras. Additionally a slim image is provided, with no extras. Run as follows
+
+```shell
+docker compose run --remove-orphans oe-python-template-example-slim --help
+```
+
+
 * See the [reference documentation of the API](https://oe-python-template-example.readthedocs.io/en/latest/api_reference_v1.html) for detailed documentation of all API operations and parameters.
 
 
@@ -483,9 +505,9 @@ Nothing yet
 ## Further Reading
 
 * Inspect our [security policy](https://oe-python-template-example.readthedocs.io/en/latest/security.html) with detailed documentation of checks, tools and principles.
-* Check out the [CLI Reference](https://oe-python-template-example.readthedocs.io/en/latest/cli_reference.html) with detailed documentation of all CLI commands and options.
-* Check out the [Library Reference](https://oe-python-template-example.readthedocs.io/en/latest/lib_reference.html) with detailed documentation of public classes and functions.
-* Check out the [API Reference](https://oe-python-template-example.readthedocs.io/en/latest/api_reference_v1.html) with detailed documentation of all API operations and parameters.
+* Check out the [CLI reference](https://oe-python-template-example.readthedocs.io/en/latest/cli_reference.html) with detailed documentation of all CLI commands and options.
+* Check out the [library reference](https://oe-python-template-example.readthedocs.io/en/latest/lib_reference.html) with detailed documentation of public classes and functions.
+* Check out the [API reference](https://oe-python-template-example.readthedocs.io/en/latest/api_reference_v1.html) with detailed documentation of all API operations and parameters.
 * Our [release notes](https://oe-python-template-example.readthedocs.io/en/latest/release-notes.html) provide a complete log of recent improvements and changes.
 * In case you want to help us improve 🧠 OE Python Template Example: The [contribution guidelines](https://oe-python-template-example.readthedocs.io/en/latest/contributing.html) explain how to setup your development environment and create pull requests.
 * We gratefully acknowledge the [open source projects](https://oe-python-template-example.readthedocs.io/en/latest/attributions.html) that this project builds upon. Thank you to all these wonderful contributors!

{oe_python_template_example-0.4.0 → oe_python_template_example-0.4.2}/README.md

@@ -78,13 +78,15 @@ Projects generated with this template come with a comprehensive development tool
 17. Changelog and release notes generated with [git-cliff](https://git-cliff.org/)
 18. Documentation generated with [Sphinx](https://www.sphinx-doc.org/en/master/) including reference documentation for the library, CLI, and API
 19. Documentation published to [Read The Docs](https://readthedocs.org/) including generation of PDF and single page HTML versions
-20. Interactive OpenAPI specification with [Swagger](https://swagger.io/)
-21. Python package published to [PyPI](https://pypi.org/)
-22. 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)
-23. One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
-24. Settings for use with [VSCode](https://code.visualstudio.com/)
-25. Settings and custom instructions for use with [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
-26. API deployed as serverless function to [Vercel](https://vercel.com/) (optional)
+20. Documentation including dynamic badges, setup instructions, contribution guide and security policy
+21. Interactive OpenAPI specification with [Swagger](https://swagger.io/)
+22. Python package published to [PyPI](https://pypi.org/)
+23. Multi-stage build of fat and slim (no-extras) Docker images, app running nonroot
+24. Mult-arch 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)
+25. One-click development environments with [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) and [GitHub Codespaces](https://github.com/features/codespaces)
+26. Settings for use with [VSCode](https://code.visualstudio.com/)
+27. Settings and custom instructions for use with [GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
+28. API deployed as serverless function to [Vercel](https://vercel.com/) (optional)
 
 ### Application Features
 
@@ -92,17 +94,20 @@ Beyond development tooling, projects generated with this template include the co
 
 1. Usable as library with "Hello" module exposing a simple service that can say "Hello, world!" and echo utterances.
 2. Command-line interface (CLI) with [Typer](https://typer.tiangolo.com/)
-3. Versioned webservice API with [FastAPI](https://fastapi.tiangolo.com/)
-4. [Interactive Jupyter notebook](https://jupyter.org/) and [reactive Marimo notebook](https://marimo.io/)
-5. Simple Web UI with [Streamlit](https://streamlit.io/)
-6. 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/)
+2. Versioned webservice API with [FastAPI](https://fastapi.tiangolo.com/)
+3. Comfortable command-line interface (CLI) with
+   [Typer](https://typer.tiangolo.com/)
+4. Cross-platform Graphical User Interface (GUI) with
+   [NiceGUI](https://nicegui.io/) running in native window
+5. [Interactive Jupyter notebook](https://jupyter.org/) and [reactive Marimo notebook](https://marimo.io/)
+6. Simple Web UI with [Streamlit](https://streamlit.io/)
 7. Validation and settings management with [pydantic](https://docs.pydantic.dev/)
-8. Info command enabling to inspect the runtime, compiled settings, and further info provided dynamically by modules
-9. Health endpoint exposing system health dynamically aggregated from all modules and dependencies
-10. Flexible logging and instrumentation, including support for [Sentry](https://sentry.io/) and [Logfire](https://logfire.dev/) 
-11. Hello service demonstrates use of custom real time metrics collected via Logfire
-12. Modular architecture including auto-registration of services, CLI commands and API routes exposed by modules
-13. Documentation including dynamic badges, setup instructions, contribution guide and security policy
+8. Flexible logging and instrumentation, including support for [Sentry](https://sentry.io/) and [Logfire](https://logfire.dev/) 
+9. Modular architecture including auto-registration of services, CLI commands, API routes and GUI pages exposed by domain modules
+10. System module providing aggregate health and info to the runtime, compiled settings, and further info provided by domain modules
+11. Health and Info available via command, webservice API (info passsword protected) and GUI
+12. Hello service demonstrates use of custom real time metrics collected via Logfire
+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/)
 
 Explore [here](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example) for what's generated out of the box.
 
@@ -169,9 +174,12 @@ pip install oe-python-template-example        # add dependency to your project
 Executing the command line interface (CLI) in an isolated Python environment is just as easy:
 
 ```shell
-uvx oe-python-template-example hello-world       # prints "Hello, world! [..]"
-uvx oe-python-template-example serve             # serves web API
-uvx oe-python-template-example serve --port=4711 # serves web API on port 4711
+uvx oe-python-template-example hello world               # prints "Hello, world! [..]"
+uvx oe-python-template-example hello echo "Lorem Ipsum"  # echos "Lorem Ipsum"
+uvx oe-python-template-example gui                       # opens the graphical user interface (GUI)
+uvx oe-python-template-example system serve              # serves web API
+uvx oe-python-template-example system serve --port=4711  # serves web API on port 4711
+uvx oe-python-template-example system openapi            # serves web API on port 4711
 ```
 
 Notes:
@@ -184,10 +192,11 @@ The CLI provides extensive help:
 
 ```shell
 uvx oe-python-template-example --help                # all CLI commands
-uvx oe-python-template-example hello-world --help    # help for specific command
-uvx oe-python-template-example echo --help
-uvx oe-python-template-example openapi --help
-uvx oe-python-template-example serve --help
+uvx oe-python-template-example hello world --help    # help for specific command
+uvx oe-python-template-example hello echo --help
+uvx oe-python-template-example gui --help
+uvx oe-python-template-example system serve --help
+uvx oe-python-template-example system openapi --help
 ```
 
 
@@ -315,6 +324,7 @@ uvx oe-python-template-example hello world
 uvx oe-python-template-example hello echo --help
 uvx oe-python-template-example hello echo "Lorem"
 uvx oe-python-template-example hello echo "Lorem" --json
+uvx oe-python-template-example gui
 uvx oe-python-template-example system info
 uvx oe-python-template-example system health
 uvx oe-python-template-example system openapi
@@ -399,6 +409,15 @@ echo "Shutting down the API container ..."
 docker compose down
 ```
 
+#### Slim
+
+The default Docker image includes all extras. Additionally a slim image is provided, with no extras. Run as follows
+
+```shell
+docker compose run --remove-orphans oe-python-template-example-slim --help
+```
+
+
 * See the [reference documentation of the API](https://oe-python-template-example.readthedocs.io/en/latest/api_reference_v1.html) for detailed documentation of all API operations and parameters.
 
 
@@ -410,9 +429,9 @@ Nothing yet
 ## Further Reading
 
 * Inspect our [security policy](https://oe-python-template-example.readthedocs.io/en/latest/security.html) with detailed documentation of checks, tools and principles.
-* Check out the [CLI Reference](https://oe-python-template-example.readthedocs.io/en/latest/cli_reference.html) with detailed documentation of all CLI commands and options.
-* Check out the [Library Reference](https://oe-python-template-example.readthedocs.io/en/latest/lib_reference.html) with detailed documentation of public classes and functions.
-* Check out the [API Reference](https://oe-python-template-example.readthedocs.io/en/latest/api_reference_v1.html) with detailed documentation of all API operations and parameters.
+* Check out the [CLI reference](https://oe-python-template-example.readthedocs.io/en/latest/cli_reference.html) with detailed documentation of all CLI commands and options.
+* Check out the [library reference](https://oe-python-template-example.readthedocs.io/en/latest/lib_reference.html) with detailed documentation of public classes and functions.
+* Check out the [API reference](https://oe-python-template-example.readthedocs.io/en/latest/api_reference_v1.html) with detailed documentation of all API operations and parameters.
 * Our [release notes](https://oe-python-template-example.readthedocs.io/en/latest/release-notes.html) provide a complete log of recent improvements and changes.
 * In case you want to help us improve 🧠 OE Python Template Example: The [contribution guidelines](https://oe-python-template-example.readthedocs.io/en/latest/contributing.html) explain how to setup your development environment and create pull requests.
 * We gratefully acknowledge the [open source projects](https://oe-python-template-example.readthedocs.io/en/latest/attributions.html) that this project builds upon. Thank you to all these wonderful contributors!

{oe_python_template_example-0.4.0 → oe_python_template_example-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oe-python-template-example"
-version = "0.4.0"
+version = "0.4.2"
 description = "🧠 Example project scaffolded and kept up to date with OE Python Template (oe-python-template)."
 readme = "README.md"
 authors = [
@@ -75,49 +75,30 @@ dependencies = [
     "opentelemetry-instrumentation-urllib3>=0.53b0",
     "psutil>=7.0.0",
     "pydantic>=2.11.3",
-    "pydantic-settings>=2.8.1",
-    "sentry-sdk>=2.25.1",
+    "pydantic-settings>=2.9.1",
+    "sentry-sdk>=2.26.1",
     "typer>=0.15.1",
     "uptime>=3.0.1",
     # Custom
     # Nothing yet
 ]
 
-[project.scripts]
-oe-python-template-example = "oe_python_template_example.cli:cli"
-
-[project.urls]
-Homepage = "https://oe-python-template-example.readthedocs.io/en/latest/"
-Documentation = "https://oe-python-template-example.readthedocs.io/en/latest/"
-Source = "https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example"
-Changelog = "https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/releases"
-Issues = "https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/issues"
-
-[build-system]
-requires = ["hatchling==1.27.0"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build]
-include = ["src/*"]
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/oe_python_template_example"]
-
 [project.optional-dependencies]
 examples = [
     "streamlit>=1.44.1",
-    "marimo>=0.12.8",
+    "marimo>=0.13.0",
     "jupyter>=1.1.1",
     "jinja2>=3.1.6",
 ]
+app = ["nicegui>=2.15.0", "pywebview>=5.4"]
 
 [dependency-groups]
 dev = [
     "autodoc-pydantic>=2.2.0",
-    "bump-my-version>=1.1.1",
+    "bump-my-version>=1.1.2",
     "cyclonedx-py>=1.0.1",
     "detect-secrets>=1.5.0",
-    "enum-tools>=0.12.0",
+    "enum-tools>=0.13.0",
     "furo>=2024.8.6",
     "git-cliff>=2.8.0",
     "matplotlib>=3.10.1",
@@ -133,10 +114,12 @@ dev = [
     "pytest-docker>=3.2.1",
     "pytest-env>=1.1.5",
     "pytest-regressions>=2.7.0",
+    "pytest-selenium>=4.1.0",
     "pytest-subprocess>=1.5.3",
     "pytest-timeout>=2.3.1",
+    "pytest-watcher>=0.4.3",
     "pytest-xdist[psutil]>=3.6.1",
-    "ruff>=0.11.5",
+    "ruff>=0.11.6",
     "sphinx>=8.2.3",
     "sphinx-autobuild>=2024.10.3",
     "sphinx-copybutton>=0.5.2",
@@ -153,6 +136,26 @@ dev = [
     "watchdog>=6.0.0",
 ]
 
+[project.scripts]
+oe-python-template-example = "oe_python_template_example.cli:cli"
+
+[project.urls]
+Homepage = "https://oe-python-template-example.readthedocs.io/en/latest/"
+Documentation = "https://oe-python-template-example.readthedocs.io/en/latest/"
+Source = "https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example"
+Changelog = "https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/releases"
+Issues = "https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example/issues"
+
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+include = ["src/*"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oe_python_template_example"]
+
 [tool.uv]
 override-dependencies = [ # https://github.com/astral-sh/uv/issues/4422
     "rfc3987; sys_platform == 'never'", # GPLv3
@@ -278,7 +281,7 @@ source = ["src/"]
 
 
 [tool.bumpversion]
-current_version = "0.4.0"
+current_version = "0.4.2"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"
@@ -316,6 +319,9 @@ filename = "sonar-project.properties"
 [[tool.bumpversion.files]]
 filename = "docs/source/conf.py"
 
+[[tool.bumpversion.files]]
+filename = "examples/notebook.py"
+
 [tool.git-cliff.remote.github]
 owner = "helmut-hoffer-von-ankershoffen"
 repo = "oe-python-template-example"

{oe_python_template_example-0.4.0 → oe_python_template_example-0.4.2}/src/oe_python_template_example/api.py

@@ -31,7 +31,7 @@ API_BASE_URL = __base__url__
 if not API_BASE_URL:
     API_BASE_URL = f"http://{UVICORN_HOST}:{UVICORN_PORT}"
 
-app = FastAPI(
+api = FastAPI(
     root_path="/api",
     title=TITLE,
     contact={
@@ -76,4 +76,4 @@ for router in locate_implementations(VersionedAPIRouter):
 
 # Mount all API versions to the main app
 for version in API_VERSIONS:
-    app.mount(f"/{version}", api_instances[version])
+    api.mount(f"/{version}", api_instances[version])

oe_python_template_example-0.4.2/src/oe_python_template_example/cli.py

@@ -0,0 +1,55 @@
+"""CLI (Command Line Interface) of OE Python Template Example."""
+
+import sys
+from importlib.util import find_spec
+
+import typer
+
+from .constants import MODULES_TO_INSTRUMENT
+from .utils import __version__, boot, console, get_logger, prepare_cli
+
+boot(MODULES_TO_INSTRUMENT)
+logger = get_logger(__name__)
+
+cli = typer.Typer(help="Command Line Interface of OE Python Template Example")
+prepare_cli(cli, f"🧠 OE Python Template Example v{__version__} - built with love in Berlin 🐻")
+
+
+if find_spec("nicegui"):
+
+    @cli.command()
+    def gui() -> None:
+        """Start graphical user interface (GUI) in native window."""
+        from .utils import gui_run  # noqa: PLC0415
+
+        gui_run(native=True, with_api=False, title="OE Python Template Example", icon="🧠")
+
+
+if find_spec("marimo"):
+    from typing import Annotated
+
+    import uvicorn
+
+    from .utils import create_marimo_app
+
+    @cli.command()
+    def notebook(
+        host: Annotated[str, typer.Option(help="Host to bind the server to")] = "127.0.0.1",
+        port: Annotated[int, typer.Option(help="Port to bind the server to")] = 8001,
+    ) -> None:
+        """Start notebook in web browser."""
+        console.print(f"Starting marimo notebook server at http://{host}:{port}")
+        uvicorn.run(
+            create_marimo_app(),
+            host=host,
+            port=port,
+        )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    try:
+        cli()
+    except Exception as e:  # noqa: BLE001
+        logger.critical("Fatal error occurred: %s", e)
+        console.print(f"Fatal error occurred: {e}", style="error")
+        sys.exit(1)

oe_python_template_example-0.4.2/src/oe_python_template_example/constants.py

@@ -0,0 +1,13 @@
+"""Constants for the OE Python Template Example."""
+
+from pathlib import Path
+
+MODULES_TO_INSTRUMENT = ["oe_python_template_example.hello"]
+
+API_VERSIONS = {
+    "v1": "1.0.0",
+    "v2": "2.0.0",
+}
+
+NOTEBOOK_FOLDER = Path(__file__).parent.parent.parent / "examples"
+NOTEBOOK_APP = Path(__file__).parent.parent.parent / "examples" / "notebook.py"

{oe_python_template_example-0.4.0 → oe_python_template_example-0.4.2}/src/oe_python_template_example/hello/__init__.py

@@ -15,3 +15,14 @@ __all__ = [
     "api_v2",
     "cli",
 ]
+
+
+from importlib.util import find_spec
+
+# advertise PageBuuilder to enable auto-discovery
+if find_spec("nicegui"):
+    from ._gui import PageBuilder
+
+    __all__ += [
+        "PageBuilder",
+    ]

oe_python_template_example-0.4.2/src/oe_python_template_example/hello/_gui.py

@@ -0,0 +1,40 @@
+"""Homepage (index) of GUI."""
+
+from pathlib import Path
+
+import numpy as np
+from nicegui import ui
+
+from oe_python_template_example.utils import BasePageBuilder, GUILocalFilePicker
+
+from ._service import Service
+
+
+async def pick_file() -> None:
+    """Open a file picker dialog and show notifier when closed again."""
+    result = await GUILocalFilePicker(str(Path.cwd() / "examples"), multiple=True)
+    ui.notify(f"You chose {result}")
+
+
+class PageBuilder(BasePageBuilder):
+    @staticmethod
+    def register_pages() -> None:
+        @ui.page("/")
+        def page_index() -> None:
+            """Homepage of GUI."""
+            service = Service()
+
+            ui.button("Choose file", on_click=pick_file, icon="folder").mark("BUTTON_CHOOSE_FILE")
+
+            ui.button("Click me", on_click=lambda: ui.notify(service.get_hello_world()), icon="check").mark(
+                "BUTTON_CLICK_ME"
+            )
+
+            with ui.card().tight().mark("CARD_PLOT"):  # noqa: SIM117
+                with ui.matplotlib(figsize=(4, 3)).figure as fig:
+                    x = np.linspace(0.0, 5.0)
+                    y = np.cos(2 * np.pi * x) * np.exp(-x)
+                    ax = fig.gca()
+                    ax.plot(x, y, "-")
+
+            ui.link("Info", "/info").mark("LINK_INFO")

{oe_python_template_example-0.4.0 → oe_python_template_example-0.4.2}/src/oe_python_template_example/system/__init__.py

@@ -1,4 +1,4 @@
-"""Hello module."""
+"""System module."""
 
 from ._api import api_routers
 from ._cli import cli
@@ -12,6 +12,17 @@ __all__ = [
     "cli",
 ]
 
+
+from importlib.util import find_spec
+
+# advertise PageBuuilder to enable auto-discovery
+if find_spec("nicegui"):
+    from ._gui import PageBuilder
+
+    __all__ += [
+        "PageBuilder",
+    ]
+
 # Export all individual API routers so they are picked up by depdency injection (DI)
 for version, router in api_routers.items():
     router_name = f"api_{version}"

{oe_python_template_example-0.4.0 → oe_python_template_example-0.4.2}/src/oe_python_template_example/system/_cli.py

@@ -3,6 +3,7 @@
 import json
 import os
 from enum import StrEnum
+from importlib.util import find_spec
 from typing import Annotated
 
 import typer
@@ -81,29 +82,69 @@ def info(
             console.print(yaml.dump(info, width=80, default_flow_style=False), end="")
 
 
-@cli.command()
-def serve(
-    host: Annotated[str, typer.Option(help="Host to bind the server to")] = "127.0.0.1",
-    port: Annotated[int, typer.Option(help="Port to bind the server to")] = 8000,
-    watch: Annotated[bool, typer.Option(help="Enable auto-reload")] = True,
-) -> None:
-    """Start the webservice API server.
-
-    Args:
-        host (str): Host to bind the server to.
-        port (int): Port to bind the server to.
-        watch (bool): Enable auto-reload.
-    """
-    console.print(f"Starting API server at http://{host}:{port}")
-    # using environ to pass host/port to api.py to generate doc link
-    os.environ["UVICORN_HOST"] = host
-    os.environ["UVICORN_PORT"] = str(port)
-    uvicorn.run(
-        f"{__project_name__}.api:app",
-        host=host,
-        port=port,
-        reload=watch,
-    )
+if find_spec("nicegui"):
+    from ..utils import gui_run  # noqa: TID252
+
+    @cli.command()
+    def serve(  # noqa: PLR0913, PLR0917 # type: ignore
+        app: Annotated[bool, typer.Option(help="Enable web application")] = True,
+        api: Annotated[bool, typer.Option(help="Enable webservice API")] = True,
+        host: Annotated[str, typer.Option(help="Host to bind the server to")] = "127.0.0.1",
+        port: Annotated[int, typer.Option(help="Port to bind the server to")] = 8000,
+        watch: Annotated[bool, typer.Option(help="Enable auto-reload on changes of source code")] = True,
+        open_browser: Annotated[bool, typer.Option(help="Open app in browser after starting the server")] = False,
+    ) -> None:
+        """Start the web server, hosting the graphical web application and/or webservice API.
+
+        Args:
+            app (bool): Enable web application.
+            api (bool): Enable webservice API.
+            host (str): Host to bind the server to.
+            port (int): Port to bind the server to.
+            watch (bool): Enable auto-reload on changes of source code.
+            open_browser (bool): Open app in browser after starting the server.
+        """
+        if api and not app:
+            console.print(f"Starting webservice API server at http://{host}:{port}")
+            # using environ to pass host/port to api.py to generate doc link
+            os.environ["UVICORN_HOST"] = host
+            os.environ["UVICORN_PORT"] = str(port)
+            uvicorn.run(
+                f"{__project_name__}.api:api",
+                host=host,
+                port=port,
+                reload=watch,
+            )
+        elif app:
+            console.print(f"Starting web application server at http://{host}:{port}")
+            gui_run(native=False, host=host, port=port, with_api=api, show=open_browser)
+
+else:
+
+    @cli.command()
+    def serve(  # type: ignore
+        host: Annotated[str, typer.Option(help="Host to bind the server to")] = "127.0.0.1",
+        port: Annotated[int, typer.Option(help="Port to bind the server to")] = 8000,
+        watch: Annotated[bool, typer.Option(help="Enable auto-reload on changes of source code")] = True,
+    ) -> None:
+        """Start the web server, hosting the API.
+
+        Args:
+            api (bool): Enable webservice API.
+            host (str): Host to bind the server to.
+            port (int): Port to bind the server to.
+            watch (bool): Enable auto-reload on changes of source code.
+        """
+        console.print(f"Starting webservice API server at http://{host}:{port}")
+        # using environ to pass host/port to api.py to generate doc link
+        os.environ["UVICORN_HOST"] = host
+        os.environ["UVICORN_PORT"] = str(port)
+        uvicorn.run(
+            f"{__project_name__}.api:api",
+            host=host,
+            port=port,
+            reload=watch,
+        )
 
 
 @cli.command()

oe_python_template_example-0.4.2/src/oe_python_template_example/system/_gui.py

@@ -0,0 +1,20 @@
+"""Homepage (index) of GUI."""
+
+from nicegui import ui
+
+from ..utils import BasePageBuilder, __project_name__, __version__  # noqa: TID252
+from ._service import Service
+
+
+class PageBuilder(BasePageBuilder):
+    @staticmethod
+    def register_pages() -> None:
+        @ui.page("/info")
+        def page_info() -> None:
+            """Homepage of GUI."""
+            ui.label(f"{__project_name__} v{__version__}").mark("LABEL_VERSION")
+            ui.json_editor({
+                "content": {"json": Service().info(True, True)},
+                "readOnly": True,
+            }).mark("JSON_EDITOR_INFO")
+            ui.link("Home", "/").mark("LINK_HOME")

{oe_python_template_example-0.4.0 → oe_python_template_example-0.4.2}/src/oe_python_template_example/utils/__init__.py

@@ -60,3 +60,17 @@ __all__ = [
     "prepare_cli",
     "strip_to_none_before_validator",
 ]
+
+from importlib.util import find_spec
+
+if find_spec("nicegui"):
+    from ._gui import BasePageBuilder, GUILocalFilePicker, gui_register_pages, gui_run
+
+    __all__ += ["BasePageBuilder", "GUILocalFilePicker", "gui_register_pages", "gui_run"]
+
+if find_spec("marimo"):
+    from ._notebook import create_marimo_app
+
+    __all__ += [
+        "create_marimo_app",
+    ]

{oe_python_template_example-0.4.0 → oe_python_template_example-0.4.2}/src/oe_python_template_example/utils/_constants.py

@@ -14,7 +14,21 @@ __project_path__ = str(Path(__file__).parent.parent.parent)
 __version__ = metadata.version(__project_name__)
 __is_development_mode__ = "uvx" not in sys.argv[0].lower()
 __is_running_in_container__ = os.getenv(f"{__project_name__.upper()}_RUNNING_IN_CONTAINER")
-__env__ = os.getenv("ENV", os.getenv("VERCEL_ENV", "local"))
+
+# Determine environment we are deployed on
+ENV_VAR_MAPPINGS = {
+    "ENV": lambda env: env,
+    "VERCEL_ENV": lambda env: env,  # See https://vercel.com/docs/environment-variables/system-environment-variables
+    "RAILWAY_ENVIRONMENT": lambda env: env,  # See https://docs.railway.com/reference/variables#railway-provided-variables
+}
+__env__ = "local"  # Default
+for env_var, mapper in ENV_VAR_MAPPINGS.items():
+    env_value = os.getenv(env_var)
+    if env_value:
+        __env__ = mapper(env_value)  # type: ignore[no-untyped-call]
+        break
+
+# Define environment file paths
 __env_file__ = [
     Path.home() / f".{__project_name__}" / ".env",
     Path.home() / f".{__project_name__}" / f".env.{__env__}",
@@ -25,12 +39,18 @@ env_file_path = os.getenv(f"{__project_name__.upper()}_ENV_FILE")
 if env_file_path:
     __env_file__.insert(2, Path(env_file_path))
 
-vercel_base_url = os.getenv("VERCEL_URL", None)
-if vercel_base_url:
-    vercel_base_url = "https://" + vercel_base_url
-__base__url__ = os.getenv(__project_name__.upper() + "_BASE_URL", None)
-if not __base__url__ and vercel_base_url:
-    __base__url__ = vercel_base_url
+# Determine __base_url__
+PLATFORM_URL_MAPPINGS = {
+    "VERCEL_URL": lambda url: f"https://{url}",  # See https://vercel.com/docs/environment-variables/system-environment-variables
+    "RAILWAY_PUBLIC_DOMAIN": lambda url: f"https://{url}",  # See https://docs.railway.com/reference/variables#railway-provided-variables
+}
+__base__url__ = os.getenv(f"{__project_name__.upper()}_BASE_URL")
+if not __base__url__:
+    for env_var, mappers in PLATFORM_URL_MAPPINGS.items():
+        env_value = os.getenv(env_var)
+        if env_value:
+            __base__url__ = mappers(env_value)  # type: ignore[no-untyped-call]
+            break
 
 
 def get_project_url_by_label(prefix: str) -> str:
@@ -47,7 +67,6 @@ def get_project_url_by_label(prefix: str) -> str:
     for url_entry in metadata.metadata(__project_name__).get_all("Project-URL", []):
         if url_entry.startswith(prefix):
             return str(url_entry.split(", ", 1)[1])
-
     return ""
 
 

oe_python_template_example-0.4.2/src/oe_python_template_example/utils/_gui.py

@@ -0,0 +1,174 @@
+import platform
+from abc import ABC, abstractmethod
+from pathlib import Path
+from types import EllipsisType
+
+from nicegui import app, events, ui
+from nicegui import native as native_app
+
+from ._constants import __project_name__
+from ._di import locate_subclasses
+from ._log import get_logger
+
+logger = get_logger(__name__)
+
+
+class BasePageBuilder(ABC):
+    """Base class for all page builders."""
+
+    @staticmethod
+    @abstractmethod
+    def register_pages() -> None:
+        """Register pages."""
+
+
+def gui_register_pages() -> None:
+    """Register pages.
+
+    This function is called by the GUI to register all pages.
+    """
+    page_builders = locate_subclasses(BasePageBuilder)
+    for page_builder in page_builders:
+        page_builder.register_pages()
+
+
+def gui_run(  # noqa: PLR0913, PLR0917
+    native: bool = True,
+    show: bool = False,
+    host: str | None = None,
+    port: int | None = None,
+    title: str = __project_name__,
+    icon: str = "",
+    watch: bool = False,
+    with_api: bool = False,
+) -> None:
+    """Start the GUI.
+
+    Args:
+        native: Whether to run the GUI in native mode.
+        show: Whether to show the GUI.
+        host: Host to run the GUI on.
+        port: Port to run the GUI on.
+        title: Title of the GUI.
+        icon: Icon for the GUI.
+        watch: Whether to watch for changes and reload the GUI.
+        with_api: Whether to mount the API.
+
+    Raises:
+        ValueError: If with_notebook is True but notebook_path is None.
+    """
+    if with_api:
+        from ..api import api  # noqa: PLC0415, TID252
+
+        app.mount("/api", api)
+
+    gui_register_pages()
+    ui.run(
+        title=title,
+        favicon=icon,
+        native=native,
+        reload=watch,
+        dark=False,
+        host=host,
+        port=port or native_app.find_open_port(),
+        frameless=False,
+        show_welcome_message=True,
+        show=show,
+    )
+
+
+class GUILocalFilePicker(ui.dialog):
+    def __init__(
+        self,
+        directory: str,
+        *,
+        upper_limit: str | EllipsisType | None = ...,
+        multiple: bool = False,
+        show_hidden_files: bool = False,
+    ) -> None:
+        """Local File Picker.
+
+        A simple file picker that allows selecting files from the local filesystem where NiceGUI is running.
+
+        Args:
+            directory: The directory to start in.
+            upper_limit: The directory to stop at. None for no limit, default is same as starting directory.
+            multiple: Whether to allow multiple files to be selected.
+            show_hidden_files: Whether to show hidden files.
+        """
+        super().__init__()
+
+        self.path = Path(directory).expanduser()
+        if upper_limit is None:
+            self.upper_limit = None
+        elif upper_limit is ...:
+            self.upper_limit = Path(directory).expanduser()
+        else:
+            self.upper_limit = Path(upper_limit).expanduser()
+        self.show_hidden_files = show_hidden_files
+
+        with self, ui.card():
+            self.add_drives_toggle()
+            self.grid = (
+                ui.aggrid(
+                    {
+                        "columnDefs": [{"field": "name", "headerName": "File"}],
+                        "rowSelection": "multiple" if multiple else "single",
+                    },
+                    html_columns=[0],
+                )
+                .classes("w-96")
+                .on("cellDoubleClicked", self.handle_double_click)
+            )
+            with ui.row().classes("w-full justify-end"):
+                ui.button("Cancel", on_click=self.close).props("outline").mark("BUTTON_CANCEL")
+                ui.button("Ok", on_click=self._handle_ok).mark("BUTTON_OK")
+        self.update_grid()
+
+    def add_drives_toggle(self) -> None:
+        if platform.system() == "Windows":
+            import win32api  # noqa: PLC0415
+
+            drives = win32api.GetLogicalDriveStrings().split("\000")[:-1]
+            self.drives_toggle = ui.toggle(drives, value=drives[0], on_change=self.update_drive)
+
+    def update_drive(self) -> None:
+        self.path = Path(self.drives_toggle.value).expanduser()
+        self.update_grid()
+
+    def update_grid(self) -> None:
+        paths = list(self.path.glob("*"))
+        if not self.show_hidden_files:
+            paths = [p for p in paths if not p.name.startswith(".")]
+        paths.sort(key=lambda p: p.name.lower())
+        paths.sort(key=lambda p: not p.is_dir())
+
+        self.grid.options["rowData"] = [
+            {
+                "name": f"📁 <strong>{p.name}</strong>" if p.is_dir() else p.name,
+                "path": str(p),
+            }
+            for p in paths
+        ]
+        if (self.upper_limit is None and self.path != self.path.parent) or (
+            self.upper_limit is not None and self.path != self.upper_limit
+        ):
+            self.grid.options["rowData"].insert(
+                0,
+                {
+                    "name": "📁 <strong>..</strong>",
+                    "path": str(self.path.parent),
+                },
+            )
+        self.grid.update()
+
+    def handle_double_click(self, e: events.GenericEventArguments) -> None:
+        self.path = Path(e.args["data"]["path"])
+        if self.path.is_dir():
+            self.update_grid()
+        else:
+            self.submit([str(self.path)])
+
+    async def _handle_ok(self) -> None:
+        rows = await self.grid.get_selected_rows()
+        self.submit([r["path"] for r in rows])

oe_python_template_example-0.4.2/src/oe_python_template_example/utils/_notebook.py

@@ -0,0 +1,61 @@
+"""System service."""
+
+from collections.abc import Callable
+
+import marimo
+from fastapi import APIRouter, FastAPI
+
+from ..constants import NOTEBOOK_APP, NOTEBOOK_FOLDER  # noqa: TID252
+from ._health import Health
+from ._log import get_logger
+
+logger = get_logger(__name__)
+
+
+def register_health_endpoint(router: APIRouter) -> Callable[..., Health]:
+    """Register health endpoint to the given router.
+
+    Args:
+        router: The router to register the health endpoint to.
+
+    Returns:
+        Callable[..., Health]: The health endpoint function.
+    """
+
+    @router.get("/healthz")
+    def health_endpoint() -> Health:
+        """Determine health of the app.
+
+        Returns:
+            Health: Health.
+        """
+        return Health(status=Health.Code.UP)
+
+    return health_endpoint
+
+
+def create_marimo_app() -> FastAPI:
+    """Create a FastAPI app with marimo notebook server.
+
+    Returns:
+        FastAPI: FastAPI app with marimo notebook server.
+
+    Raises:
+        ValueError: If the notebook directory does not exist.
+    """
+    server = marimo.create_asgi_app(include_code=True)
+    if not NOTEBOOK_FOLDER.is_dir():
+        logger.critical(
+            "Directory %s does not exist. Please create the directory and add your notebooks.",
+            NOTEBOOK_FOLDER,
+        )
+        message = f"Directory {NOTEBOOK_FOLDER} does not exist. Please create and add your notebooks."
+        raise ValueError(message)
+    server = server.with_app(path="/", root=str(NOTEBOOK_APP))
+    #            .with_dynamic_directory(path="/dashboard", directory=str(self._settings.directory))
+    app = FastAPI()
+    router = APIRouter(tags=["marimo"])
+    register_health_endpoint(router)
+    app.include_router(router)
+    app.mount("/", server.build())
+    return app

oe_python_template_example-0.4.0/src/oe_python_template_example/cli.py

@@ -1,22 +0,0 @@
-"""CLI (Command Line Interface) of OE Python Template Example."""
-
-import sys
-
-import typer
-
-from .constants import MODULES_TO_INSTRUMENT
-from .utils import __version__, boot, console, get_logger, prepare_cli
-
-boot(MODULES_TO_INSTRUMENT)
-logger = get_logger(__name__)
-
-cli = typer.Typer(help="Command Line Interface of ")
-prepare_cli(cli, f"🧠 OE Python Template Example v{__version__} - built with love in Berlin 🐻")
-
-if __name__ == "__main__":  # pragma: no cover
-    try:
-        cli()
-    except Exception as e:  # noqa: BLE001
-        logger.critical("Fatal error occurred: %s", e)
-        console.print(f"Fatal error occurred: {e}", style="error")
-        sys.exit(1)

oe_python_template_example-0.4.0/src/oe_python_template_example/constants.py

@@ -1,7 +0,0 @@
-"""Constants for the OE Python Template Example."""
-
-API_VERSIONS = {
-    "v1": "1.0.0",
-    "v2": "2.0.0",
-}
-MODULES_TO_INSTRUMENT = ["oe_python_template_example.hello"]