oe-python-template-example 0.1.16__tar.gz → 0.1.18__tar.gz

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/.copier-answers.yml

@@ -1,4 +1,4 @@
-_commit: v0.5.11
+_commit: v0.5.13
 _src_path: gh:helmut-hoffer-von-ankershoffen/oe-python-template
 author_email: helmuthva@gmail.com
 author_github_username: helmut-hoffer-von-ankershoffen

oe_python_template_example-0.1.18/.github/copilot-instructions.md

@@ -0,0 +1,5 @@
+Always conform to the coding styles defined in CODE_STYLE.md in the root
+directory of this repository when generating code.
+
+Learn about tools to use in CONTRIBUTING.md in the root directory of this
+repository.

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/.vscode/settings.json

@@ -1,4 +1,7 @@
 {
+    "[jsonc]": {
+        "editor.defaultFormatter": "vscode.json-language-features"
+    },
     "files.exclude": {
         "**/__pycache__ ": true
     },
@@ -48,20 +51,23 @@
         "markdown": true,
         "scminput": true
     },
-    "github.copilot.advanced": {
-
-    },
+    "github.copilot.advanced": {},
     "github.copilot.chat.editor.temporalContext.enabled": true,
     "github.copilot.chat.edits.codesearch.enabled": true,
     "github.copilot.chat.edits.temporalContext.enabled": true,
