finanzonline-uid 2.0.0__tar.gz

finanzonline_uid-2.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'"
+}

finanzonline_uid-2.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
+}

finanzonline_uid-2.0.0/.env.example

@@ -0,0 +1,131 @@
+# Copy to .env and fill values as needed.
+#
+# .env file format (no prefix needed):
+#   SECTION__KEY=value
+#
+# Environment variable format (requires prefix):
+#   FINANZONLINE_UID___SECTION__KEY=value
+
+# =============================================================================
+# CI/CD Tokens
+# =============================================================================
+
+# 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=
+
+# =============================================================================
+# Application Settings
+# =============================================================================
+
+# Language for user-facing messages and email notifications
+# Supported: en (English), de (German), es (Spanish), fr (French), ru (Russian)
+APP__LANGUAGE=en
+
+# =============================================================================
+# FinanzOnline Configuration (required for UID checks)
+# =============================================================================
+#
+# IMPORTANT: The user (BENID) must have webservice permissions enabled!
+# Check FinanzOnline user administration to ensure the user is configured
+# as a webservice user, not just a regular FinanzOnline user.
+#
+# Return code -7 means "The user is not a web service user"
+# Return code -4 means "The access codes are not valid"
+#
+
+# Participant ID (Teilnehmer-ID) - 8-12 alphanumeric characters
+FINANZONLINE__TID=123456789
+
+# User ID (Benutzer-ID) - 5-12 characters
+# IMPORTANT: Must be a WEBSERVICE user created in FinanzOnline user admin!
+FINANZONLINE__BENID=MYUSER
+
+# Password/PIN - 5-128 characters
+FINANZONLINE__PIN=secret
+
+# Your Austrian UID (must start with ATU)
+FINANZONLINE__UID_TN=ATU12345678
+
+# Software Producer VAT-ID - 10-24 alphanumeric characters
+# This is the VAT-ID of the company that produced the software - put Your own ATU Number there
+FINANZONLINE__HERSTELLERID=ATU12345678
+
+# Optional: Session and query timeouts
+# FINANZONLINE__SESSION_TIMEOUT=60.0
+# FINANZONLINE__QUERY_TIMEOUT=60.0
+
+# Default email recipients for UID check results (JSON array format)
+# Note: EMAIL__DEFAULT_RECIPIENTS is preferred as it works even when FO config fails
+# FINANZONLINE__DEFAULT_RECIPIENTS=["admin@example.com"]
+
+# Email format for notifications (default: both)
+# Options: html, plain, both
+#   - html:  Send HTML-only emails (rich formatting)
+#   - plain: Send plain text-only emails
+#   - both:  Send multipart/alternative with both formats
+FINANZONLINE__EMAIL_FORMAT=both
+
+# Cache valid UID results for this many hours (0 = disabled, default: 48)
+# Only valid results are cached. Email notifications include cache timestamp.
+FINANZONLINE__CACHE_RESULTS_HOURS=48
+
+# Path to cache file (default: platform-specific cache directory)
+# Uses file locking for safe concurrent access on network drives
+# FINANZONLINE__CACHE_FILE=/shared/network/uid_cache.json
+
+# Rate limiting: Maximum API queries allowed within the time window (0 = disabled)
+# When exceeded: logs warning, sends email, but query still proceeds (BMF handles actual limit)
+# Note: Cache hits don't count toward rate limit - only actual API calls are tracked
+FINANZONLINE__RATELIMIT_QUERIES=50
+
+# Rate limiting: Sliding window duration in hours (default: 24)
+FINANZONLINE__RATELIMIT_HOURS=24.0
+
+# Path to rate limit tracking file (default: platform-specific cache directory)
+# Uses file locking for safe concurrent access
+# FINANZONLINE__RATELIMIT_FILE=/shared/network/rate_limits.json
+
+# Default email recipients for ALL notifications (including config errors)
+# This is the PRIMARY recipient setting - used even when FinanzOnline config fails
+FINANZONLINE__DEFAULT_RECIPIENTS=["admin@example.com"]
+
+# =============================================================================
+# Email Configuration (for sending notifications)
+# =============================================================================
+
+# SMTP servers in JSON array format (tried in order)
+EMAIL__SMTP_HOSTS=["smtp.example.com:587"]
+
+# Default sender address
+EMAIL__FROM_ADDRESS=alerts@example.com
+
+# SMTP authentication (optional, both needed for auth)
+# EMAIL__SMTP_USERNAME=your-email@example.com
+# EMAIL__SMTP_PASSWORD=your-app-password
+
+# SMTP connection settings
+# EMAIL__USE_STARTTLS=true
+# EMAIL__TIMEOUT=30.0
+
+
+# =============================================================================
+# Testing (for local development)
+# =============================================================================
+
+# Test SMTP server configuration
+TEST_SMTP_SERVER=
+TEST_EMAIL_ADDRESS=
+
+# =============================================================================
+# Logging Configuration
+# =============================================================================
+# Uses same SECTION__KEY format as other settings (via lib_layered_config)
+# LIB_LOG_RICH__CONSOLE_LEVEL=DEBUG
+# LIB_LOG_RICH__CONSOLE_FORMAT_PRESET=short

finanzonline_uid-2.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"

finanzonline_uid-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,205 @@
+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.10, 3.11, 3.12, and 3.13
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    env:
+      PYO3_USE_ABI3_FORWARD_COMPATIBILITY: "1"
+      PYTHONIOENCODING: "utf-8"
+    steps:
+      - uses: actions/checkout@v6
+      - 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 rtoml for metadata extraction
+        shell: bash
+        run: python -m pip install rtoml
+      - name: Extract project metadata
+        shell: python
+        run: |
+          import os
+          import rtoml
+          from pathlib import Path
+
+          data = rtoml.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@v5
+        with:
+          path: .ruff_cache
+          key: ruff-${{ runner.os }}-${{ github.sha }}
+          restore-keys: |
+            ruff-${{ runner.os }}-
+      - name: Cache pyright
+        uses: actions/cache@v5
+        with:
+          path: .pyright
+          key: pyright-${{ runner.os }}-py${{ matrix.python }}-${{ github.sha }}
+          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@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install rtoml for metadata extraction
+        run: python -m pip install rtoml
+      - name: Extract project metadata
+        shell: python
+        run: |
+          import os
+          import rtoml
+          from pathlib import Path
+
+          data = rtoml.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@v6
+      - 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

finanzonline_uid-2.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@v6
+
+      - 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 }}"

finanzonline_uid-2.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@v6
+      - 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@v6
+        with:
+          name: dist
+          path: dist/*

finanzonline_uid-2.0.0/.gitignore

@@ -0,0 +1,180 @@
+# ====================================
+# 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_*
+
+# ====================================
+# 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

finanzonline_uid-2.0.0/.qlty/qlty.toml

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

finanzonline_uid-2.0.0/.snyk

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