merge feature/2/create-first-version

.github/workflows/build.yaml

@@ -0,0 +1,38 @@
+---
+# build.yaml
+#
+# GitHub Action Build Workflow CI/CD configuration.
+#
+# author  : stefan schablowski
+# contact : stefan.schablowski@desmodyne.com
+# created : 2025-03-23
+
+
+# uv > Using uv in GitHub Actions:
+#   https://docs.astral.sh/uv/guides/integration/github
+
+
+name: Build
+on:   [push]
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: 0.6.9
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: code/python/pyproject.toml
+
+      - name: Run `uv build`
+        run: uv build --directory code/python

.github/workflows/publish.yaml

@@ -0,0 +1,49 @@
+---
+# publish.yaml
+#
+# GitHub Action Publish Workflow CI/CD configuration.
+#
+# author  : stefan schablowski
+# contact : stefan.schablowski@desmodyne.com
+# created : 2025-03-23
+
+
+# taken from "Step 3" at
+#   https://medium.com/@blackary/ ...
+#    ... publishing-a-python-package-from-github-to-pypi-in-2024-a6fb8635d45d
+
+
+name: Publish
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    environment:
+      name: pypi
+      url:  https://pypi.org/p/keyring-insecure-backend
+    name: publish
+    permissions:
+      id-token: write
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: 0.6.9
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: code/python/pyproject.toml
+
+      - name: Run `uv build`
+        run: uv build --directory code/python
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/sync.yaml

@@ -0,0 +1,37 @@
+---
+# sync.yaml
+#
+# GitHub Action Sync Workflow CI/CD configuration.
+#
+# author  : stefan schablowski
+# contact : stefan.schablowski@desmodyne.com
+# created : 2025-03-23
+
+
+# see ./build.yaml
+
+
+name: Sync
+on:   [push]
+
+jobs:
+  sync:
+    name: sync
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: 0.6.9
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: code/python/pyproject.toml
+
+      - name: Run `uv sync`
+        run: uv sync --directory code/python

.vscode/settings.json

@@ -0,0 +1,51 @@
+// settings.json
+//
+// Visual Studio Code workspace settings
+//
+// author  : stefan schablowski
+// contact : stefan.schablowski@desmodyne.com
+// created : 2021-09-25
+
+
+// NOTE: file suffix says .json, but actual file format is some proprietary
+// Microsoft mess: mostly a json file, but with JavaScript-style (?) comments;
+// can't be read/modified or even displayed properly by regular json tools :-/
+
+// NOTE: VS Code user ./. workspace settings:
+// + user settings are stored in
+//     $HOME/Library/Application Support/Code/User/settings.json
+// + workspace settings are stored in
+//     .../.vscode/settings.json
+// + workspace settings take precedence over user settings:
+//   https://code.visualstudio.com/docs/getstarted/settings#_settings-precedence
+//
+// TODO: review VS Code settings, move from user to workspace settings
+// TODO: review VS Code analysis / linting / etc. settings:
+//   https://code.visualstudio.com/docs/python/settings-reference
+
+
+{
+  // make auto indentation less dumb
+  "editor.autoIndent": "advanced",
+  // display a vertical line at 80 characters
+  "editor.rulers":     [ 80 ],
+
+  // remove trailing whitespace upon saving files
+  "files.trimTrailingWhitespace": true,
+
+  // pylance > pyright settings
+  "python.analysis.diagnosticMode":   "workspace",
+  "python.analysis.exclude": [
+    "attic",
+    "code/python/.venv",
+    "doc/python/.venv",
+    "tmp"
+  ],
+  "python.analysis.typeCheckingMode": "strict",
+
+  // NOTE: one single argument is probably not worth creating a shell frontend
+  "shellcheck.customArgs": [
+    "--enable=all",
+    "-x"
+  ]
+}

code/python/keyring_insecure_backend/ConfFileModel.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python
+# encoding: utf-8
+
+"""
+ConfFileModel.py
+
+Insecure Keyring Backend configuration file data model.
+
+author  : stefan schablowski
+contact : stefan.schablowski@desmodyne.com
+created : 2025-03-11
+"""
+
+
+from pathlib import Path
+
+# https://pypi.org/project/pydantic
+from pydantic import BaseModel, ConfigDict
+
+from .ConfRichLoggingModel import ConfRichLoggingModel
+
+
+# -----------------------------------------------------------------------------
+# public types
+
+class ConfFileModel(BaseModel):
+    """
+    Pydantic model that defines configuration file attributes.
+    """
+
+    model_config = ConfigDict(extra='forbid')
+    logging:           ConfRichLoggingModel
+    path_to_data_file: Path

