bitranox-template-py-lib 1.0.0__tar.gz

bitranox_template_py_lib-1.0.0/.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+  "image": "mcr.microsoft.com/devcontainers/python:3.13",
+
+  "postCreateCommand": "bash -lc '\nPY=/usr/local/bin/python;\n$PY -m pip install -U pip && \\\n$PY -m pip install ipykernel && \\\n$PY -m pip install -e . && \\\n# register kernel using this exact interpreter\n$PY -m ipykernel install --name=python3 --display-name=\"Python 3 (3.13)\" --user && \\\n# patch the notebook to point to the python3 kernelspec (VS Code will bind to /usr/local/bin/python)\n$PY - <<\"PY\"\nimport json, pathlib\np = pathlib.Path(\"notebooks/Quickstart.ipynb\")\nif p.exists():\n    nb = json.loads(p.read_text(encoding=\"utf-8\"))\n    md = nb.setdefault(\"metadata\", {})\n    md[\"kernelspec\"] = {\n        \"name\": \"python3\",\n        \"display_name\": \"Python 3 (3.13)\",\n        \"language\": \"python\"\n    }\n    md[\"language_info\"] = {\"name\": \"python\"}\n    p.write_text(json.dumps(nb, ensure_ascii=False, indent=1), encoding=\"utf-8\")\n    print(\"Pinned kernelspec to python3 in\", p)\nelse:\n    print(\"Notebook not found:\", p)\nPY'\n",
+
+  "customizations": {
+    "vscode": {
+      "extensions": ["ms-toolsai.jupyter", "ms-python.python"],
+      "settings": {
+        "workbench.startupEditor": "none",
+        "jupyter.alwaysTrustNotebooks": true,
+        "jupyter.kernelPickerType": "OnlyRecommended",
+        "python.defaultInterpreterPath": "/usr/local/bin/python"
+      }
+    },
+    "codespaces": {
+      "openFiles": ["README.md"]
+    }
+  },
+
+  "postAttachCommand": "bash -lc 'if [ -f notebooks/Quickstart.ipynb ]; then code -r notebooks/Quickstart.ipynb; fi'"
+}

bitranox_template_py_lib-1.0.0/.devcontainer/settings.json

@@ -0,0 +1,6 @@
+{
+  "python.defaultInterpreterPath": "/usr/local/bin/python3.13",
+  "jupyter.alwaysTrustNotebooks": true,
+  "jupyter.kernelPickerType": "OnlyRecommended",
+  "jupyter.askForKernelRestart": false
+}

bitranox_template_py_lib-1.0.0/.env.example

@@ -0,0 +1,11 @@
+# Copy to .env and fill values as needed.
+
+# Codecov upload token (required for private repos; optional for public repos)
+CODECOV_TOKEN=
+
+# PyPI API token for release workflow (.github/workflows/release.yml)
+# Format: pypi-AgENdGVzdC5weXBpLm9yZwIk...
+PYPI_API_TOKEN=
+
+# Optional: GitHub token for API-limited tasks
+GITHUB_TOKEN=

bitranox_template_py_lib-1.0.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    allow:
+      - dependency-type: "direct"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"

