oireachtas-api 2.1.0

Houses of the Oireachtas Open Data APIs Python SDK

Houses of the Oireachtas Open Data API - Python SDK

A modern, lightweight Python client SDK for retrieving and querying open parliament data from the national parliament of Ireland (Houses of the Oireachtas).

📖 Full Documentation: The comprehensive interactive documentation built with MkDocs is available on GitHub Pages: https://irishsmurf.github.io/OireachtasAPI/

This client SDK makes metadata queries easy, allowing you to discover and locate specific official documents, bills, members, votes (divisions), and debates. Output formats point directly to XML/PDF datasets hosted at data.oireachtas.ie.

---

🚀 Key Features

• Modern Python 3 Support: Fully compatible with Python 3.8+ (legacy Python 2 support has been dropped).
• Fully Tested: Upgraded to use pytest with a complete suite of unit (mocked) and integration (live API) tests.
• Open Access: Works out of the box with the public Oireachtas API endpoints (no authentication tokens required).
• Automated CI/CD: GitHub Actions verify compatibility on every push and automatically build & publish new GitHub Releases when tags are created.

---

🛠 Installation

Installing via PyPI

You can install the package directly from PyPI:

pip install oireachtas-api

Installing directly from GitHub

To install the latest development version directly from GitHub:

pip install git+https://github.com/Irishsmurf/OireachtasAPI.git

Local Development Setup

To clone the repository and install it in editable mode with development dependencies:

# Clone the repository
git clone https://github.com/Irishsmurf/OireachtasAPI.git
cd OireachtasAPI

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install requirements
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt -r test-requirements.txt
pip install -e .

---

💡 Quick Start Example

This code demonstrates how to retrieve the 5 most recent active Constituencies:

import oireachtas_api
from pprint import pprint

# 1. Initialize the simplified client
client = oireachtas_api.Client()

try:
    # 2. Query constituencies (returns standard Python list/dict)
    response = client.constituencies(limit=5)
    
    # 3. Print the API response
    print("--- Oireachtas Constituencies ---")
    pprint(response)
except oireachtas_api.ApiException as e:
    print(f"Failed to query constituencies: {e}")

---

📂 Core API Reference

All requests call the live API endpoint: https://api.oireachtas.ie/v1.

Simplified Unified Client

The Client class consolidates all endpoints into a single wrapper. Method calls return standard Python dictionaries and lists, eliminating the need to interact with verbose auto-generated model objects:

import oireachtas_api

client = oireachtas_api.Client()

# Retrieve constituencies
constituencies = client.constituencies(limit=5)

# Access member information
members = client.members(limit=10)

Method API	Description / Use Case	Official Specs
constituencies()	Retrieve electoral districts	Docs
debates()	Access official debates transcripts	Docs
divisions()	Inspect parliamentary votes and counts	Docs
houses()	Query house info (Dáil or Seanad)	Docs
legislation()	Query active & historic bills and acts	Docs
members()	Look up details of TDs and Senators	Docs
parties()	List political parties	Docs
questions()	Query parliamentary questions (PQs)	Docs

Note: The legacy individual service API classes (ConstituenciesApi, MembersApi, etc.) and data models are still exported for backward compatibility.

---

🧪 Testing Guide

We use pytest for unit and integration tests.

1. Isolated Unit Tests (Mocked Network)

To run local test stubs using mock API responses (extremely fast, offline-safe):

pytest -m "not integration"

2. Live Integration Tests

To verify compatibility against the real, live Oireachtas API endpoints:

pytest -m "integration"

3. Run the Whole Test Suite

To run all tests:

pytest

---

🏷 Release Automation

This project tracks official releases automatically:

1. Ensure your version code is up to date in setup.py.
2. Commit your changes and tag the master branch:

   git tag v2.0.0
   git push origin v2.0.0
   

3. The Release Workflow will automatically build the package wheels, publish a GitHub Release with build assets attached, and publish the release to PyPI using OIDC Trusted Publishing.

---

📬 Contact & Support

• Official API Portal: beta.oireachtas.ie/en/open-data
• Email: [e-mail]