ffbb-data-client 2.0.0__tar.gz

ffbb_data_client-2.0.0/.coveragerc

@@ -0,0 +1,70 @@
+# .coveragerc — coverage.py configuration
+# https://coverage.readthedocs.io/en/latest/config.html
+
+[run]
+branch = True
+source = ffbb_api_client_v3
+parallel = True
+# CRITICAL for Coveralls: ensures paths are relative to the git root
+# Without this, Coveralls reports 0% or fails to map files
+relative_files = True
+omit =
+    # Test files don't need to appear in coverage reports
+    tests/*
+    tests/**/*
+    # Build artifacts
+    setup.py
+    # Type stubs
+    *.pyi
+
+[paths]
+# Maps coverage paths from different environments (tox, Docker, etc.)
+# to the canonical source root. Order matters: first match wins.
+source =
+    src/ffbb_api_client_v3
+    */ffbb_api_client_v3
+    */src/ffbb_api_client_v3
+
+[report]
+# Minimum coverage threshold — CI will fail below this
+# Uncomment and adjust once coverage stabilizes above 90%
+# fail_under = 90
+
+show_missing = True
+skip_covered = False
+skip_empty = True
+precision = 2
+
+# Lines to exclude from coverage measurement
+exclude_lines =
+    # Standard pragma
+    pragma: no cover
+
+    # Debug-only code
+    def __repr__
+    if self\.debug
+    if settings\.DEBUG
+
+    # Defensive assertions — tested via other means
+    raise AssertionError
+    raise NotImplementedError
+
+    # Non-runnable code paths
+    if 0:
+    if __name__ == .__main__.:
+
+    # Type-checking imports (not executed at runtime)
+    if TYPE_CHECKING:
+    @(abc\.)?abstractmethod
+
+    # Protocol / overload stubs
+    \.\.\.
+
+[html]
+directory = htmlcov
+title = FFBBApiClientV3 Coverage
+
+[xml]
+# Required by coverallsapp/github-action@v2 Universal Coverage Reporter
+# when not using lcov format
+output = coverage.xml