bitranox_template_py_lib-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,208 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    # Run daily at 3:17 AM UTC (off-peak hours, odd minute to avoid congestion)
+    - cron: '17 3 * * *'
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        # Test against Python 3.9+ as specified in requires-python
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.x"]
+    env:
+      PYO3_USE_ABI3_FORWARD_COMPATIBILITY: "1"
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Install tomli for Python < 3.11
+        if: matrix.python == '3.9' || matrix.python == '3.10'
+        run: python -m pip install tomli
+      - name: Extract project metadata
+        shell: python
+        run: |
+          import os
+          try:
+              import tomllib
+          except ModuleNotFoundError:
+              import tomli as tomllib
+          from pathlib import Path
+
+          data = tomllib.loads(Path('pyproject.toml').read_text('utf-8'))
+          project = data['project']['name']
+          module = project.replace('-', '_')
+          dash = project.replace('_', '-')
+          scripts = list(data['project'].get('scripts', {}).keys())
+          cli_bin = scripts[0] if scripts else dash
+
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as env:
+              env.write(f"PROJECT_NAME={project}\n")
+              env.write(f"PACKAGE_MODULE={module}\n")
+              env.write(f"CLI_BIN={cli_bin}\n")
+      - name: Install make on Windows
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          choco install -y make
+          echo "C:\\ProgramData\\chocolatey\\bin" >> $env:GITHUB_PATH
+      - name: Install journald prerequisites
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y python3-systemd
+
+      - name: Upgrade pip
+        shell: bash
+        run: python -m pip install --upgrade pip
+
+      - name: Install dev deps
+        shell: bash
+        run: |
+          uv pip install -e .[dev] --system
+
+      - name: Install Windows Event Log prerequisites
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          uv pip install pywin32 --system
+      - name: Cache ruff
+        uses: actions/cache@v4
+        with:
+          path: .ruff_cache
+          key: ruff-${{ runner.os }}-${{ hashFiles('**/*.py') }}
+          restore-keys: |
+            ruff-${{ runner.os }}-
+      - name: Cache pyright
+        uses: actions/cache@v4
+        with:
+          path: .pyright
+          key: pyright-${{ runner.os }}-py${{ matrix.python }}-${{ hashFiles('**/*.py', 'pyproject.toml') }}
+          restore-keys: |
+            pyright-${{ runner.os }}-py${{ matrix.python }}-
+            pyright-${{ runner.os }}-
+      - name: Run full test suite (lint, types, tests, coverage, codecov)
+        shell: bash
+        env:
+          TEST_VERBOSE: "1"
+        run: make test
+      - name: Build wheel/sdist
+        shell: bash
+        run: python -m build
+      - name: Verify wheel install in clean env
+        shell: bash
+        run: |
+          python -m venv .venv_wheel
+          . .venv_wheel/bin/activate 2>/dev/null || . .venv_wheel/Scripts/activate 2>/dev/null
+          pip install dist/*.whl
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+
+  pipx-uv:
+    name: pipx/uv verification (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Extract project metadata
+        shell: python
+        run: |
+          import os
+          try:
+              import tomllib
+          except ModuleNotFoundError:
+              import tomli as tomllib
+          from pathlib import Path
+
+          data = tomllib.loads(Path('pyproject.toml').read_text('utf-8'))
+          project = data['project']['name']
+          module = project.replace('-', '_')
+          dash = project.replace('_', '-')
+          scripts = list(data['project'].get('scripts', {}).keys())
+          cli_bin = scripts[0] if scripts else dash
+
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as env:
+              env.write(f"PROJECT_NAME={project}\n")
+              env.write(f"PACKAGE_MODULE={module}\n")
+              env.write(f"CLI_BIN={cli_bin}\n")
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: pipx install from wheel
+        run: |
+          python -m pip install pipx
+          pipx install dist/*.whl
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: uv tool install
+        run: |
+          uv tool install .
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+
+  notebooks:
+    name: Execute notebooks (ubuntu, Python 3.13)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install notebook runner deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install nbclient nbformat ipykernel jupyter_client
+          python -m ipykernel install --user --name python3 --display-name "Python 3"
+      - name: Execute Quickstart notebook
+        env:
+          PIP_DISABLE_PIP_VERSION_CHECK: "1"
+          PIP_NO_INPUT: "1"
+        run: |
+          python - << 'PY'
+          from pathlib import Path
+
+          import nbformat
+          from nbclient import NotebookClient
+
+          nb_path = Path('notebooks/Quickstart.ipynb')
+          if not nb_path.exists():
+              raise SystemExit(f"Notebook not found: {nb_path}")
+
+          notebook = nbformat.read(nb_path, as_version=4)
+          client = NotebookClient(
+              notebook,
+              timeout=900,
+              kernel_name='python3',
+              allow_errors=False,
+          )
+          client.execute()
+
+          out_path = Path('notebooks/Quickstart-executed.ipynb')
+          nbformat.write(notebook, out_path)
+          print(f"Executed notebook written to: {out_path}")
+          PY

bitranox_template_py_lib-1.0.0/.github/workflows/codeql.yml

@@ -0,0 +1,39 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    - cron: '0 8 * * 1'
+
+jobs:
+  analyze:
+    name: CodeQL Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

bitranox_template_py_lib-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch: {}
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+      - name: Verify PyPI token is set
+        run: |
+          if [ -z "${{ secrets.PYPI_API_TOKEN }}" ]; then
+            echo "::error title=Missing PyPI token::Set the PYPI_API_TOKEN secret in GitHub repository settings to enable PyPI publishing on releases."
+            echo "See: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions"
+            exit 1
+          fi
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Build artifacts
+        run: |
+          python -m pip install --upgrade pip
+          uv pip install build --system
+          python -m build
+      - name: Publish to PyPI
+        # Use the rolling major tag to get latest Twine/standards support (e.g., Core Metadata 2.4)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          attestations: false
+          skip-existing: true
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/*

bitranox_template_py_lib-1.0.0/.gitignore

@@ -0,0 +1,181 @@
+# ====================================
+# ROTEK SPEZIFISCH: Git commands you might run once
+# git add .gitignore && git commit -m "Ignore IDE settings"
+# git push
+# git rm -r --cached .idea
+# git commit -m "Remove .idea and add to .gitignore"
+# git push
+# alternative : BE CAREFUL: overwrites remote history
+# git push origin master --force
+
+# ====================================
+# APP
+# ====================================
+website/build/
+website/.docusaurus/
+website/node_modules/
+node_modules/
+web-local-preview/
+translation_app*.log
+translation_web*.log
+tmp_github_web_pages/
+tmp_linkcheck_web_pages/
+.eslintcache
+.vitest/
+npm-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.env.*
+!.env.example
+todo.md
+tmp_*
+.claude
+
+# ====================================
+# IDEs & Editors
+# ====================================
+# IntelliJ, PyCharm, etc.
+.idea/
+# VS Code workspace settings
+.vscode/
+*.code-workspace
+
+# ====================================
+# Python bytecode & caches
+# ====================================
+# __pycache__: compiled .pyc files at any depth
+# *.py[cod]: catches .pyc, .pyo, .pyd
+__pycache__/
+*.py[cod]
+*$py.class     # other compiled artifacts
+
+# pytest, coverage, MyPy, Hypothesis
+.pytest_cache/
+.mypy_cache/
+.pyright/
+.coverage*
+htmlcov/
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+.nox/
+
+# general cache directories (any project-level caching)
+.cache/
+.run/
+.import_linter_cache/
+
+# ====================================
+# Build & distribution artifacts
+# ====================================
+# source/package builds
+build/
+dist/
+*.egg-info/    # metadata for pip installs
+*.egg
+*.whl
+pip-wheel-metadata/
+*.manifest     # PyInstaller metadata
+*.spec         # PyInstaller spec files
+
+# Eggs, parts, wheels, sdist, etc.
+develop-eggs/
+.eggs/
+parts/
+sdist/
+wheels/
+downloads/
+var/
+
+# pip logs & installer leftovers
+pip-log.txt
+pip-delete-this-directory.txt
+.installed.cfg
+
+# ====================================
+# Virtual environments & secrets
+# ====================================
+# common venv folder names
+env/
+venv/
+ENV/
+.venv/
+# backups, alternate names
+env.bak/
+venv.bak/
+# dotenv files with credentials
+.env
+
+# ====================================
+# Project-specific & framework files
+# ====================================
+# Django logs & local overrides
+*.log
+local_settings.py
+
+# Flask instance folder
+instance/
+.webassets-cache
+
+# Scrapy cache
+.scrapy
+
+# Sphinx docs
+docs/_build/
+
+# PyBuilder output
+target/
+
+# Jupyter notebooks checkpoints
+.ipynb_checkpoints
+
+# pyenv Python version file
+.python-version
+
+# Celery beat schedule
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Spyder IDE
+.spyderproject
+.spyproject
+
+# Rope IDE
+.ropeproject
+
+# MkDocs static site folder
+/site
+
+# ====================================
+# OS-specific files
+# ====================================
+# macOS
+.DS_Store
+# Windows
+Thumbs.db
+ehthumbs.db
+
+# Archives
+*.zip
+
+# Thunderbird build artifact (created temporarily by pack script)
+sources/manifest.json
+
+# ====================================
+# Tool-specific extras
+# ====================================
+# Codecov uploader script (downloaded during local uploads)
+codecov.sh
+codecov.xml
+
+# Nix build result symlink
+result
+
+# Optional lockfiles (for alternative managers)
+poetry.lock
+pdm.lock
+uv.lock

bitranox_template_py_lib-1.0.0/.qlty/qlty.toml

@@ -0,0 +1,2 @@
+exclude_patterns = ["scripts/**"]
+test_patterns = ["tests/**"]

bitranox_template_py_lib-1.0.0/.snyk

@@ -0,0 +1,5 @@
+# Snyk (https://snyk.io) policy file
+exclude:
+ global:
+   - scripts/**
+   - tests/**

bitranox_template_py_lib-1.0.0/AGENTS.md

@@ -0,0 +1,104 @@
+# Repository Guidelines
+
+## On session start
+
+- Read following files from directory /media/srv-main/softdev/*/projects/softwarestack/systemprompts and keep their guidance in working memory:
+  - core_programming_solid.md
+  - bash_clean_architecture.md
+  - bash_clean_code.md
+  - bash_small_functions.md
+  - python_solid_architecture_enforcer.md
+  - python_clean_architecture.md
+  - python_clean_code.md
+  - python_small_functions_style.md
+  - python_libraries_to_use.md
+  - python_structure_template.md
+  - self_documenting.md
+  - self_documenting_template.md
+  - python_jupyter_notebooks.md
+  - python_testing.md
+
+always apply those Rules :
+
+- core_programming_solid.md
+
+when writing or refracturing Bash scripts, apply those Rules :
+
+- core_programming_solid.md
+- bash_clean_architecture.md
+- bash_clean_code.md
+- bash_small_functions.md
+
+when writing or refracturing Python scripts, apply those Rules :
+- core_programming_solid.md
+- python_solid_architecture_enforcer.md
+- python_clean_architecture.md
+- python_clean_code.md
+- python_small_functions_style.md
+- python_libraries_to_use.md
+- python_lib_structure_template.md
+
+## Project Structure & Module Organization
+
+- `src/bitranox_template_py_lib/`: Python package
+- `scripts/`: shared automation
+- `tests/`: test suite
+
+
+### Versioning & Releases
+
+- Single source of truth for the package version is `pyproject.toml` (`[project].version`).
+- Automation rewrites `src/bitranox_template_py_lib/__init__conf__.py` from `pyproject.toml`, so runtime code imports generated constants instead of querying `importlib.metadata`.
+- After updating project metadata (version, summary, URLs, authors) run `make test` (or `python -m scripts.test`) to regenerate the metadata module before committing.
+- Tag releases `vX.Y.Z` and push tags; CI will build artifacts and publish when configured.
+
+### Common Make Targets (Alphabetical)
+
+
+| Target            | One-line description                                                           |
+|-------------------|--------------------------------------------------------------------------------|
+| `build`           | Build wheel/sdist artifacts.                                                    |
+| `bump`            | Bump version (VERSION=X.Y.Z or PART=major\|minor\|patch) and update changelog. |
+| `bump-major`      | Increment major version ((X+1).0.0).                                           |
+| `bump-minor`      | Increment minor version (X.Y.Z → X.(Y+1).0).                                   |
+| `bump-patch`      | Increment patch version (X.Y.Z → X.Y.(Z+1)).                                   |
+| `clean`           | Remove caches, coverage, and build artifacts (includes `dist/` and `build/`).  |
+| `dev`             | Install package with dev extras.                                               |
+| `help`            | Show this table.                                                               |
+| `install`         | Editable install.                                                              |
+| `menu`            | Interactive TUI menu (make menu).                                              |
+| `push`            | Commit changes once and push to GitHub (no CI monitoring).                     |
+| `release`         | Tag vX.Y.Z, push, sync packaging, run gh release if available.                 |
+| `run`             | Run module entry (`python -m ... --help`).                                     |
+| `test`            | Lint, format, type-check, run tests with coverage, upload to Codecov.          |
+| `version-current` | Print current version from `pyproject.toml`.                                   |
+
+
+## Coding Style & Naming Conventions
+  - apply python_clean_code.md
+
+
+## Commit & Pull Request Guidelines
+
+## Architecture Overview
+  - apply python_clean_architecture.md
+
+## Security & Configuration Tips
+- `.env` is only for local tooling (CodeCov tokens, etc.); do not commit secrets.
+- Rich logging should sanitize payloads before rendering once implemented.
+
+## Translations (Docs)
+
+## Translations (App UI Strings)
+
+## Changes in WEB Documentation
+- when asked to update website documentation - only do that in the english docs under /website/docs because other languages will be translated automatically,
+  unless stated otherwise by the user. In doubt - ask the user
+
+## Changes in APP Strings
+- when i18 strings are changed, only to that in sources/\_locales/en because other languages will be translated automatically,
+  unless stated otherwise by the user. In doubt - ask the user
+
+## commit/push/GitHub policy
+- run "make test" before any push to avoid lint/test breakage.
+- after push, monitor errors in the github actions and try to correct the errors

bitranox_template_py_lib-1.0.0/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## [1.0.0] - 2025-11-04
+- Bootstrap `bitranox_template_py_lib`