v0.2.0

breaking changes

see the latest documentation for more info

general api design

• the fr24.core module is replaced by fr24.service, fr24.cache, and fr24.configuration.
• all service methods (e.g., fr24.live_feed.fetch) now return a Result object (e.g., LiveFeedResult) instead of an APIResponse. you can access the raw bytes (.response.content), http headers (.response.headers), or use protocol-based methods to convert the data:
  • to_proto(): parses the response into a protobuf message.
  • to_dict(): parses the response into a python dictionary.
  • to_polars(): parses and transforms the data into a polars dataframe (if supported)
• the to_arrow() method and .df property on data objects are removed. use to_polars() to get a dataframe.
• the live_feed.fetch() method no longer fetches the entire world by default; it now requires a BoundingBox argument. to fetch global data, you can iterate through fr24.BBOXES_WORLD_STATIC.

flight list pagination

• the flight_list.fetch_all() method now returns an AsyncIterator[FlightListResult].
• the old data.concat(..., inplace=True) logic for upserting is removed. to paginate and merge, create a FlightListResultCollection and append results to it. calling .to_polars() on the collection will merge all flights and remove duplicates.

caching

• the ArrowTable base class, .save() and .load() methods on data objects are removed.
• caching is now handled by the FR24Cache class and the result.write_table(cache) method.
• reading from the cache is done via cache.<service>.scan_table(...), which returns a polars.LazyFrame.
• the FR24Cache instance provides access to different data collections via properties (e.g., cache.live_feed, cache.playback, cache.flight_list.reg).

low-level functions (fr24.json and fr24.grpc)

• now accepts a single Params dataclass argument instead of multiple keyword arguments.
• now require explicit headers and auth arguments.
• functions now return the raw httpx.Response. parsing the response (e.g., with .json() or fr24.proto.parse_data) is now a separate, explicit step.
• follow_flight_stream now yield raw bytes chunks instead of a full httpx.response object.

types and schemas

• type definitions have been reorganized into fr24.types.json and fr24.types.grpc.
• schemas for cached data are now in fr24.types.cache and use polars dtypes.
• the timestamp field in live_feed data is now a millisecond-precision datetime object (pl.Datetime("ms", time_zone="utc")) instead of a unix timestamp in seconds.

new gRPC APIs

• fr24.flight_details.fetch(): information for a live flight.
• fr24.playback_flight.fetch(): historical state vectors for a past flight.

CLI

• the cli has been completely restructured with far more commands available
• fr24 feed -> fr24 live-feed
• fr24 flight-list --all -> fr24 flight-list-all
• output is now controlled via -o/--output and can be a filepath, - for stdout, or cache for the default cache.
• new commands have been added for the new services (flight-details, playback-flight, etc.).
• the new --when-file-exists option (backup, error, overwrite) provides control over file output when a path already exists.

Migration guide

fetching and pasing

v0.2.0 replaces the old pandas/pyarrow setup with polars.LazyFrame. polars offer a far more ergonomic way to deal with dataframes and enables lazy file loading.

before (v0.1.4):

from fr24.core import FR24

async with FR24() as fr24:
    response = await fr24.live_feed.fetch()
    datac = response.to_arrow()
    print(datac.df) # pandas dataframe

after (v0.2.0):

from fr24 import FR24, BoundingBox

bbox = BoundingBox(south=42, north=52, west=-8, east=10) # now explicit

async with FR24() as fr24:
    result = await fr24.live_feed.fetch(bbox)
    
    print(result.response.content) # raw bytes
    print(result.to_proto()) # decoded google.protobuf.Message
    print(result.to_dict())
    print(result.to_polars()) # polars dataframe

caching

The new FR24Cache instance now mimics the service API, allowing you to read and write to from the cache.

before (v0.1.4):

response = await fr24.playback.fetch(0x2FB3041)
data = response.to_arrow()
data.save()  # where this is saved to?

# loads the entire parquet in memory :(
data_local = fr24.playback.load(0x2FB3041)
print(data_local.df)

after (v0.2.0):

from fr24 import FR24, FR24Cache

cache = FR24Cache.default()

async with FR24() as fr24:
    result = await fr24.playback.fetch(0x2FB3041)
    result.write_table(cache) # can be a `pathlib.Path` or a file-like object

# lazily load the parquet and collect the results
df_local = cache.playback.scan_table(0x2FB3041).collect()
print(df_local)

low-level apis: from **kwargs to params dataclasses

Low-level functions no longer accept a flat list of keyword arguments. Instead, they take a single strongly-typed flat Params dataclass.

before (v0.1.4):

from fr24.json import flight_list

list_ = await flight_list(client, flight="af291", timestamp="2024-04-01")

after (v0.2.0):

from fr24.json import flight_list, FlightListParams

params = FlightListParams(flight="af291", timestamp="2024-04-01")
response = await flight_list(client, params, headers, auth)
list_ = response.json() # parsing is now an explicit step