bolster.data_sources.niassembly.votes
=====================================

.. py:module:: bolster.data_sources.niassembly.votes

.. autoapi-nested-parse::

   NI Assembly Votes / Divisions data module.

   Fetches plenary division (vote) records from the NI Assembly AIMS API.
   Divisions are fetched by date range via ``GetVotesOnDivision_JSON`` and
   per-member vote records are fetched via ``GetDivisionMemberVoting``
   (which returns XML).

   Update frequency: Real-time.

   .. rubric:: Example

   >>> from bolster.data_sources.niassembly import votes
   >>> df = votes.get_all_divisions()
   >>> len(df) > 100
   True
   >>> "DivisionDate" in df.columns
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.niassembly.votes.logger


Functions
---------

.. autoapisummary::

   bolster.data_sources.niassembly.votes.get_all_divisions
   bolster.data_sources.niassembly.votes.get_division_votes


Module Contents
---------------

.. py:data:: logger

.. py:function:: get_all_divisions(start_date = None, end_date = None)

   Return all Assembly divisions (votes) in a date range as a DataFrame.

   Defaults to fetching from the start of the current Assembly mandate
   (2022-05-01) to today.  Pass explicit dates for a narrower or wider window.

   :param start_date: ISO-8601 date string (YYYY-MM-DD).  Defaults to
                      ``"2022-05-01"`` (current mandate start).
   :param end_date: ISO-8601 date string (YYYY-MM-DD).  Defaults to today.

   :returns: EventID, SessionID, DocumentID, DivisionDate,
             DivisionSubject, DivisonType, DivisionResult, MemberVoting.
             Returns an empty DataFrame if no divisions are found.
   :rtype: DataFrame with columns

   :raises requests.HTTPError: If the API request fails.

   .. rubric:: Example

   >>> df = get_all_divisions()
   >>> len(df) >= 0
   True
   >>> "DivisionSubject" in df.columns
   True


.. py:function:: get_division_votes(division_id)

   Return per-member voting records for a single division.

   Fetches ``GetDivisionMemberVoting`` (XML) and parses member vote records.

   :param division_id: NI Assembly AIMS DocumentID for the division.

   :returns: DocumentID, EventID, PersonID, MemberName,
             Vote, Designation, VoteInVacancy, MemberSortName.
             Returns an empty DataFrame if no records are found.
   :rtype: DataFrame with columns

   :raises requests.HTTPError: If the API request fails.

   .. rubric:: Example

   >>> df = get_division_votes(406283)
   >>> "Vote" in df.columns
   True
   >>> len(df) > 0
   True