API Reference

This page provides detailed API documentation for RepeaterBook.

Main Module

repeaterbook

Python utility to work with data from RepeaterBook.

Classes

RepeaterBook

RepeaterBook API client.

Attributes

database_path property

database_path: Path

Database path.

database_uri property

database_uri: str

Database URI.

engine cached property

engine: Engine

Create database engine.

Functions

init_db

init_db() -> None

Initialize database.

Source code in src/repeaterbook/database.py

def init_db(self) -> None:
    """Initialize database."""
    SQLModel.metadata.create_all(self.engine)

populate

populate(repeaters: Iterable[Repeater]) -> None

Populate internal database.

Source code in src/repeaterbook/database.py

def populate(self, repeaters: Iterable[Repeater]) -> None:
    """Populate internal database."""
    self.init_db()

    with Session(self.engine) as session:
        for repeater in repeaters:
            session.merge(repeater)
        session.commit()

    logger.info("Populated repeaters.")

query

query(*where: _ColumnExpressionArgument[bool] | bool) -> Sequence[Repeater]

Query the database.

Source code in src/repeaterbook/database.py

def query(
    self,
    *where: _ColumnExpressionArgument[bool] | bool,
) -> Sequence[Repeater]:
    """Query the database."""
    with Session(self.engine) as session:
        statement = select(Repeater).where(*where)
        repeaters = session.exec(statement).all()

    logger.info(f"Found {len(repeaters)} repeaters.")

    return repeaters

truncate

truncate() -> None

Truncate the database.

Source code in src/repeaterbook/database.py

def truncate(self) -> None:
    """Truncate the database."""
    with Session(self.engine) as session:
        session.exec(delete(Repeater))
        session.commit()

    logger.info("Truncated repeaters.")

RepeaterBookAPIError

Bases: RepeaterBookError

Error returned by the RepeaterBook API.

Raised when the API returns an error response (status: "error"). The error message from the API is preserved in the exception message.

RepeaterBookCacheError

Bases: RepeaterBookError

Error during cache operations.

Raised when reading from or writing to the cache fails, such as file permission issues or disk full errors.

RepeaterBookError

Bases: Exception

Base exception for RepeaterBook library.

All RepeaterBook-specific exceptions inherit from this class, making it easy to catch all library errors with a single except clause.

RepeaterBookUnauthorizedError

Bases: RepeaterBookAPIError

Unauthorized access to the API.

Raised when the API returns a 401 Unauthorized status code, indicating that authentication is required or has failed.

RepeaterBookValidationError

Bases: RepeaterBookError

Invalid data or response format.

Raised when: - API response is not in expected format (not a dict) - Required fields are missing from the response - Data values fail validation (e.g., invalid coordinates)

Repeater

Bases: SQLModel

Repeater.

Functions

validate_latitude classmethod

validate_latitude(v: Decimal) -> Decimal

Validate latitude is within valid range.

Source code in src/repeaterbook/models.py

@field_validator("latitude")
@classmethod
def validate_latitude(cls, v: Decimal) -> Decimal:
    """Validate latitude is within valid range."""
    if not Decimal(-90) <= v <= Decimal(90):
        msg = f"Latitude must be between -90 and 90, got {v}"
        raise ValueError(msg)
    return v

validate_longitude classmethod

validate_longitude(v: Decimal) -> Decimal

Validate longitude is within valid range.

Source code in src/repeaterbook/models.py

@field_validator("longitude")
@classmethod
def validate_longitude(cls, v: Decimal) -> Decimal:
    """Validate longitude is within valid range."""
    if not Decimal(-180) <= v <= Decimal(180):
        msg = f"Longitude must be between -180 and 180, got {v}"
        raise ValueError(msg)
    return v

validate_frequency classmethod

validate_frequency(v: Decimal) -> Decimal

Validate frequency is positive.

Source code in src/repeaterbook/models.py

@field_validator("frequency", "input_frequency")
@classmethod
def validate_frequency(cls, v: Decimal) -> Decimal:
    """Validate frequency is positive."""
    if v <= 0:
        msg = f"Frequency must be positive, got {v}"
        raise ValueError(msg)
    return v