boarddata 3.0.0__py3-none-any.whl

boarddata/__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/_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]