oireachtas-api 2.0.1

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).

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 client
client = oireachtas_api.ConstituenciesApi()

try:
    # 2. Query constituencies (limiting to 5 results)
    response = client.constituencies(limit=5)
    
    # 3. Print the API response
    print("--- Oireachtas Constituencies ---")
    pprint(response)
except oireachtas_api.rest.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.

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

---

🧪 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]