parentsquare-client

An unofficial, read-only sync and async ParentSquare client for the authenticated ParentSquare web experience.

ParentSquare does not publish a parent-facing API. This project reads the authenticated parent web experience and therefore may stop working when ParentSquare changes its site or account protections. It is not affiliated with or endorsed by ParentSquare, Inc. Review ParentSquare's current terms and your district's policies before using it.

Install the client from PyPI:

pip install parentsquare-client
uv add parentsquare-client

Credential storage is opt-in. Install the keyring extra to use the operating system's configured credential store:

pip install "parentsquare-client[keyring]"
uv add "parentsquare-client[keyring]"

from parentsquare import KeyringCredentialStore

credentials = KeyringCredentialStore()
credentials.set_password("parent@example.com", "password")
password = credentials.get_password("parent@example.com")

The default client does not read or write the keyring. The embedding application owns its credential storage policy.

Development

Install the development environment with uv sync --extra dev, then run uv run pytest. Install prek with uvx prek install to enable the same checks used by CI. Tagged releases create GitHub release artifacts; the published release workflow uses PyPI Trusted Publishing and can be dispatched against TestPyPI for a pre-release verification.

See docs/releasing.md for the one-time Trusted Publisher configuration and tag workflow.

from parentsquare import AsyncParentSquareClient

async with AsyncParentSquareClient("parent@example.com", "password") as client:
    account = await client.discover_account()
    schools = account.schools
    students = account.students
    posts = await client.fetch_posts(schools[0].id)
    events = await client.fetch_calendar_events(schools[0].id)
    dashboard = await client.fetch_student_dashboard(students[0])
    groups = await client.fetch_groups(schools[0], students=students)
    group_posts = await client.fetch_group_posts(schools[0], groups[0])

The synchronous wrapper is useful for scripts and data tools:

from parentsquare import ParentSquareClient

with ParentSquareClient("parent@example.com", "password") as client:
    schools = client.discover_schools()
    posts = client.fetch_posts(schools[0].id)

The typed models use frozen, slotted dataclasses and expose to_record() for data tools. get_html(), get_json(), and get_ics() provide an authenticated read-only escape hatch for upstream pages that have not yet earned a stable model. There are intentionally no write methods.

IDs are stable within ParentSquare's account and are suitable for downstream deduplication and merge keys. A student dashboard's grade_level is a school grade label, not an academic mark. Synthetic fixtures are used in this repository's tests; real messages, cookies, credentials, student records, and calendar URLs must never be committed.

Authentication

The client supports the normal sign-in flow and a six-digit MFA challenge. A caller handles MFARequired by presenting the masked destination to the user and calling submit_mfa_code. The client does not persist credentials or cookies; an embedding application owns that storage policy.

Status

This is an early alpha. Parent-visible schools, students, student dashboards, groups, group feeds, posts, and calendars are typed read operations. When students are supplied to fetch_groups, linked student IDs are attached to each group from ParentSquare's authenticated group picker. Less stable read-only pages can be reached with the raw methods while their models are developed. Replies, acknowledgements, forms, sign-ups, payments, attachments, and every write operation remain out of scope for this client.