Models

Dataclasses and enums used throughout the library. Everything here is exported directly from rmp_api.

Data flow

Most workflows follow this path:

search_schools returns list[SchoolResult] -- use school.id for professor searches.
search_professors returns list[ProfessorResult] -- use professor.id for rating fetches.
get_professor_summary returns a ProfessorRating with aggregated stats.
get_all_ratings / get_ratings_page return list[Rating] with individual student reviews.
compute_score takes list[Rating] and returns a ProfessorScore.
compare_professors takes multiple list[Rating] inputs and returns a ProfessorComparison.
compute_score_over_time returns a ScoreTimeline.
compute_split_score returns a SplitScore.

Sentinel values

ProfessorRating uses sentinel values when no professor is found:

avg_rating, avg_difficulty, would_take_again_percent are set to -1
num_ratings is set to 0
link is set to ""

Always check num_ratings > 0 before using a ProfessorRating's numeric fields.

ProfessorScore uses 0 as a sentinel (returned when compute_score receives an empty list).

Reference

Dataclasses and enums shared across the rmp_api package.

`ProfessorComparison` `dataclass`

Side-by-side comparison of multiple professors ranked by a chosen signal.

Produced by :func:~scoring.compare_professors.

Attributes:

Name	Type	Description
`ranking`	`list[tuple[str, ProfessorScore]]`	List of `(label, score)` pairs sorted best -> worst by `sort_by`.
`scores`	`dict[str, ProfessorScore]`	`{label: ProfessorScore}` mapping for direct lookup.
`sort_by`	`str`	Name of the :class:`ProfessorScore` field used for ranking.
`best`	`str`	Label of the top-ranked professor.
`worst`	`str`	Label of the lowest-ranked professor.
`deltas`	`dict[str, float]`	`{label: float}` showing each professor's `sort_by` value minus the best professor's value. Best professor has `delta = 0.0`; all others are `<= 0.0`.

`ProfessorRating` `dataclass`

Aggregate stats for a professor from their RMP profile.

Sentinel values (returned when no professor is found): avg_rating, avg_difficulty, and would_take_again_percent are set to -1; num_ratings is 0; link is "".

Attributes:

Name	Type	Description
`avg_rating`	`float`	Mean overall rating (0.0–5.0).
`avg_difficulty`	`float`	Mean difficulty rating (0.0–5.0).
`would_take_again_percent`	`float`	Percentage of students who would take again (0.0–100.0). `-1` if not enough data.
`num_ratings`	`int`	Total number of submitted ratings.
`formatted_name`	`str`	Full name as `"<firstName> <lastName>"`.
`department`	`str`	Academic department string (e.g. `"Computer Science"`).
`link`	`str`	URL to the professor's RMP page.

`ProfessorResult` `dataclass`

A professor returned by :func:~client.search_professors.

Attributes:

Name	Type	Description
`id`	`str`	Base64-encoded RMP node ID. Pass this as `professor_id` to other functions.
`legacy_id`	`int`	Legacy numeric professor ID. Only useful for building URLs like `https://www.ratemyprofessors.com/professor/{legacy_id}`.
`first_name`	`str`	Professor's first name.
`last_name`	`str`	Professor's last name.
`department`	`str`	Academic department string (e.g. `"Computer Science"`).
`school_name`	`str`	Name of the school this result is associated with.
`avg_rating`	`float`	Mean overall rating on this professor's RMP profile (0.0-5.0).
`avg_difficulty`	`float`	Mean difficulty rating (0.0-5.0).
`num_ratings`	`int`	Total number of submitted ratings.
`would_take_again_percent`	`float`	Percentage of students who would take again (0.0-100.0). `-1` if not enough data.

`ProfessorScore` `dataclass`

All quality signals computed from a professor's :class:Rating list.

Produced by :func:~scoring.compute_score. All scores are normalized unless noted otherwise.

Attributes:

Name	Type	Description
`num_ratings`	`int`	Total number of ratings used to compute this score.
`raw_avg_rating`	`float`	Simple mean of `(helpful + clarity) / 2` across all ratings (1–5).
`avg_clarity`	`float`	Mean clarity rating (1–5).
`avg_helpfulness`	`float`	Mean helpfulness rating (1–5).
`avg_difficulty`	`float`	Mean difficulty rating (1–5). `0.0` if no difficulty data.
`recency_weighted_rating`	`float`	Exponential-decay-weighted mean of overall quality (1–5). Older ratings contribute less; half-life configurable in `compute_score`.
`reliability_score`	`float`	Bayesian confidence based on sample size (0–1). ~0.5 at 25 ratings, approaches 1 asymptotically.
`easiness_score`	`float`	Inverse of average difficulty, normalised to 0–1. `1.0` = easiest (avg difficulty 1), `0.0` = hardest (avg difficulty 5).
`would_take_again_pct`	`float`	Fraction of students who would take the professor again (0–1).
`last_review_date`	`str \| None`	Date of the most recent rating as `"YYYY-MM-DD"`, or `None`.
`review_velocity`	`float`	Reviews posted per year within a 2-year rolling window.
`top_tags`	`list[tuple[str, int]]`	Up to 10 most common student-selected tags as `(tag, count)` pairs.
`difficulty_histogram`	`dict[int, int]`	Count of ratings per difficulty bucket `{1: n, 2: n, …, 5: n}`.
`composite_score`	`float`	Weighted combination of signals, clamped to `[0, 1]`. Weights determined by the preset or custom dict passed to `compute_score`.

`Rating` `dataclass`

Single student rating for a professor.

Attributes:

