Pitt API

PittAPI is an unofficial Python library for public data from the University of Pittsburgh and related services. Version 2.0 provides synchronous service clients and immutable, typed result models.

Installation

PittAPI requires Python 3.13. Add it to a uv-managed project with:

uv add pittapi

Client basics

Each data source has its own client. A client accepts an optional requests.Session and a timeout in seconds. When PittAPI creates the session, using the client as a context manager closes it automatically:

frompittapiimportCourseClientwithCourseClient(timeout=15) ascourses:
cs=courses.get_subject_courses("CS")
forcourseincs.courses:
print(course.course_number, course.course_title)

An injected session remains owned by the caller and is not closed by PittAPI.

All structured results are frozen, slotted dataclasses. Nested collections are tuples, so callers cannot accidentally change a response after it is returned.

Examples

fromdatetimeimportdatetimefrompittapiimportDiningClient, LibraryClient, NewsClientwithDiningClient() asdining:
locations=dining.get_locations()
hours=dining.get_location_hours("The Eatery", datetime(2024, 4, 12))
withLibraryClient() aslibrary:
books=library.get_documents("computer science")
withNewsClient() asnews:
topics=news.get_topics()
technology=next(topicfortopicintopicsiftopic.name=="Technology & Science")
articles=news.get_articles_by_topic(technology, max_num_results=5)

Services whose available resources change over time provide discovery methods:

frompittapiimportLabClient, LaundryClient, ShuttleClient, TextbookClientfrompittapi.textbookimportCourseInfowithLabClient() aslabs:
locations=labs.get_locations()
status=labs.get_status(locations[0])
withLaundryClient() aslaundry:
rooms=laundry.get_locations()
machines=laundry.get_machine_statuses(rooms[0])
withShuttleClient() asshuttle:
configuration=shuttle.get_configuration()
routes=shuttle.get_routes(configuration)
withTextbookClient() astextbooks:
term=next(termfortermintextbooks.get_terms() ifterm.inquiry_enabled)
textbooks.select_term(term)
books=textbooks.get_textbooks_for_course(CourseInfo("CS", "0441"))

Network and HTTP failures remain standard requests exceptions. Invalid arguments or malformed provider responses raise ValueError; a valid lookup with no matching entity raises LookupError.

Users upgrading from PittAPI 1.x should read the 2.0 migration guide.

Development

Install the locked Python 3.13 development environment and run the full validation suite:

uv sync --locked
uv run pytest --cov=pittapi --cov-branch --cov-fail-under=100 tests/
uv run pre-commit run --all-files

See the contributing guidelines for the project’s readability and testing expectations.

License

PittAPI is licensed under the GPLv2.