code/python/keyring_insecure_backend/ConfLoggingModel.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python
+# encoding: utf-8
+
+"""
+ConfLoggingModel.py
+
+Python logging configuration data model.
+
+author  : stefan schablowski
+contact : stefan.schablowski@desmodyne.com
+created : 2025-03-18
+"""
+
+
+# python > logging > configuration:
+#   https://docs.python.org/3/library/logging.config.html
+# python > logging > configuration > data model:
+#   https://docs.python.org/3/library/logging.config.html#dictionary-schema-details
+
+
+# TODO: add validators to ensure logging objects reference valid other objects
+# TODO: support user-defined objects ?
+#   https://docs.python.org/3/library/logging.config.html#user-defined-objects
+
+
+from typing import Any, Dict, List, Literal, Optional
+
+# https://pypi.org/project/pydantic
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# -----------------------------------------------------------------------------
+# supporting types
+
+class ConfLoggingFilterModel(BaseModel):
+    """
+    Pydantic helper model that defines logging filter conf attrbutes.
+    """
+
+    # https://docs.python.org/3/library/logging.html#logging.Filter
+
+    model_config = ConfigDict(extra='forbid')
+    name:          Optional[str]   = None
+
+
+class ConfLoggingFormatterModel(BaseModel):
+    """
+    Pydantic helper model that defines logging formatter conf attrbutes.
+    """
+
+    # https://docs.python.org/3/library/logging.html#logging.Formatter
+
+    model_config = ConfigDict(extra='forbid')
+    # NOTE: 'class' obviously is a python keyword; use alias to work around:
+    #   https://stackoverflow.com/a/70584815
+    #   https://docs.pydantic.dev/latest/concepts/fields/#field-aliases
+    # TODO: restrict to dot notation / valid class names ?
+    class_:        Optional[str]  = Field(alias = 'class', default = None)
+    # TODO: verify this is a valid date format ?
+    datefmt:       Optional[str]               = None
+    defaults:      Optional[Dict[str, Any]]    = None
+    # TODO: verify this is a valid log message format ?
+    format:        Optional[str]               = None
+    # TODO: restrict to '%', '{' or '$'
+    style:         Optional[str]               = None
+    # NOTE: 'validate' is a BaseModel method; see class_ above
+    validate_:     Optional[bool] = Field(alias = 'validate', default = None)
+
+
+class ConfLoggingHandlerModel(BaseModel):
+    """
+    Pydantic helper model that defines logging handler conf attrbutes.
+    """
+
+    # https://docs.python.org/3/library/logging.html#logging.Handler
+    # however, most useful info is in the handlers section at
+    #   https://docs.python.org/3/library/logging.config.html ...
+    #    ... #dictionary-schema-details
+
+    # from above page:
+    # > All other keys are passed through as keyword
+    # > arguments to the handler’s constructor.
+    # --> do not forbid extra attributes as usual
+    model_config = ConfigDict(extra='allow')
+    class_:        Optional[str]  = Field(alias = 'class', default = None)
+    filters:       Optional[List[str]] = None
+    formatter:     Optional[str]       = None
+    # TODO: restrict to python log levels (?) in upper case (?)
+    level:         Optional[str]       = None
+
+
+class ConfLoggingLoggerModel(BaseModel):
+    """
+    Pydantic helper model that defines logging logger conf attrbutes.
+    """
+
+    # https://docs.python.org/3/library/logging.html#logging.Logger
+    # however, most useful info is in the loggers section at
+    #   https://docs.python.org/3/library/logging.config.html ...
+    #    ... #dictionary-schema-details and at
+    #   https://docs.python.org/3/library/logging.config.html ...
+    #    ... #object-connections
+
+    model_config = ConfigDict(extra='forbid')
+    filters:       Optional[List[str]] = None
+    handlers:      Optional[List[str]] = None
+    level:         Optional[str]       = None
+    propagate:     Optional[bool]      = None
+
+
+# -----------------------------------------------------------------------------
+# public types
+
+class ConfLoggingModel(BaseModel):
+    """
+    Pydantic model that defines python logging configuration attributes.
+    """
+
+    # TODO: python's interpretation of 'optional' seems inconsistent:
+    # + python logging configuration docs say attributes are optional:
+    #     https://docs.python.org/3/library/logging.config.html ...
+    #      ... #dictionary-schema-details > 'All other keys are optional'
+    # + from python typing docs at
+    #     https://docs.python.org/3/library/typing.html#typing.Optional:
+    #   > Optional[X] is equivalent to X | None (or Union[X, None]).
+    # however, using `Optional[...] = None` below as in e.g.
+    #   formatters:    Optional[Dict[str, ConfLoggingFormatterModel]]  = None
+    # fails because python code seems to expect empty dictionaries:
+    #     File ".../lib/python3.13/logging/config.py", line 581, in configure
+    #       for name in formatters:
+    #                   ^^^^^^^^^^
+    #   TypeError: 'NoneType' object is not iterable
+    # workaround: use {} as default value instead of None
+
+    model_config = ConfigDict(extra='forbid')
+    # NOTE: attribute order not alphabetical, but follows documentation at
+    #   https://docs.python.org/3/library/logging.config.html ...
+    #    ... #dictionary-schema-details
+    version:       Literal[1]
+    formatters:    Optional[Dict[str, ConfLoggingFormatterModel]]  = {}
+    filters:       Optional[Dict[str, ConfLoggingFilterModel]]     = {}
+    handlers:      Optional[Dict[str, ConfLoggingHandlerModel]]    = {}
+    loggers:       Optional[Dict[str, ConfLoggingLoggerModel]]     = {}
+    # TODO: from https://docs.python.org/3/library/logging.config.html:
+    #   > configuration will be as for any logger,
+    #   > except that the propagate setting will not be applicable
+    root:          Optional[ConfLoggingLoggerModel]                = None
+    incremental:   Optional[bool]                                  = None
+    disable_existing_loggers:  Optional[bool]                      = None