Name	Type	Description
`id`	`str`	Base64-encoded RMP node ID for this rating.
`legacy_id`	`int`	Legacy numeric rating ID.
`comment`	`str`	Student's written review text.
`date`	`str`	Submission date string (ISO 8601, e.g. `"2024-03-15 00:00:00 +0000 UTC"`).
`course`	`str`	Course code the student reviewed for (e.g. `"CS61A"`).
`helpful_rating`	`float`	Helpfulness score (1.0–5.0).
`clarity_rating`	`float`	Clarity score (1.0–5.0).
`difficulty_rating`	`float`	Difficulty score (1.0–5.0).
`rating_tags`	`list[str]`	List of tag strings selected by the student (e.g. `["Tough grader", "Clear grading"]`).
`flag_status`	`str`	Moderation status (e.g. `"FLAGGED"`, `"UNFLAGGED"`).
`attendance_mandatory`	`str \| None`	Whether attendance was mandatory (`"mandatory"`, `"non mandatory"`, or `None`).
`would_take_again`	`int \| None`	`1` if yes, `0` if no, `None` if not answered.
`grade`	`str \| None`	Self-reported grade received (e.g. `"A+"`, `"B"`), or `None`.
`textbook_use`	`int \| None`	Textbook usage score (0–5 scale), or `None` if not answered.
`is_for_online_class`	`bool`	`True` if the rating is for an online section.
`is_for_credit`	`bool`	`True` if the student took the course for credit.
`thumbs_up_total`	`int`	Number of helpful votes on this rating.
`thumbs_down_total`	`int`	Number of unhelpful votes on this rating.
`teacher_note`	`str \| None`	Professor's response comment, or `None` if no response.

`SchoolResult` `dataclass`

A school returned by :func:~client.search_schools.

Attributes:

Name	Type	Description
`id`	`str`	Base64-encoded RMP node ID. Pass this as `school_id` to other functions.
`legacy_id`	`int`	Legacy numeric school ID. Only useful for building URLs like `https://www.ratemyprofessors.com/school/{legacy_id}`.
`name`	`str`	Full school name (e.g. `"University of California, Berkeley"`).
`city`	`str`	City the school is located in.
`state`	`str`	State or province abbreviation.
`num_ratings`	`int`	Total number of professor ratings at this school.
`avg_rating`	`float`	Average professor rating across the school (0.0-5.0).

`ScoreTimeline` `dataclass`

Professor scores bucketed over time with a linear trend.

Produced by :func:~scoring.compute_score_over_time. Buckets are sorted oldest -> newest; each contains a full :class:ProfessorScore computed from only the ratings in that period.

Attributes:

Name	Type	Description
`periods`	`list[tuple[str, ProfessorScore]]`	List of `(label, score)` pairs, oldest first. Label format depends on the `period` argument: `"year"` -> `"2023"`; `"semester"` -> `"2023-Spring"` / `"2023-Fall"`; `"quarter"` -> `"2023-Q1"` … `"2023-Q4"`.
`trend`	`float`	Linear-regression slope of `composite_score` across bucket indices. Positive = improving over time; negative = declining.
`total_span_years`	`float`	Time span covered by all dated ratings in years.

`SortBy`

Bases: StrEnum

:class:~models.ProfessorScore field to rank by in :func:~scoring.compare_professors.

Members compare equal to their string values, so plain strings still work: SortBy.COMPOSITE_SCORE == "composite_score" is True.

Higher values are always ranked first. To rank by easiness (lower difficulty = better), use :attr:EASINESS_SCORE rather than :attr:AVG_DIFFICULTY.

Members

COMPOSITE_SCORE: Weighted composite (default). RAW_AVG_RATING: Mean of (helpful + clarity) / 2. AVG_CLARITY: Mean clarity rating. AVG_HELPFULNESS: Mean helpfulness rating. AVG_DIFFICULTY: Mean difficulty (higher = harder). RECENCY_WEIGHTED_RATING: Exponential-decay-weighted quality. RELIABILITY_SCORE: Bayesian confidence from sample size. EASINESS_SCORE: Inverse of average difficulty (higher = easier). WOULD_TAKE_AGAIN_PCT: Fraction who would take again. REVIEW_VELOCITY: Reviews per year (2-year window). NUM_RATINGS: Total rating count.

`SplitScore` `dataclass`

Professor scores split by delivery format.

Produced by :func:~scoring.compute_split_score. Each field is a full :class:ProfessorScore computed from the relevant subset of ratings.

Attributes:

Name	Type	Description
`online`	`ProfessorScore`	Score from ratings where `is_for_online_class` is `True`.
`in_person`	`ProfessorScore`	Score from ratings where `is_for_online_class` is `False`.
`combined`	`ProfessorScore`	Score from all ratings regardless of format.

`TimePeriod`

Bases: StrEnum

Time bucketing granularity for :func:~scoring.compute_score_over_time.

Members compare equal to their string values, so plain strings still work: TimePeriod.YEAR == "year" is True.

Members

YEAR: Annual buckets — "2023". SEMESTER: Half-year buckets — "2023-Spring" / "2023-Fall". QUARTER: Quarterly buckets — "2023-Q1" … "2023-Q4".

Models

Data flow

Sentinel values

Reference

ProfessorComparison dataclass

ProfessorRating dataclass

ProfessorResult dataclass

ProfessorScore dataclass

Rating dataclass

SchoolResult dataclass

ScoreTimeline dataclass

SortBy

SplitScore dataclass

TimePeriod

`ProfessorComparison` `dataclass`

`ProfessorRating` `dataclass`

`ProfessorResult` `dataclass`

`ProfessorScore` `dataclass`

`Rating` `dataclass`

`SchoolResult` `dataclass`

`ScoreTimeline` `dataclass`

`SortBy`

`SplitScore` `dataclass`

`TimePeriod`