-    "github.copilot.chat.languageContext.typescript.enabled": true,
-    "github.copilot.chat.reviewSelection.instructions": [
-
-
+    "github.copilot.chat.codeGeneration.instructions": [
+        {
+            "file": "CODE_STYLE.md"
+        },
+        {
+            "file": "CONTRIBUTING.md"
+        }
     ],
-    "github.copilot.chat.scopeSelection": true,
     "github.copilot.chat.completionContext.typescript.mode": "on",
     "github.copilot.chat.generateTests.codeLens": true,
+    "github.copilot.chat.languageContext.typescript.enabled": true,
+    "github.copilot.chat.reviewSelection.instructions": [],
+    "github.copilot.chat.scopeSelection": true,
     "github.copilot.chat.search.semanticTextResults": true,
     "sonarlint.connectedMode.project": {
         "connectionId": "helmut-hoffer-von-ankershoffen",

oe_python_template_example-0.1.18/CODE_STYLE.md

@@ -0,0 +1,287 @@
+# Code Style
+
+Author: Helmut Hoffer von Ankershoffen (@helmut-hoffer-von-ankershoffen )
+Status: Draft
+Created: 2025-03-16
+Updated: 2025-03-16
+
+This document describes the code style used in
+[oe-python-templat](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template)
+and derivatives. It defines strict requirements to be followed by all
+contributors - humans and agents - to ensure consistency and readability across
+the codebase.
+
+## Code
+
+We favor readability and maintainability over cleverness and brevity.
+
+- We always write code that is easy to read, understand, maintain, test,
+  document, deploy, use, integrate, and extend.
+- We always write code that is efficient and performant, but only if it does not
+  sacrifice readability, maintainability, and testability.
+- We always write code that is secure and does not introduce vulnerabilities.
+- We always write code that is portable and does not introduce platform-specific
+  dependencies.
+- We always write code that is compatible with the Python version indicated in
+  the .python-version file in the root of this repository.
+
+# Naming
+
+We believe that good names are essential for code readability and
+maintainability. A good name is one that is descriptive, unambiguous, and
+meaningful. It should convey the purpose and intent of the code it represents.
+
+- We take extra care to find proper names for all identifiers, including
+  variables, functions, classes, types, tests, modules, and packages. We prefer
+  descriptive names that clearly indicate the purpose and functionality of the
+  code.
+- We avoid using abbreviations, acronyms, and jargon unless they are widely
+  understood and accepted in the context of the code. We prefer full words and
+  phrases that are easy to understand.
+- We avoid using single-letter names, except for loop variables and iterators.
+- We avoid using generic names like `data`, `info`, `temp`, `foo`, `bar`, etc.
+  These names do not convey any meaning and make the code harder to read and
+  understand.
+- We avoid using names that are too long or too short. A good name should be
+  concise but descriptive. It should be long enough to convey the purpose and
+  intent of the code, but not so long that it becomes cumbersome to read and
+  write.
+- We avoid using names that are too similar or too different. A good name should
+  be unique and distinct. It should not be confused with other names in the
+  code. It should not be so different that it becomes hard to remember and
+  recognize.
+
+## Formatting
+
+We use [ruff](https://github.com/astral-sh/ruff) to format Python code
+
+- The ruff formatter adheres to the
+  [Black](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
+  code style which is [PEP 8](https://www.python.org/dev/peps/pep-0008/)
+  compliant.
+- The ruff formatter is configured to use a max line length of 120.
+- The ruff formatter is called by the lint session of nox.
+
+Beyond PEP 8 we adhere to the following naming conventions: We use the following
+conventions for Python code:
+
+- Class names: `PascalCase` - descriptive nouns that clearly indicate purpose.
+- Function/method names: `snake_case` - verb phrases that describe actions.
+- Variables/attributes: `snake_case` - descriptive nouns/noun phrases.
+- Constants: `UPPER_SNAKE_CASE`.
+- Private members: Prefix with single underscore `_private_attribute`.
+- "True" private members: Prefix with double underscore `__truly_private`.
+- Type variables: `CamelCase` with short, descriptive names (e.g., `T`, `KT`,
+  `VT`).
+- Boolean variables/functions: Prefix with `is_`, `has_`, `should_`, etc.
+- Interface classes: Suffix with `Interface` or `Protocol`.
+
+## Linting and type checking
+
+We use [ruff](https://github.com/astral-sh/ruff) to lint Python code
+
+- All linting rules are enabled except those explicitly disabled in
+  pyproject.toml
+- The ruff linter is called by the lint session of nox.
+
+We use [mypy](https://mypy.readthedocs.io/) for static type checking of Python
+code.
+
+- mypy is configured to use the `strict` mode in pyproject.toml
+- mypy is called by the lint session of nox.
+
+## Documentation
+
+We use docstrings to document the purpose of modules, classes, types, functions,
+its parameters and returns
+
+- We use Google style docstrings with typed Args and Returns.
+- We comment complex code and algorithms to explain their purpose and
+  functionality.
+- We leave references with deep links in code to external documentation,
+  standards, and specifications.
+
+We provide an auto-generated OpenAPI specification and reference documentation.
+
+We generate the final documentation using Sphinx and publish it to readthedocs.
+
+- Generation of documentation is called by the docs session of nox
+
+## Testing
+
+We use [pytest](https://docs.pytest.org/en/stable/) for testing Python code.
+
+- Tests are defined in the `tests/` directory
+- We use pytest fixtures to set up test data and state
+- We leverage several pytest plugins:
+  - `pytest-asyncio` for testing async code
+  - `pytest-cov` for coverage reporting
+  - `pytest-docker` for integration tests with containers
+  - `pytest-env` for environment variable management
+  - `pytest-regressions` for regression testing
+  - `pytest-xdist` for parallel test execution
+- Test execution is automated through the nox test session which runs across the
+  Python versions indicated in the `pyproject.toml`.
+
+Our test coverage is measured using `pytest-cov` and reported in the CI
+pipeline.
+
+- We aim for 100% unit coverage on all code paths, including error handling and
+  edge cases.
+- We fail the CI if unit test coverage drops below 85%.
+
+Apart from unit tests we provide integration tests and end-to-end tests:
+
+- We smoke test as part of the CI/CD pipeline.
+- We facilitate exploratory testing to ensure comprehensive coverage.
+- We use `pytest-docker` for integration tests with containers.
+
+## Error Handling
+
+We use structured, explicit error handling that enables effective debugging and
+monitoring:
+
+- Use specific exception classes instead of generic ones.
+- Include contextual information in exception messages.
+- Log exceptions with appropriate severity levels and context.
+- Gracefully degrade functionality when possible rather than failing completely.
+- Use type hints to catch type errors at compile time rather than runtime.
+- Design errors to be actionable for both users and developers.
+
+## Logging
+
+We log information to help with debugging and monitoring:
+
+- Use structured logging with consistent fields across all log entries.
+- Include correlation IDs for tracking requests across components.
+- Log at appropriate levels (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+- Be mindful of PII and sensitive data in logs, using obfuscation where needed.
+- Consider log volume and performance impact in production environments.
+
+## Performance Considerations
+
+We consider performance from the early design stage, not as an afterthought:
+
+- Consider algorithmic complexity (Big O notation) for all operations.
+- Prefer lazy evaluation when dealing with large datasets.
+- Use appropriate data structures for specific access patterns.
+- Be mindful of memory usage, especially for long-running processes.
+- Consider profiling for critical paths and potential bottlenecks.
+- Document performance characteristics and assumptions.
+- Write benchmarks for performance-critical code.
+- Design for horizontal scaling from the beginning.
+- Use asynchronous operations appropriately for I/O-bound tasks.
+- Consider caching strategies when appropriate.
+
+## API Design
+
+For both internal and external APIs we follow the principle of least surprise.
+
+- We maintain backward compatibility whenever possible. If not possible we add a
+  new major version of the API.
+- Implement proper versioning for breaking changes.
+- Document error conditions, return values, and side effects.
+- Design for testability and mockability.
+- Provide sensible defaults while allowing for configuration.
+- Follow RESTful principles for HTTP APIs.
+- Use consistent parameter ordering and naming.
+- Implement proper validation with helpful error messages.
+- Consider rate limiting and circuit breaking for external services.
+
+## Security
+
+We prioritize security at every stage of development to prevent vulnerabilities
+and protect our users.
+
+- Follow the principle of least privilege for all operations and access
+  controls.
+- Never store secrets (API keys, passwords, tokens) in code repositories.
+  - Use environment variables or dedicated secret management services.
+  - Code is checked via `detect-secrets` pre-commit hook to prevent accidental
+    commits of secrets.
+
+We implement proper input validation and sanitization for all external inputs
+via [pydantic](https://pydantic-docs.helpmanual.io/):
+
+- Validate inputs as early as possible in the data flow.
+
+We handle authentication and authorization correctly:
+
+- Use industry-standard authentication protocols (OAuth, JWT).
+- Separate authentication from authorization logic.
+- Implement proper session management with secure cookies.
+- Protect against common vulnerabilities:
+  - SQL Injection: Use parameterized queries or ORM frameworks.
+  - XSS: Apply proper output encoding.
+  - CSRF: Implement anti-CSRF tokens for state-changing operations.
+  - SSRF: Validate and restrict URL destinations.
+  - Command Injection: Avoid direct system command execution where possible.
+- Implement proper error handling that doesn't leak sensitive information.
+- Use secure defaults and fail closed (secure) rather than open (insecure).
+
+We apply the principle of defense in depth:
+
+- Don't rely on a single security control.
+- Implement multiple layers of protection.
+- Document security considerations in code and design documents.
+- Write security-focused tests:
+  - Test for security property violations.
+  - Test error cases and edge conditions.
+  - Test for resource exhaustion scenarios.
+- Apply proper rate limiting and throttling to prevent abuse.
+- For cryptographic operations:
+  - Use established libraries, not custom implementations.
+  - Follow current best practices for algorithm selection and key management.
+  - Be aware of the limitations of cryptographic primitives.
+- Regularly run security-focused static analysis tools as part of CI/CD:
+  - CodeQL analysis (via GitHub Actions)
+  - SonarCloud checks for security vulnerabilities
+
+Our security posture is defined in [SECURITY.md](SECURITY.md).
+
+## Dependency Management
+
+We use modern dependency management practices:
+
+- [uv](https://github.com/astral-sh/uv) for fast, reliable package installation
+  and environment management
+- Dependency version locking via uv.lock file
+- Regular dependency auditing:
+  - Security auditing via `pip-audit`
+  - License compliance checks via `pip-licenses`
+  - SBOM generation via `cyclonedx-py`
+
+Dependency updates are automated via Dependabot and Renovate to ensure we stay
+current with security patches.
+
+## Versioning
+
+We use [semantic versioning](https://semver.org/) for versioning our releases:
+
+- MAJOR: Breaking changes
+- MINOR: New features, non-breaking changes
+- PATCH: Bug fixes, non-breaking changes
+
+Our API versioning follows the same principles, with major versions indicated in
+the URL (e.g., /api/v1/resource) and the full version provided as part of the
+OpenAPI pecification.
+
+## Conventional Commits
+
+Our commit messages follow conventional commits format.
+
+- We use 'feat','fix','chore','docs','style','refactor','test' prefixes and
+  components in parentheses. E.g.
+  `feat(api): add new endpoint for user registration`.
+
+## Guidance for AI Pair Programming
+
+When generating code with AI assistance:
+
+- AI-generated code must follow all style guidelines in this document.
+- Always review AI-generated code for correctness, security implications, and
+  adherence to project patterns.
+- Use AI to generate tests alongside implementation code.
+- Request explanations for complex algorithms or patterns in the generated code.
+- Remember that AI should augment, not replace, human judgment about code
+  quality and design decisions.

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/CONTRIBUTING.md

@@ -139,6 +139,8 @@ uv run nox -s update_from_template
 
 ## Pull Request Guidelines
 
+- Before starting to write code read the [code style guide](CODE_STYLE.md) document for mandatory coding style
+  guidelines.
 - **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.
 - **Squash Commits:** Before submitting a pull request, please squash your commits into a single commit.
 - **Branch Naming:** Use descriptive branch names like `feature/your-feature` or `fix/issue-number`.

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oe-python-template-example
-Version: 0.1.16
+Version: 0.1.18
 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,6 +59,9 @@ Requires-Dist: marimo>=0.11.19; extra == 'examples'
 Requires-Dist: streamlit>=1.43.2; extra == 'examples'
 Description-Content-Type: text/markdown
 
+
+[//]: # (README.md generated from docs/partials/README_*.md)
+
 # 🧠 OE Python Template Example
 
 [![License](https://img.shields.io/github/license/helmut-hoffer-von-ankershoffen/oe-python-template-example?logo=opensourceinitiative&logoColor=3DA639&labelColor=414042&color=A41831)
@@ -136,10 +139,13 @@ uvx oe-python-template-example serve --port=4711 # serves webservice API on port
 ```
 
 Notes:
-* The API is versioned, mounted at `/api/v1` resp. `/api/v2`
-* While serving the webservice 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.
-* Interactive documentation is provided at [http://127.0.0.1:8000/api/docs](http://127.0.0.1:8000/api/docs)
 
+- The API is versioned, mounted at `/api/v1` resp. `/api/v2`
+- While serving the webservice 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.
+- Interactive documentation is provided at
+  [http://127.0.0.1:8000/api/docs](http://127.0.0.1:8000/api/docs)
 
 The CLI provides extensive help:
 

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/README.md

@@ -1,3 +1,6 @@
+
+[//]: # (README.md generated from docs/partials/README_*.md)
+
 # 🧠 OE Python Template Example
 
 [![License](https://img.shields.io/github/license/helmut-hoffer-von-ankershoffen/oe-python-template-example?logo=opensourceinitiative&logoColor=3DA639&labelColor=414042&color=A41831)
@@ -75,10 +78,13 @@ uvx oe-python-template-example serve --port=4711 # serves webservice API on port
 ```
 
 Notes:
-* The API is versioned, mounted at `/api/v1` resp. `/api/v2`
-* While serving the webservice 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.
-* Interactive documentation is provided at [http://127.0.0.1:8000/api/docs](http://127.0.0.1:8000/api/docs)
 
+- The API is versioned, mounted at `/api/v1` resp. `/api/v2`
+- While serving the webservice 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.
+- Interactive documentation is provided at
+  [http://127.0.0.1:8000/api/docs](http://127.0.0.1:8000/api/docs)
 
 The CLI provides extensive help:
 

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/SECURITY.md

@@ -47,6 +47,14 @@ We follow these security best practices:
 - Automated CI/CD pipelines including security checks
 - Adherence to Python security best practices
 
+We promote security awareness among contributors and users
+
+- We indicate security as a priority in our
+  [code style guide](CODE_STYLE.md), to be followed by human and agentic
+  contributors as mandatory
+- We publish our security posture in SECURITY.md (this document), encouraring
+  users to report vulnerabilities.
+
 ## Security Compliance
 
 For questions about security compliance or for more details about our security practices, please contact helmuthva@gmail.com.

oe_python_template_example-0.1.18/VERSION

@@ -0,0 +1 @@
+0.1.18

oe_python_template_example-0.1.16/_readme_main.md → oe_python_template_example-0.1.18/docs/partials/README_main.md

@@ -33,10 +33,13 @@ uvx oe-python-template-example serve --port=4711 # serves webservice API on port
 ```
 
 Notes:
-* The API is versioned, mounted at `/api/v1` resp. `/api/v2`
-* While serving the webservice 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.
-* Interactive documentation is provided at [http://127.0.0.1:8000/api/docs](http://127.0.0.1:8000/api/docs)
 
+- The API is versioned, mounted at `/api/v1` resp. `/api/v2`
+- While serving the webservice 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.
+- Interactive documentation is provided at
+  [http://127.0.0.1:8000/api/docs](http://127.0.0.1:8000/api/docs)
 
 The CLI provides extensive help:
 

oe_python_template_example-0.1.18/docs/source/code-style.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../../CODE_STYLE.md

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/docs/source/conf.py

@@ -29,7 +29,7 @@ extensions = [
 project = "oe-python-template-example"
 author = "Helmut Hoffer von Ankershoffen"
 copyright = f" (c) 2025-{datetime.now(UTC).year}, {author}"  # noqa: A001
-version = "0.1.16"
+version = "0.1.18"
 release = version
 github_username = "helmut-hoffer-von-ankershoffen"
 github_repository = "oe-python-template-example"

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/docs/source/index.rst

@@ -14,9 +14,10 @@
    api_v1
    api_v2
    reference
-   release-notes
    security
+   release-notes
    contributing
+   code-style
 
 .. sidebar-links::
    :caption: Links

oe_python_template_example-0.1.18/docs/source/main.rst

@@ -0,0 +1,2 @@
+.. mdinclude:: ../partials/README_main.md
+:start-line: 0

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/noxfile.py

@@ -56,10 +56,11 @@ def docs(session: nox.Session) -> None:
     """Build documentation and concatenate README."""
     _setup_venv(session)
     # Concatenate README files
-    header = Path("_readme_header.md").read_text(encoding="utf-8")
-    main = Path("_readme_main.md").read_text(encoding="utf-8")
-    footer = Path("_readme_footer.md").read_text(encoding="utf-8")
-    readme_content = f"{header}\n\n{main}\n\n{footer}"
+    preamble = "\n[//]: # (README.md generated from docs/partials/README_*.md)\n\n"
+    header = Path("docs/partials/README_header.md").read_text(encoding="utf-8")
+    main = Path("docs/partials/README_main.md").read_text(encoding="utf-8")
+    footer = Path("docs/partials/README_footer.md").read_text(encoding="utf-8")
+    readme_content = f"{preamble}{header}\n\n{main}\n\n{footer}"
     Path("README.md").write_text(readme_content, encoding="utf-8")
     # Dump openapi schema to file
     with Path("docs/source/_static/openapi_v1.yaml").open("w", encoding="utf-8") as f:

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oe-python-template-example"
-version = "0.1.16"
+version = "0.1.18"
 description = "🧠 Example project scaffolded and kept up to date with OE Python Template (oe-python-template)."
 readme = "README.md"
 authors = [
@@ -242,7 +242,7 @@ source = ["src/"]
 
 
 [tool.bumpversion]
-current_version = "0.1.16"
+current_version = "0.1.18"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/sonar-project.properties

@@ -1,6 +1,6 @@
 sonar.projectKey=helmut-hoffer-von-ankershoffen_oe-python-template-example
 sonar.organization=helmut-hoffer-von-ankershoffen
-sonar.projectVersion=0.1.16
+sonar.projectVersion=0.1.18
 sonar.projectDescription=🧠 Example project scaffolded and kept up to date with OE Python Template (oe-python-template).
 sonar.links.homepage=https://oe-python-template-example.readthedocs.io/en/latest/
 sonar.links.scm=https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template-example

{oe_python_template_example-0.1.16 → oe_python_template_example-0.1.18}/uv.lock

@@ -2075,7 +2075,7 @@ wheels = [
 
 [[package]]
 name = "oe-python-template-example"
-version = "0.1.16"
+version = "0.1.18"
 source = { editable = "." }
 dependencies = [
     { name = "fastapi", extra = ["all", "standard"] },

oe_python_template_example-0.1.16/VERSION

@@ -1 +0,0 @@
-0.1.16

oe_python_template_example-0.1.16/docs/source/main.rst

@@ -1,2 +0,0 @@
-.. mdinclude:: ../../_readme_main.md
-    :start-line: 0