Utilities

Mostly used in the service.

utils

Classes:

Name	Description
BarePath
SupportsToDict
SupportsToPolars
Ok
Err
UnwrapError
ParamDetail
SphinxParser	A poor man's parser for Sphinx docstrings and its :param: directive.

Functions:

Name	Description
dataclass_frozen
to_unix_timestamp	Casts timestamp-like object to a Unix timestamp in integer seconds.
get_current_timestamp	Returns the current Unix timestamp in seconds.
parse_server_timestamp
to_flight_id
to_flight_id_hex	Converts flight ID to a hex string.
format_bare_path
write_table	Writes the table as the specified format via polars.
scan_table	Reads the table as the specified format via polars.
static_check_signature	Marker to signal the static analyser that the decorated method or

Attributes:

Name	Type	Description
dataclass_opts	dict[str, bool]
logger
DEFAULT_HEADERS
FileLike
FileExistsBehaviour	TypeAlias
DictT_co		The dictionary representation of an object, e.g. TypedDict.
T
E
Result	TypeAlias	A type that represents either success (Ok) or failure (Err).
M

dataclass_opts module-attribute

dataclass_opts: dict[str, bool] = {}

logger module-attribute

logger = getLogger(__name__)

DEFAULT_HEADERS module-attribute

DEFAULT_HEADERS = {
    "User-Agent": "Mozilla/5.0 (X11; Linux x86_64; rv:136.0) Gecko/20100101 Firefox/136.0",
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
    "Accept-Language": "en-US,en;q=0.5",
    "Accept-Encoding": "gzip, deflate, zstd",
    "Origin": "https://www.flightradar24.com",
    "Connection": "keep-alive",
    "Referer": "https://www.flightradar24.com/",
    "Sec-Fetch-Dest": "empty",
    "Sec-Fetch-Mode": "cors",
    "Sec-Fetch-Site": "same-site",
    "TE": "trailers",
}

FileLike module-attribute

FileLike = Union[str, Path, IO[bytes], BarePath]

FileExistsBehaviour module-attribute

FileExistsBehaviour: TypeAlias = Literal[
    "backup", "error", "overwrite"
]

DictT_co module-attribute

DictT_co = TypeVar('DictT_co', covariant=True)

The dictionary representation of an object, e.g. TypedDict.

T module-attribute

T = TypeVar('T')

E module-attribute

E = TypeVar('E')

Result module-attribute

Result: TypeAlias = Union[Ok[T], Err[E]]

A type that represents either success (Ok) or failure (Err).

M module-attribute

M = TypeVar('M', bound=Callable[..., Any])

BarePath

Attributes:

Name	Type	Description
path	Path

path instance-attribute

path: Path

SupportsToDict

Bases: Protocol[DictT_co]

Methods:

Name	Description
to_dict	Converts the object into a dictionary.

to_dict

to_dict() -> DictT_co

Converts the object into a dictionary.

SupportsToPolars

Bases: Protocol

Methods:

Name	Description
to_polars	Converts the object into a polars dataframe.

to_polars

to_polars() -> DataFrame

Converts the object into a polars dataframe.

Ok

Bases: Generic[T]

Methods:

Name	Description
ok
err
is_ok
is_err
unwrap

ok

ok() -> T

err

err() -> None

is_ok

is_ok() -> Literal[True]

is_err

is_err() -> Literal[False]

unwrap

unwrap() -> T

Err

Bases: Generic[E]

Methods:

Name	Description
ok
err
is_ok
is_err
unwrap

ok

ok() -> None

err

err() -> E

is_ok

is_ok() -> Literal[False]

is_err

is_err() -> Literal[True]

unwrap

unwrap() -> NoReturn

UnwrapError

UnwrapError(err: Any, message: str)

Bases: Exception

Attributes:

Name	Type	Description
err	Any

err property

err: Any

ParamDetail

Bases: NamedTuple

Attributes:

