boarddata 3.0.0__tar.gz

boarddata-3.0.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: boarddata
+Version: 3.0.0
+Summary: Python SDK for the BoardData V2 REST API
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: typing_extensions>=4.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+
+# boarddata
+
+Python SDK for the BoardData V2 REST API.
+
+## Installation
+
+```bash
+pip install boarddata
+```
+
+## Quick Start
+
+```python
+from boarddata import BoardDataClient
+
+# From environment variables
+client = BoardDataClient.from_env()
+
+# Or explicit configuration
+client = BoardDataClient(
+    base_url="https://api.boarddata.scalens.com",
+    auth0_domain="your-tenant.auth0.com",
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+)
+
+# List companies
+companies = client.list_companies(country="FR", page_size=10)
+
+# Get a specific company
+company = client.get_company("company-uuid")
+
+# Create or update a company
+result = client.upsert_company("FR0000120271", "TotalEnergies", country="FR")
+print(result["action"])  # "created" or "updated"
+print(result["id"])      # company UUID
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `BOARDDATA_BACKEND_URL` | Base URL of the BoardData API |
+| `BOARDDATA_AUTH0_DOMAIN` | Auth0 tenant domain |
+| `BOARDDATA_AUTH0_CLIENT_ID` | Auth0 client ID |
+| `BOARDDATA_AUTH0_CLIENT_SECRET` | Auth0 client secret |
+
+## Token Caching
+
+```python
+from boarddata import BoardDataClient, FileTokenCache
+
+# File-based cache
+client = BoardDataClient.from_env(token_cache="~/.boarddata/token.json")
+
+# Or with explicit cache object
+cache = FileTokenCache("~/.boarddata/token.json")
+client = BoardDataClient.from_env(token_cache=cache)
+```
+
+## Pagination
+
+```python
+# Auto-paginate any list endpoint
+all_companies = client.paginate(client.list_companies, country="FR")
+
+# Limit pages
+first_100 = client.paginate(client.list_companies, max_pages=4, page_size=25)
+```
+
+## Available Domains
+
+- **Companies** — `list_companies`, `get_company`, `create_company`, `update_company`, `delete_company`, `upsert_company`
+- **Persons** — `list_persons`, `get_person`, `create_person`, `update_person`, `delete_person`, `upsert_person`
+- **Directors** — `list_directors`, `get_director`, `create_director`, `update_director`, `delete_director`, `upsert_director`
+- **Comex** — `list_comex`, `get_comex`, `create_comex`, `update_comex`, `delete_comex`, `upsert_comex`
+- **Auditors** — `list_auditors`, `get_auditor`, `create_auditor`, `update_auditor`, `delete_auditor`
+- **Documents** — `list_documents`, `get_document`, `create_document`, `update_document`, `delete_document`
+- **Assemblies** — `list_assemblies`, `get_assembly`, `create_assembly`, `update_assembly`, `delete_assembly`
+- **Resolutions** — `list_resolutions`, `get_resolution`, `update_resolution`, `delete_resolution`
+- **ESG** — `list_iros`, `create_iro`, `list_transition_plans`, `create_transition_plan`, `list_esg_benchmark`
+- **Sentinel** — `list_analyses`, `create_analysis`, `retry_press_extraction`, `update_press_article`
+- **Utilities** — `search`, `query_assistant`, `get_field_sources`, `paginate`
+
+## License
+
+MIT

boarddata-3.0.0/README.md

@@ -0,0 +1,87 @@
+# boarddata
+
+Python SDK for the BoardData V2 REST API.
+
+## Installation
+
+```bash
+pip install boarddata
+```
+
+## Quick Start
+
+```python
+from boarddata import BoardDataClient
+
+# From environment variables
+client = BoardDataClient.from_env()
+
+# Or explicit configuration
+client = BoardDataClient(
+    base_url="https://api.boarddata.scalens.com",
+    auth0_domain="your-tenant.auth0.com",
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+)
+
+# List companies
+companies = client.list_companies(country="FR", page_size=10)
+
+# Get a specific company
+company = client.get_company("company-uuid")
+
+# Create or update a company
+result = client.upsert_company("FR0000120271", "TotalEnergies", country="FR")
+print(result["action"])  # "created" or "updated"
+print(result["id"])      # company UUID
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `BOARDDATA_BACKEND_URL` | Base URL of the BoardData API |
+| `BOARDDATA_AUTH0_DOMAIN` | Auth0 tenant domain |
+| `BOARDDATA_AUTH0_CLIENT_ID` | Auth0 client ID |
+| `BOARDDATA_AUTH0_CLIENT_SECRET` | Auth0 client secret |
+
+## Token Caching
+
+```python
+from boarddata import BoardDataClient, FileTokenCache
+
+# File-based cache
+client = BoardDataClient.from_env(token_cache="~/.boarddata/token.json")
+
+# Or with explicit cache object
+cache = FileTokenCache("~/.boarddata/token.json")
+client = BoardDataClient.from_env(token_cache=cache)
+```
+
+## Pagination
+
+```python
+# Auto-paginate any list endpoint
+all_companies = client.paginate(client.list_companies, country="FR")
+
+# Limit pages
+first_100 = client.paginate(client.list_companies, max_pages=4, page_size=25)
+```
+
+## Available Domains
+
+- **Companies** — `list_companies`, `get_company`, `create_company`, `update_company`, `delete_company`, `upsert_company`
+- **Persons** — `list_persons`, `get_person`, `create_person`, `update_person`, `delete_person`, `upsert_person`
+- **Directors** — `list_directors`, `get_director`, `create_director`, `update_director`, `delete_director`, `upsert_director`
+- **Comex** — `list_comex`, `get_comex`, `create_comex`, `update_comex`, `delete_comex`, `upsert_comex`
+- **Auditors** — `list_auditors`, `get_auditor`, `create_auditor`, `update_auditor`, `delete_auditor`
+- **Documents** — `list_documents`, `get_document`, `create_document`, `update_document`, `delete_document`
+- **Assemblies** — `list_assemblies`, `get_assembly`, `create_assembly`, `update_assembly`, `delete_assembly`
+- **Resolutions** — `list_resolutions`, `get_resolution`, `update_resolution`, `delete_resolution`
+- **ESG** — `list_iros`, `create_iro`, `list_transition_plans`, `create_transition_plan`, `list_esg_benchmark`
+- **Sentinel** — `list_analyses`, `create_analysis`, `retry_press_extraction`, `update_press_article`
+- **Utilities** — `search`, `query_assistant`, `get_field_sources`, `paginate`
+
+## License
+
+MIT

