Python implementation explained

Written by Elena David, SEO, ORM, and AI Visibility Consultant.

This reference connects Python implementation choices to observable application behavior. Read it after running the quickstart.

Imports and modules

Each .py file is a module. Relative imports connect modules inside the package:

from .loader import Review

The leading dot means “from the current reputation_monitor package.” Standard-library imports omit the dot, as in import csv and from pathlib import Path.

Variables and data types

The project uses:

• strings for identifiers and review text;
• integers for ratings and process status codes;
• date objects for validated review dates;
• Path objects for filesystem locations;
• Boolean results from comparisons such as rating <= maximum_rating.

Type hints such as list[Review] document expected values and help static-analysis tools. Python does not automatically enforce these annotations at runtime.

Dataclasses

Review is a frozen dataclass:

@dataclass(frozen=True)
class Review:
    review_id: str
    practice_id: str
    practice_name: str
    review_date: date
    rating: int
    review_text: str
    source_label: str

The decorator generates initialization and representation behavior. frozen=True prevents field reassignment after construction.

Dictionaries and CSV parsing

csv.DictReader returns each input row as a dictionary keyed by header:

reader = csv.DictReader(csv_file)

The loader builds another dictionary containing only required values:

values = {field: (row.get(field) or "").strip() for field in REQUIRED_FIELDS}

This dictionary comprehension loops over each required field, retrieves its value, replaces a missing or None value with an empty string, and trims surrounding whitespace.

Lists, sets, and loops

Lists preserve review order. Sets support efficient membership checks and contain unique values:

previous_ids = {review.review_id for review in previous}

The reporter uses a conventional loop to create one output row per alert:

for review in alerts:
    writer.writerow({...})

Functions and return values

Functions separate tasks and make testing direct. find_new_reviews() accepts two review lists and returns a new list without reading files or printing output. load_reviews() returns a LoadResult containing both successful records and issues.

The CLI's run() returns 0 or 1. main() passes that value to SystemExit, making it the shell process status.

Conditions

Rating selection is expressed as a filtering condition:

return [review for review in reviews if review.rating <= maximum_rating]

The if clause keeps only reviews for which the comparison is true.

Paths and file contexts

Path.open() returns a file object. The with statement closes it even if an error occurs:

with csv_path.open("r", encoding="utf-8-sig", newline="") as csv_file:
    reader = csv.DictReader(csv_file)

Before writing, output_path.parent.mkdir(parents=True, exist_ok=True) creates missing output directories.

Exceptions

Row conversion raises ValueError for invalid content. load_reviews() catches it inside the row loop and records a ValidationIssue, so later rows can continue. The CLI catches expected file and structural errors around the complete load and returns status 1.

This difference defines recoverable row problems versus run-stopping problems. Read Error handling and validation for the complete mapping.

HTML escaping

The reporter applies html.escape() to text before inserting it into HTML. This ensures characters such as <, >, and & are represented as text. The CSV writer uses CSV quoting rather than HTML escaping because the two formats have different serialization rules.

Continue maintenance

Read the matching test beside each module before changing public behavior. Run focused tests during implementation and python -m pytest before packaging. Review web_importer.py especially carefully when changing URL handling, redirects, DNS checks, robots behavior, timeouts, or size limits.