Name	Type	Description
name	str
description	str

name instance-attribute

name: str

description instance-attribute

description: str

SphinxParser dataclass

SphinxParser(
    text: str,
    name: str | None = None,
    doc_lines: list[str] = list(),
)

A poor man's parser for Sphinx docstrings and its :param: directive.

Methods:

Name	Description
__iter__

Attributes:

Name	Type	Description
text	str
name	str | None
doc_lines	list[str]

text instance-attribute

text: str

name class-attribute instance-attribute

name: str | None = None

doc_lines class-attribute instance-attribute

doc_lines: list[str] = field(default_factory=list)

__iter__

__iter__() -> Iterator[str | ParamDetail]

dataclass_frozen

dataclass_frozen(cls: type[_D]) -> type[_D]

to_unix_timestamp

to_unix_timestamp(
    timestamp: IntoTimestamp | Literal["now"] | str,
) -> IntTimestampS | Literal["now"]

to_unix_timestamp(timestamp: None) -> None

to_unix_timestamp(
    timestamp: IntoTimestamp | str | Literal["now"] | None,
) -> IntTimestampS | Literal["now"] | None

Casts timestamp-like object to a Unix timestamp in integer seconds.

get_current_timestamp

get_current_timestamp() -> IntTimestampS

Returns the current Unix timestamp in seconds.

parse_server_timestamp

parse_server_timestamp(
    response: Response,
) -> IntTimestampS | None

to_flight_id

to_flight_id(flight_id: IntoFlightId) -> IntFlightId

to_flight_id_hex

to_flight_id_hex(flight_id: IntoFlightId) -> StrFlightIdHex

Converts flight ID to a hex string.

format_bare_path

format_bare_path(
    path: BarePath, format: TabularFileFmt
) -> Path

write_table

write_table(
    result: SupportsToPolars,
    file: FileLike,
    *,
    format: TabularFileFmt = "parquet",
    when_file_exists: FileExistsBehaviour = "backup",
    **kwargs: Any,
) -> None

Writes the table as the specified format via polars.

Parameters:

Name	Type	Description	Default
file	FileLike	File path or writable file-like object. The path will be given an appropriate suffix if it is a BarePath.	required

scan_table

scan_table(
    file: FileLike,
    *,
    format: TabularFileFmt = "parquet",
    schema: dict[str, DataType] | None = None,
) -> LazyFrame

Reads the table as the specified format via polars.

Parameters:

Name	Type	Description	Default
file	FileLike	File path or readable file-like object. The path will be given an appropriate suffix if it is a BarePath.	required
schema	dict[str, DataType] | None	The schema to enforce when reading the table. For CSV files, this should be specified to properly parse datetimes from strings.	None

static_check_signature

static_check_signature(
    dataclass: Any,
) -> Callable[[M], M]

Marker to signal the static analyser that the decorated method or function should be checked against the signature of the given dataclass.

Many of our low level APIs use 1) parameters stored in a single flat dataclass, and 2) functions that take in this dataclass:

@dataclass
class LiveFeedParams:
    bbox_south: float
    """Latitude, minimum, degrees"""
    bbox_north: float
    bbox_west: float
    bbox_east: float
    flight_id: int
    # ... other params ...

def live_feed(params: LiveFeedParams, ...):
    ...

but service methods and CLIs expect a flat signature:

from fr24.utils import static_check_signature

@static_check_signature(LiveFeedParams)
def live_feed_cli(
    bbox_south: float,
    bbox_north: float,
    bbox_west: float,
    bbox_east: float,
    flight_id: int
    # ... other params ...
):
    """:param bbox_south: The southern latitude of the bounding box.
    ..."""
    ...

./scripts/check_signature.py uses static analysis to:

1. scan for all uses of the decorator
2. for each member of the dataclass, collect all docstrings, members names and types
3. for each argument of the decorated method, parse the sphinx docstring, names and types
4. compare them.