boarddata-3.0.0/__init__.py

@@ -0,0 +1,18 @@
+"""BoardData API Python SDK."""
+
+from .cache import FileTokenCache
+from ._base import Base, TokenCache
+from .client import BoardDataClient
+from .errors import BoardDataError
+
+from . import types as types  # noqa: F401 — makes types accessible as boarddata.types
+
+__version__ = "3.0.0"
+__all__ = [
+    "Base",
+    "BoardDataClient",
+    "BoardDataError",
+    "FileTokenCache",
+    "TokenCache",
+    "__version__",
+]

boarddata-3.0.0/_assemblies.py

@@ -0,0 +1,400 @@
+"""Assembly, resolution, presentation, and question methods."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .types.assemblies import (
+    AssemblyDetail,
+    CreatePresentationPayload,
+    CreateQuestionPayload,
+    CreateResolutionPayload,
+    PresentationItem,
+    QuestionItem,
+    ResolutionDetail,
+    UpdatePresentationPayload,
+    UpdateQuestionPayload,
+    UpdateResolutionPayload,
+)
+from .types.core import FieldSourcePayload, PaginatedResponse
+
+
+class AssemblyMixin:
+    """Assembly, resolution, presentation, and question API methods."""
+
+    # ------------------------------------------------------------------
+    # Assemblies
+    # ------------------------------------------------------------------
+
+    def list_assemblies(self, **params: Any) -> PaginatedResponse:
+        """List assemblies.
+
+        Args:
+            company: Filter by company UUID.
+            assembly_type: Filter by assembly type (``"OGM"``, ``"EGM"``, ``"COGM"``).
+            fiscal_year: Filter by fiscal year.
+            page: Page number.
+            page_size: Results per page.
+
+        Returns:
+            Paginated response with assembly results.
+
+        Raises:
+            BoardDataError: On non-2xx API response.
+        """
+        return self._get("assemblies/", **params)  # type: ignore[attr-defined]
+
+    def get_assembly(self, uid: str) -> AssemblyDetail:
+        """Retrieve an assembly by UUID.
+
+        Args:
+            uid: Assembly UUID.
+
+        Returns:
+            AssemblyDetail with nested resolutions, presentations, questions.
+
+        Raises:
+            BoardDataError: On non-2xx API response.
+        """
+        return self._get(f"assemblies/{uid}/")  # type: ignore[attr-defined]
+
+    def create_assembly(
+        self,
+        company: str,
+        assembly_date: str,
+        assembly_type: str,
+        fiscal_year: int,
+        *,
+        postponed_date: str | None = None,
+        date_not_certified: bool | None = None,
+        motivation: str | None = None,
+        agenda: str | None = None,
+        report: str | None = None,
+        report_purpose: str | None = None,
+        quorum: str | None = None,
+        attendee_count: int | None = None,
+        includes_abstention: bool | None = None,
+        present_count: int | None = None,
+        remote_count: int | None = None,
+        questions_count: int | None = None,
+        written_questions_count: int | None = None,
+        questions_duration: str | None = None,
+        duration: str | None = None,
+        resolution_count: int | None = None,
+        format: str | None = None,
+        is_virtual: bool | None = None,
+        is_in_person: bool | None = None,
+        is_hybrid: bool | None = None,
+        has_live_voting: bool | None = None,
+        has_replay: bool | None = None,
+        has_live_qa: bool | None = None,
+        has_video: bool | None = None,
+        has_audio: bool | None = None,
+        has_simultaneous_translation: bool | None = None,
+        closed_doors: bool | None = None,
+        balo_published: bool | None = None,
+        dividend_affected: bool | None = None,
+        field_sources: list[FieldSourcePayload] | None = None,
+    ) -> AssemblyDetail:
+        """Create an assembly.
+
+        Args:
+            company: Company UUID.
+            assembly_date: Assembly date (``"YYYY-MM-DD"``).
+            assembly_type: Type of assembly.
+            fiscal_year: Fiscal year.
+            postponed_date: Postponed date if applicable.
+            date_not_certified: Whether the date is not certified.
+            motivation: Assembly motivation text.
+            agenda: Assembly agenda text.
+            report: Assembly report text.
+            report_purpose: Report purpose text.
+            quorum: Quorum percentage (decimal as string).
+            attendee_count: Total attendee count.
+            includes_abstention: Whether vote counts include abstentions.
+            present_count: Number physically present.
+            remote_count: Number attending remotely.
+            questions_count: Number of questions asked.
+            written_questions_count: Number of written questions.
+            questions_duration: Duration of Q&A (``"HH:MM:SS"``).
+            duration: Total assembly duration (``"HH:MM:SS"``).
+            resolution_count: Number of resolutions.
+            format: Assembly format.
+            is_virtual: Whether assembly was virtual.
+            is_in_person: Whether assembly was in person.
+            is_hybrid: Whether assembly was hybrid.
+            has_live_voting: Whether live voting was available.
+            has_replay: Whether replay is available.
+            has_live_qa: Whether live Q&A was available.
+            has_video: Whether video was available.
+            has_audio: Whether audio was available.
+            has_simultaneous_translation: Whether simultaneous translation was available.
+            closed_doors: Whether assembly was behind closed doors.
+            balo_published: Whether BALO was published.
+            dividend_affected: Whether dividend was affected.
+            field_sources: Document provenance for fields.
+
+        Returns:
+            Created AssemblyDetail.
+
+        Raises:
+            BoardDataError: On non-2xx API response.
+        """
+        payload = self._build_payload(  # type: ignore[attr-defined]
+            company=company,
+            assembly_date=assembly_date,
+            assembly_type=assembly_type,
+            fiscal_year=fiscal_year,
+            postponed_date=postponed_date,
+            date_not_certified=date_not_certified,
+            motivation=motivation,
+            agenda=agenda,
+            report=report,
+            report_purpose=report_purpose,
+            quorum=quorum,
+            attendee_count=attendee_count,
+            includes_abstention=includes_abstention,
+            present_count=present_count,
+            remote_count=remote_count,
+            questions_count=questions_count,
+            written_questions_count=written_questions_count,
+            questions_duration=questions_duration,
+            duration=duration,
+            resolution_count=resolution_count,
+            format=format,
+            is_virtual=is_virtual,
+            is_in_person=is_in_person,
+            is_hybrid=is_hybrid,
+            has_live_voting=has_live_voting,
+            has_replay=has_replay,
+            has_live_qa=has_live_qa,
+            has_video=has_video,
+            has_audio=has_audio,
+            has_simultaneous_translation=has_simultaneous_translation,
+            closed_doors=closed_doors,
+            balo_published=balo_published,
+            dividend_affected=dividend_affected,
+            field_sources=field_sources,
+        )
+        return self._post("assemblies/", payload)  # type: ignore[attr-defined]
+
+    def update_assembly(
+        self,
+        uid: str,
+        *,
+        assembly_date: str | None = None,
+        assembly_type: str | None = None,
+        fiscal_year: int | None = None,
+        postponed_date: str | None = None,
+        date_not_certified: bool | None = None,
+        motivation: str | None = None,
+        agenda: str | None = None,
+        report: str | None = None,
+        report_purpose: str | None = None,
+        quorum: str | None = None,
+        attendee_count: int | None = None,
+        includes_abstention: bool | None = None,
+        present_count: int | None = None,
+        remote_count: int | None = None,
+        questions_count: int | None = None,
+        written_questions_count: int | None = None,
+        questions_duration: str | None = None,
+        duration: str | None = None,
+        resolution_count: int | None = None,
+        format: str | None = None,
+        is_virtual: bool | None = None,
+        is_in_person: bool | None = None,
+        is_hybrid: bool | None = None,
+        has_live_voting: bool | None = None,
+        has_replay: bool | None = None,
+        has_live_qa: bool | None = None,
+        has_video: bool | None = None,
+        has_audio: bool | None = None,
+        has_simultaneous_translation: bool | None = None,
+        closed_doors: bool | None = None,
+        balo_published: bool | None = None,
+        dividend_affected: bool | None = None,
+    ) -> AssemblyDetail:
+        """Partial update an assembly.
+
+        Args:
+            uid: Assembly UUID.
+            (All other args same as create_assembly, all optional.)
+
+        Returns:
+            Updated AssemblyDetail.
+
+        Raises:
+            BoardDataError: On non-2xx API response.
+        """
+        payload = self._build_payload(  # type: ignore[attr-defined]
+            assembly_date=assembly_date,
+            assembly_type=assembly_type,
+            fiscal_year=fiscal_year,
+            postponed_date=postponed_date,
+            date_not_certified=date_not_certified,
+            motivation=motivation,
+            agenda=agenda,
+            report=report,
+            report_purpose=report_purpose,
+            quorum=quorum,
+            attendee_count=attendee_count,
+            includes_abstention=includes_abstention,
+            present_count=present_count,
+            remote_count=remote_count,
+            questions_count=questions_count,
+            written_questions_count=written_questions_count,
+            questions_duration=questions_duration,
+            duration=duration,
+            resolution_count=resolution_count,
+            format=format,
+            is_virtual=is_virtual,
+            is_in_person=is_in_person,
+            is_hybrid=is_hybrid,
+            has_live_voting=has_live_voting,
+            has_replay=has_replay,
+            has_live_qa=has_live_qa,
+            has_video=has_video,
+            has_audio=has_audio,
+            has_simultaneous_translation=has_simultaneous_translation,
+            closed_doors=closed_doors,
+            balo_published=balo_published,
+            dividend_affected=dividend_affected,
+        )
+        return self._patch(f"assemblies/{uid}/", payload)  # type: ignore[attr-defined]
+
+    def delete_assembly(self, uid: str) -> None:
+        """Soft-delete an assembly."""
+        self._delete(f"assemblies/{uid}/")  # type: ignore[attr-defined]
+
+    def get_assembly_stats(self, **params: Any) -> Any:
+        """Get assembly statistics."""
+        return self._get("assemblies/stats/", **params)  # type: ignore[attr-defined]
+
+    # -- Presentations --
+
+    def list_presentations(self, assembly_uid: str, **params: Any) -> PaginatedResponse:
+        """List presentations for an assembly."""
+        return self._get(f"assemblies/{assembly_uid}/presentations/", **params)  # type: ignore[attr-defined]
+
+    def create_presentations(
+        self, assembly_uid: str, data: list[CreatePresentationPayload],
+    ) -> list[PresentationItem]:
+        """Batch-create presentations for an assembly."""
+        return self._post(f"assemblies/{assembly_uid}/presentations/", data)  # type: ignore[attr-defined]
+
+    def update_presentation(
+        self, assembly_uid: str, pk: str, data: UpdatePresentationPayload,
+    ) -> PresentationItem:
+        """Partial update a presentation."""
+        return self._patch(f"assemblies/{assembly_uid}/presentations/{pk}/", data)  # type: ignore[attr-defined]
+
+    def delete_presentation(self, assembly_uid: str, pk: str) -> None:
+        """Delete a presentation."""
+        self._delete(f"assemblies/{assembly_uid}/presentations/{pk}/")  # type: ignore[attr-defined]
+
+    # -- Questions --
+
+    def list_questions(self, assembly_uid: str, **params: Any) -> PaginatedResponse:
+        """List questions for an assembly."""
+        return self._get(f"assemblies/{assembly_uid}/questions/", **params)  # type: ignore[attr-defined]
+
+    def create_questions(
+        self, assembly_uid: str, data: list[CreateQuestionPayload],
+    ) -> list[QuestionItem]:
+        """Batch-create questions for an assembly."""
+        return self._post(f"assemblies/{assembly_uid}/questions/", data)  # type: ignore[attr-defined]
+
+    def update_question(
+        self, assembly_uid: str, pk: str, data: UpdateQuestionPayload,
+    ) -> QuestionItem:
+        """Partial update a question."""
+        return self._patch(f"assemblies/{assembly_uid}/questions/{pk}/", data)  # type: ignore[attr-defined]
+
+    def delete_question(self, assembly_uid: str, pk: str) -> None:
+        """Delete a question."""
+        self._delete(f"assemblies/{assembly_uid}/questions/{pk}/")  # type: ignore[attr-defined]
+
+    # -- Resolutions --
+
+    def list_resolutions(self, **params: Any) -> PaginatedResponse:
+        """List resolutions (top-level, with filters)."""
+        return self._get("resolutions/", **params)  # type: ignore[attr-defined]
+
+    def get_resolution(self, uid: str) -> ResolutionDetail:
+        """Retrieve a resolution by UUID."""
+        return self._get(f"resolutions/{uid}/")  # type: ignore[attr-defined]
+
+    def update_resolution(
+        self,
+        uid: str,
+        *,
+        number_or_letter: str | None = None,
+        resolution_type: int | None = None,
+        description: str | None = None,
+        status: str | None = None,
+        approval_rate: str | None = None,
+        votes_for: int | None = None,
+        votes_against: int | None = None,
+        abstentions: int | None = None,
+        is_shareholder_proposal: bool | None = None,
+        is_dissenting: bool | None = None,
+        is_agreed: bool | None = None,
+    ) -> ResolutionDetail:
+        """Partial update a resolution (top-level endpoint)."""
+        payload = self._build_payload(  # type: ignore[attr-defined]
+            number_or_letter=number_or_letter,
+            resolution_type=resolution_type,
+            description=description,
+            status=status,
+            approval_rate=approval_rate,
+            votes_for=votes_for,
+            votes_against=votes_against,
+            abstentions=abstentions,
+            is_shareholder_proposal=is_shareholder_proposal,
+            is_dissenting=is_dissenting,
+            is_agreed=is_agreed,
+        )
+        return self._patch(f"resolutions/{uid}/", payload)  # type: ignore[attr-defined]
+
+    def delete_resolution(self, uid: str) -> None:
+        """Delete a resolution (top-level endpoint)."""
+        self._delete(f"resolutions/{uid}/")  # type: ignore[attr-defined]
+
+    def get_resolution_typestats(self, **params: Any) -> Any:
+        """Get per-resolution-type average approval rate and count."""
+        return self._get("resolutions/typestats/", **params)  # type: ignore[attr-defined]
+
+    def list_assembly_resolutions(self, assembly_uid: str, **params: Any) -> PaginatedResponse:
+        """List resolutions nested under an assembly."""
+        return self._get(f"assemblies/{assembly_uid}/resolutions/", **params)  # type: ignore[attr-defined]
+
+    def create_assembly_resolution(
+        self, assembly_uid: str, data: list[CreateResolutionPayload],
+    ) -> list[ResolutionDetail]:
+        """Create (batch upsert) resolutions under an assembly."""
+        return self._post(f"assemblies/{assembly_uid}/resolutions/", data)  # type: ignore[attr-defined]
+
+    def update_assembly_resolution(
+        self, assembly_uid: str, pk: str, data: UpdateResolutionPayload,
+    ) -> ResolutionDetail:
+        """Partial update a resolution under an assembly."""
+        return self._patch(f"assemblies/{assembly_uid}/resolutions/{pk}/", data)  # type: ignore[attr-defined]
+
+    def delete_assembly_resolution(self, assembly_uid: str, pk: str) -> None:
+        """Delete a resolution under an assembly."""
+        self._delete(f"assemblies/{assembly_uid}/resolutions/{pk}/")  # type: ignore[attr-defined]
+
+    # -- Lookup tables --
+
+    def list_resolution_types(self, **params: Any) -> PaginatedResponse:
+        """List resolution types."""
+        return self._get("resolution-types/", **params)  # type: ignore[attr-defined]
+
+    def list_presentation_categories(self, **params: Any) -> PaginatedResponse:
+        """List presentation categories."""
+        return self._get("presentation-categories/", **params)  # type: ignore[attr-defined]
+
+    def list_question_themes(self, **params: Any) -> PaginatedResponse:
+        """List question themes."""
+        return self._get("question-themes/", **params)  # type: ignore[attr-defined]