ffbb_data_client-2.0.0/.github/scripts/check_wrapper_parity.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Check that FFBBDataClient wrapper exposes all methods from inner clients."""
+
+import ast
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+CLIENTS = ROOT / "src" / "ffbb_data_client" / "clients"
+
+# Methods / names intentionally excluded from the parity check
+EXCLUDED = {
+    "__init__",
+    "__repr__",
+    "__str__",
+    # Singleton-factory classmethod on the wrapper itself
+    "create",
+}
+
+
+def get_public_methods(path: Path) -> set[str]:
+    """Return all public method names defined in the first class of a file.
+
+    Skips:
+    - dunder methods
+    - names listed in EXCLUDED
+    - @property decorated functions (they are attributes, not callable methods)
+    - @staticmethod / @classmethod that are internal helpers
+    """
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    methods: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            for item in node.body:
+                if not isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    continue
+                name = item.name
+                if name.startswith("_") or name in EXCLUDED:
+                    continue
+                # Skip @property decorated functions
+                is_property = any(
+                    (isinstance(d, ast.Name) and d.id == "property")
+                    or (isinstance(d, ast.Attribute) and d.attr == "property")
+                    for d in item.decorator_list
+                )
+                if is_property:
+                    continue
+                methods.add(name)
+            break  # only first class
+    return methods
+
+
+def write_summary(text: str) -> None:
+    """Append text to the GitHub Actions step summary if available."""
+    summary_file = os.environ.get("GITHUB_STEP_SUMMARY")
+    if summary_file:
+        with open(summary_file, "a", encoding="utf-8") as f:
+            f.write(text + "\n")
+
+
+def main() -> int:
+    api_methods = get_public_methods(CLIENTS / "api_ffbb_app_client.py")
+    ms_methods = get_public_methods(CLIENTS / "meilisearch_ffbb_client.py")
+    wrapper_methods = get_public_methods(CLIENTS / "ffbb_data_client.py")
+
+    all_inner = api_methods | ms_methods
+    missing = sorted(all_inner - wrapper_methods)
+
+    if not missing:
+        msg = "## ✅ Wrapper parity OK\n\nAll public methods from inner clients are exposed in `FFBBDataClient`."
+        print(msg)
+        write_summary(msg)
+        return 0
+
+    # Build markdown report
+    lines = [
+        "## ⚠️ Wrapper parity check failed",
+        "",
+        "The following methods exist in inner clients but are **not exposed** "
+        "in `FFBBDataClient`:",
+        "",
+        "| Method | Source client |",
+        "|---|---|",
+    ]
+    for m in missing:
+        source = []
+        if m in api_methods:
+            source.append("`ApiFFBBAppClient`")
+        if m in ms_methods:
+            source.append("`MeilisearchFFBBClient`")
+        lines.append(f"| `{m}` | {', '.join(source)} |")
+
+    lines += [
+        "",
+        "### How to fix",
+        "Add the missing method(s) to "
+        "`src/ffbb_data_client/clients/ffbb_data_client.py` "
+        "so they delegate to the appropriate inner client.",
+    ]
+
+    report = "\n".join(lines)
+    Path("parity_report.md").write_text(report, encoding="utf-8")
+    print(report)
+    write_summary(report)
+
+    print(f"\n❌ {len(missing)} missing method(s) found — failing build.")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ffbb_data_client-2.0.0/.github/workflows/check_wrapper_parity.yml

@@ -0,0 +1,35 @@
+name: Check Wrapper Parity
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'src/ffbb_data_client/clients/**'
+  pull_request:
+    paths:
+      - 'src/ffbb_data_client/clients/**'
+  schedule:
+    - cron: '0 6 * * 1'  # Every Monday at 06:00 UTC
+  workflow_dispatch:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  check-parity:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Run parity check
+        id: parity
+        run: python .github/scripts/check_wrapper_parity.py

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

@@ -0,0 +1,152 @@
+# GitHub Actions — CI Pipeline
+# Tests + Coverage → Coveralls (parallel mode, LCOV + XML)
+# Reference: https://docs.github.com/en/actions
+#            https://github.com/coverallsapp/github-action
+
+name: tests
+
+on:
+  push:
+    branches: [master]
+    tags: ['v[0-9]*', '[0-9]+.[0-9]+*']
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    # Run roughly every 15 days at 00:00 UTC
+    - cron: '0 0 1,16 * *'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: >-
+    ${{ github.workflow }}-${{ github.ref_type }}-
+    ${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    outputs:
+      wheel-distribution: ${{ steps.wheel-distribution.outputs.path }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with: {fetch-depth: 0}  # deep clone for setuptools-scm
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        id: setup-python
+        with: {python-version: "3.14"}
+      - name: Run static analysis and format checkers
+        run: pipx run pre-commit run --all-files --show-diff-on-failure
+      - name: Build package distribution files
+        run: >-
+          pipx run --python '${{ steps.setup-python.outputs.python-path }}'
+          tox -e clean,build -- --wheel
+      - name: Verify packaged discovery artefacts
+        run: |
+          python - <<'PY'
+          import json
+          import zipfile
+          from pathlib import Path
+
+          wheels = list(Path('dist').glob('*.whl'))
+          if len(wheels) != 1:
+              raise SystemExit(f'Expected one wheel, found {len(wheels)}')
+
+          required = {
+              'ffbb_data_client/data/collections.json',
+              'ffbb_data_client/data/endpoint_discovery.json',
+              'ffbb_data_client/data/indexes.json',
+              'ffbb_data_client/data/openapi.json',
+              'ffbb_data_client/data/openapi_full.json',
+          }
+          with zipfile.ZipFile(wheels[0]) as wheel:
+              names = set(wheel.namelist())
+              missing = sorted(required - names)
+              if missing:
+                  raise SystemExit(f'Missing discovery artefacts in wheel: {missing}')
+              with wheel.open('ffbb_data_client/data/endpoint_discovery.json') as handle:
+                  json.load(handle)
+          print('Discovery artefacts are present in the wheel.')
+          PY
+      - name: Validate distribution files
+        run: >-
+          pipx run --python '${{ steps.setup-python.outputs.python-path }}'
+          tox -e validate
+      - name: Record the path of wheel distribution
+        id: wheel-distribution
+        run: echo "path=$(ls dist/*.whl)" >> $GITHUB_OUTPUT
+      - name: Store the distribution files for use in other stages
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: python-distribution-files
+          path: dist/
+          retention-days: 1
+
+  test:
+    needs: prepare
+    strategy:
+      matrix:
+        python:
+        - "3.10"
+        - "3.11"
+        - "3.12"
+        - "3.13"
+        - "3.14"
+        platform:
+        - ubuntu-latest
+    runs-on: ${{ matrix.platform }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        id: setup-python
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Retrieve pre-built distribution files
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with: {name: python-distribution-files, path: dist/}
+      - name: Run tests
+        env:
+          API_FFBB_APP_BEARER_TOKEN: ${{ secrets.API_FFBB_APP_BEARER_TOKEN }}
+          MEILISEARCH_BEARER_TOKEN: ${{ secrets.MEILISEARCH_BEARER_TOKEN }}
+        run: >-
+          pipx run --python '${{ steps.setup-python.outputs.python-path }}'
+          tox --installpkg '${{ needs.prepare.outputs.wheel-distribution }}'
+
+      # ── Coveralls: upload partial report (parallel mode) ─────────────────
+      # coverallsapp/github-action@v2 uses the Universal Coverage Reporter
+      # which auto-detects LCOV (preferred) or XML if lcov is absent.
+      # `parallel: true` signals that more reports are coming from other jobs.
+      # `flag-name` labels this specific combination for per-flag drill-down on Coveralls.
+      - name: Upload coverage to Coveralls (parallel)
+        uses: coverallsapp/github-action@648a8eb78e6d50909eff900e4ec85cab4524a45b  # v2.3.6
+        with:
+          file: coverage.lcov
+          format: lcov
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          flag-name: ${{ matrix.platform }}-py${{ matrix.python }}
+          parallel: true
+
+  # ── Coveralls: finalize parallel build ─────────────────────────────────────
+  # Must run after ALL test jobs complete, even if some are skipped/cancelled.
+  # Sends the "done" signal so Coveralls calculates the merged coverage %.
+  finalize:
+    needs: test
+    runs-on: ubuntu-latest
+    # Always finalize, even if some test matrix cells failed
+    if: ${{ always() }}
+    steps:
+      - name: Finalize coverage report on Coveralls
+        uses: coverallsapp/github-action@648a8eb78e6d50909eff900e4ec85cab4524a45b  # v2.3.6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          parallel-finished: true
+
+  publish:
+    needs: finalize
+    if: ${{ github.event_name == 'push' && contains(github.ref, 'refs/tags/') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Publishing handled by Publish to PyPI workflow
+        run: |
+          echo "Tag validation completed by CI."
+          echo "PyPI publishing is centralized in .github/workflows/publish.yml."

ffbb_data_client-2.0.0/.github/workflows/deploy-pages.yml

@@ -0,0 +1,73 @@
+name: Deploy landing page to Pages
+
+on:
+  push:
+    branches: ["master", "main"]
+    tags: ["v*"]
+  # Permet de lancer manuellement depuis l'onglet Actions
+  workflow_dispatch:
+
+# Permissions nécessaires pour GitHub Pages
+permissions:
+  contents: write
+
+# Permet d'annuler les déploiements obsolètes
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.pages-url.outputs.url }}
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ github.token }}
+    steps:
+      - name: Fetch repository
+        run: |
+          set -euo pipefail
+          git init source
+          cd source
+          git remote add origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          git fetch --tags --force origin "${GITHUB_REF}"
+          git checkout --detach FETCH_HEAD
+
+      - name: Inject Dynamic Version for SEO
+        run: |
+          cd source
+          LATEST_TAG=$(git describe --tags --abbrev=0)
+          VERSION=${LATEST_TAG#v}
+          echo "Dernière version trouvée : $VERSION. Injection dans le JSON-LD Schema..."
+          sed -i "s/\"softwareVersion\": \"[^\"]*\"/\"softwareVersion\": \"$VERSION\"/g" website/index.html
+
+      - name: Publish website to gh-pages
+        run: |
+          set -euo pipefail
+          git init gh-pages
+          cd gh-pages
+          git remote add origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          if git fetch origin gh-pages --depth=1; then
+            git checkout gh-pages
+          else
+            git checkout --orphan gh-pages
+          fi
+          rsync -a --delete --exclude .git ../source/website/ ./
+          touch .nojekyll
+          git add -A
+          if git diff --cached --quiet; then
+            echo "No changes to publish."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "Deploy website from ${GITHUB_SHA}"
+          git push --force origin HEAD:gh-pages
+
+      - name: Set Pages URL
+        id: pages-url
+        run: |
+          OWNER=${GITHUB_REPOSITORY%/*}
+          REPO=${GITHUB_REPOSITORY#*/}
+          echo "url=https://${OWNER}.github.io/${REPO}/" >> "$GITHUB_OUTPUT"

ffbb_data_client-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,114 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # Required for setuptools_scm to resolve version from tags
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Verify packaged discovery artefacts
+        run: |
+          python - <<'PY'
+          import json
+          import zipfile
+          from pathlib import Path
+
+          wheels = list(Path('dist').glob('*.whl'))
+          if len(wheels) != 1:
+              raise SystemExit(f'Expected one wheel, found {len(wheels)}')
+
+          required = {
+              'ffbb_data_client/data/collections.json',
+              'ffbb_data_client/data/endpoint_discovery.json',
+              'ffbb_data_client/data/indexes.json',
+              'ffbb_data_client/data/openapi.json',
+              'ffbb_data_client/data/openapi_full.json',
+          }
+          with zipfile.ZipFile(wheels[0]) as wheel:
+              names = set(wheel.namelist())
+              missing = sorted(required - names)
+              if missing:
+                  raise SystemExit(f'Missing discovery artefacts in wheel: {missing}')
+              with wheel.open('ffbb_data_client/data/endpoint_discovery.json') as handle:
+                  json.load(handle)
+          print('Discovery artefacts are present in the wheel.')
+          PY
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for OIDC Trusted Publisher
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  notify-mcp-server:
+    name: Notify FFBB-MCP-Server
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Dispatch bump event to FFBB-MCP-Server
+        uses: peter-evans/repository-dispatch@v4
+        with:
+          token: ${{ secrets.MCP_SERVER_PAT }}
+          repository: nickdesi/FFBB-MCP-Server
+          event-type: ffbb-client-released
+          client-payload: '{"version": "${{ github.ref_name }}"}'

ffbb_data_client-2.0.0/.github/workflows/release-after-discovery-merge.yml

@@ -0,0 +1,87 @@
+name: Release after FFBB API discovery merge
+
+on:
+  workflow_run:
+    workflows: [tests]
+    types: [completed]
+    branches: [master]
+
+permissions:
+  contents: write
+  pull-requests: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  tag-patch-release:
+    name: Tag patch release
+    if: github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Resolve merged discovery PR
+        id: pr
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          pr_json="$(gh api "repos/$REPOSITORY/commits/$HEAD_SHA/pulls" -H "Accept: application/vnd.github+json")"
+          pr_count="$(jq 'length' <<< "$pr_json")"
+          if [[ "$pr_count" == "0" ]]; then
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            echo "No PR associated with $HEAD_SHA."
+            exit 0
+          fi
+
+          pr_number="$(jq -r '.[0].number' <<< "$pr_json")"
+          pr_merged="$(jq -r '.[0].merged_at != null' <<< "$pr_json")"
+          pr_base="$(jq -r '.[0].base.ref' <<< "$pr_json")"
+          has_label="$(jq -r '.[0].labels | map(.name) | index("ffbb-api") != null' <<< "$pr_json")"
+
+          echo "number=$pr_number" >> "$GITHUB_OUTPUT"
+          echo "release=$([[ "$pr_merged" == "true" && "$pr_base" == "master" && "$has_label" == "true" ]] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+
+          echo "PR #$pr_number merged=$pr_merged base=$pr_base ffbb-api-label=$has_label"
+
+      - name: Stop when this was not a discovery PR merge
+        if: steps.pr.outputs.release != 'true'
+        run: echo "No FFBB API discovery release needed."
+
+      - name: Checkout tested commit
+        if: steps.pr.outputs.release == 'true'
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      - name: Compute next patch tag
+        if: steps.pr.outputs.release == 'true'
+        id: version
+        run: |
+          latest_tag="$(git tag --list 'v[0-9]*.[0-9]*.[0-9]*' --sort=-v:refname | head -n 1)"
+          if [[ -z "$latest_tag" ]]; then
+            next_tag="v0.1.0"
+          else
+            version="${latest_tag#v}"
+            IFS='.' read -r major minor patch <<< "$version"
+            next_tag="v${major}.${minor}.$((patch + 1))"
+          fi
+          echo "tag=$next_tag" >> "$GITHUB_OUTPUT"
+          echo "Next tag: $next_tag"
+
+      - name: Create and push tag
+        if: steps.pr.outputs.release == 'true'
+        env:
+          NEXT_TAG: ${{ steps.version.outputs.tag }}
+          PR_NUMBER: ${{ steps.pr.outputs.number }}
+        run: |
+          if git rev-parse "$NEXT_TAG" >/dev/null 2>&1; then
+            echo "Tag $NEXT_TAG already exists."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$NEXT_TAG" -m "Release $NEXT_TAG after FFBB API discovery PR #$PR_NUMBER"
+          git push origin "$NEXT_TAG"