How to Build a Data Helper Class in Python for Beginners

from __future__ import annotations

import json
from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional


@dataclass
class DataHelper:
    """A beginner-friendly helper for common data tasks."""

    data: List[Dict[str, Any]] = field(default_factory=list)

    def add_record(self, record: Dict[str, Any]) -> None:
        """Add a single record to the dataset."""
        self.data.append(record)

    def get_record(self, index: int) -> Optional[Dict[str, Any]]:
        """Retrieve a record by index safely."""
        if 0 <= index < len(self.data):
            return self.data[index]
        return None

    def filter_by_key(self, key: str, value: Any) -> List[Dict[str, Any]]:
        """Return records where the given key matches the value."""
        return [rec for rec in self.data if rec.get(key) == value]

    def summarize(self) -> Dict[str, Any]:
        """Print and return a basic summary of the dataset."""
        summary = {
            "total_records": len(self.data),
            "keys": list(self.data[0].keys()) if self.data else [],
        }
        print(json.dumps(summary, indent=2))
        return summary


if __name__ == "__main__":
    helper = DataHelper()
    helper.add_record({"name": "Alice", "age": 30, "city": "NYC"})
    helper.add_record({"name": "Bob", "age": 25, "city": "LA"})
    helper.add_record({"name": "Carol", "age": 30, "city": "Chicago"})

    print("Bob:", helper.get_record(1))
    print("Age 30:", helper.filter_by_key("age", 30))
    helper.summarize()