election_day.utils.election.candidates
======================================

.. py:module:: election_day.utils.election.candidates


Classes
-------

.. autoapisummary::

   election_day.utils.election.candidates.CandidateResultRow


Functions
---------

.. autoapisummary::

   election_day.utils.election.candidates.get_candidates_results
   election_day.utils.election.candidates.get_candidates_data
   election_day.utils.election.candidates.get_candidates_results_by_entity


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

.. py:class:: CandidateResultRow

   Bases: :py:obj:`NamedTuple`


   .. py:attribute:: votes
      :type:  int


   .. py:attribute:: family_name
      :type:  str


   .. py:attribute:: first_name
      :type:  str


   .. py:attribute:: elected
      :type:  bool


   .. py:attribute:: party
      :type:  str | None


   .. py:attribute:: percentage
      :type:  float


   .. py:attribute:: list_name
      :type:  str | None


   .. py:attribute:: list_id
      :type:  str | None


.. py:function:: get_candidates_results(election: onegov.election_day.models.Election, session: sqlalchemy.orm.Session, entities: collections.abc.Collection[str] | None = None) -> sqlalchemy.orm.Query[CandidateResultRow]

   Returns the aggregated candidates results as list.

   Also includes percentages of votes for majorz elections. Be aware that this
   may contain rounding errors.


.. py:function:: get_candidates_data(election: onegov.election_day.models.Election, limit: int | None = None, lists: collections.abc.Collection[str] | None = None, elected: bool | None = None, sort_by_lists: bool = False, entities: collections.abc.Collection[str] | None = None) -> onegov.core.types.JSONObject_ro

   " Get the candidates as JSON. Used to for the candidates bar chart.

   Allows to optionally

   * return only the first ``limit`` results.
   * return only results for candidates within the given list names (proporz)
     or party names (majorz).
   * return only elected candidates. If not specified, only elected candidates
     are returned for proporz elections, all for majorz elections.



.. py:function:: get_candidates_results_by_entity(election: onegov.election_day.models.Election, sort_by_votes: bool = False) -> tuple[list[CandidateRow], list[tuple[str, list[ResultRow]]]]

   Returns the candidates results by entity.

   Allows to optionally order by the number of total votes instead of the
   candidate names.