fr24 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
fr24-0.1.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 Abraham Cheung
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
fr24-0.1.1/PKG-INFO ADDED
@@ -0,0 +1,61 @@
1
+ Metadata-Version: 2.1
2
+ Name: fr24
3
+ Version: 0.1.1
4
+ Summary: Parse gRPC and JSON data from FlightRadar24
5
+ Home-page: https://github.com/cathaypacific8747/fr24/
6
+ License: MIT
7
+ Author: Abraham Cheung
8
+ Author-email: abraham@ylcheung.com
9
+ Requires-Python: >=3.9,<4.0
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.9
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Requires-Dist: appdirs (>=1.4.4,<2.0.0)
17
+ Requires-Dist: brotli (>=1.1.0,<2.0.0)
18
+ Requires-Dist: click (>=8.1.7,<9.0.0)
19
+ Requires-Dist: httpx (>=0.25.1,<0.26.0)
20
+ Requires-Dist: loguru (>=0.7.2,<0.8.0)
21
+ Requires-Dist: pandas[parquet] (>=2.1.3,<3.0.0)
22
+ Requires-Dist: protobuf (>=4.25.0,<5.0.0)
23
+ Requires-Dist: pyarrow (>=14.0.1,<15.0.0)
24
+ Requires-Dist: textual (>=0.54.0,<0.55.0)
25
+ Requires-Dist: typer[all] (>=0.11.0,<0.12.0)
26
+ Description-Content-Type: text/markdown
27
+
28
+ # fr24
29
+
30
+ fr24 is a library for downloading data from [Flightradar24](https://flightradar24.com) using [gRPC](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md) and JSON.
31
+
32
+ It supports querying live feed snapshots/playback, trajectory history and other miscellaneous metadata.
33
+
34
+ Please see the [documentation](https://cathaypacific8747.github.io/fr24/) for detailed usage guides.
35
+
36
+ ## Installation and Usage
37
+
38
+ Clone the repository and run in the directory:
39
+
40
+ ```sh
41
+ pip install .
42
+ ```
43
+
44
+ For a development version, you may want to use Poetry:
45
+
46
+ ```sh
47
+ poetry install
48
+ poetry shell
49
+ ```
50
+
51
+ ## License
52
+
53
+ > [!IMPORTANT]
54
+ > Code has been developed for educational purposes ONLY. Do not abuse it.
55
+
56
+ ```json
57
+ {
58
+ "copyright": "Copyright (c) 2014-2023 Flightradar24 AB. All rights reserved.",
59
+ "legalNotice": "The contents of this file and all derived data are the property of Flightradar24 AB for use exclusively by its products and applications. Using, modifying or redistributing the data without the prior written permission of Flightradar24 AB is not allowed and may result in prosecutions."
60
+ }
61
+ ```
fr24-0.1.1/README.md ADDED
@@ -0,0 +1,34 @@
1
+ # fr24
2
+
3
+ fr24 is a library for downloading data from [Flightradar24](https://flightradar24.com) using [gRPC](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md) and JSON.
4
+
5
+ It supports querying live feed snapshots/playback, trajectory history and other miscellaneous metadata.
6
+
7
+ Please see the [documentation](https://cathaypacific8747.github.io/fr24/) for detailed usage guides.
8
+
9
+ ## Installation and Usage
10
+
11
+ Clone the repository and run in the directory:
12
+
13
+ ```sh
14
+ pip install .
15
+ ```
16
+
17
+ For a development version, you may want to use Poetry:
18
+
19
+ ```sh
20
+ poetry install
21
+ poetry shell
22
+ ```
23
+
24
+ ## License
25
+
26
+ > [!IMPORTANT]
27
+ > Code has been developed for educational purposes ONLY. Do not abuse it.
28
+
29
+ ```json
30
+ {
31
+ "copyright": "Copyright (c) 2014-2023 Flightradar24 AB. All rights reserved.",
32
+ "legalNotice": "The contents of this file and all derived data are the property of Flightradar24 AB for use exclusively by its products and applications. Using, modifying or redistributing the data without the prior written permission of Flightradar24 AB is not allowed and may result in prosecutions."
33
+ }
34
+ ```
@@ -0,0 +1,77 @@
1
+ [tool.poetry]
2
+ name = "fr24"
3
+ homepage = "https://github.com/cathaypacific8747/fr24/"
4
+ version = "0.1.1"
5
+ description = "Parse gRPC and JSON data from FlightRadar24"
6
+ authors = ["Abraham Cheung <abraham@ylcheung.com>", "Xavier Olive <git@xoolive.org>"]
7
+ license = "MIT"
8
+ include = [ "LICENSE", "py.typed", "request.proto", "style.tcss" ]
9
+ readme = "README.md"
10
+
11
+ [tool.poetry.scripts]
12
+ fr24 = 'fr24.cli:app'
13
+
14
+ [tool.poetry.dependencies]
15
+ python = ">=3.9,<4.0"
16
+ pandas = { extras = ["parquet"], version = "^2.1.3" }
17
+ pyarrow = "^14.0.1"
18
+ httpx = "^0.25.1"
19
+ protobuf = "^4.25.0"
20
+ brotli = "^1.1.0"
21
+ click = "^8.1.7"
22
+ appdirs = "^1.4.4"
23
+ textual = "^0.54.0"
24
+ loguru = "^0.7.2"
25
+ typer = {extras = ["all"], version = "^0.11.0"}
26
+
27
+ [tool.poetry.group.dev.dependencies]
28
+ ipykernel = "^6.26.0"
29
+ pytest = "^7.4.3"
30
+ pytest-asyncio = "^0.23.6"
31
+ ruff = "^0.3.4"
32
+ mypy = "^1.7.0"
33
+ textual-dev = "^1.2.1"
34
+ types-protobuf = "^4.24.0.4"
35
+
36
+
37
+ [tool.poetry.group.docs.dependencies]
38
+ mkdocs-material = {extras = ["imaging"], version = "^9.5.15"}
39
+ mkdocstrings-python = "^1.9.0"
40
+ black = "^24.3.0"
41
+
42
+ [build-system]
43
+ requires = ["poetry-core>=1.0.0"]
44
+ build-backend = "poetry.core.masonry.api"
45
+
46
+ [tool.ruff]
47
+ lint.select = [
48
+ "E", "W", # pycodestyle
49
+ "F", # pyflakes
50
+ "I", # isort
51
+ "NPY", # numpy
52
+ # "PD", # pandas
53
+ "DTZ", # flake8-datetimez
54
+ "RUF"
55
+ ]
56
+ exclude = ["proto"]
57
+ line-length = 80
58
+ target-version = "py39"
59
+
60
+ [tool.ruff.lint.isort]
61
+ known-first-party = ["numpy", "pandas"]
62
+
63
+ [tool.mypy]
64
+ python_version = 3.9
65
+ exclude = ["proto"]
66
+ platform = "posix"
67
+
68
+ color_output = true
69
+ pretty = true
70
+ show_column_numbers = true
71
+ strict = true
72
+ check_untyped_defs = true
73
+ ignore_missing_imports = true
74
+ warn_no_return = true
75
+ warn_redundant_casts = true
76
+ warn_unused_configs = true
77
+ warn_unused_ignores = true
File without changes
@@ -0,0 +1,3 @@
1
+ from .cli import app
2
+
3
+ app(prog_name="fr24")
@@ -0,0 +1,56 @@
1
+ from __future__ import annotations
2
+
3
+ import configparser
4
+ import os
5
+ from pathlib import Path
6
+
7
+ import httpx
8
+ from appdirs import user_config_dir
9
+
10
+ from .common import DEFAULT_HEADERS
11
+ from .types.fr24 import Authentication
12
+
13
+ username = os.environ.get("fr24_username", None)
14
+ password = os.environ.get("fr24_password", None)
15
+ subscription_key = os.environ.get("fr24_subscription_key", None)
16
+ token = os.environ.get("fr24_token", None)
17
+
18
+ if (config_file := (Path(user_config_dir("fr24")) / "fr24.conf")).exists():
19
+ config = configparser.ConfigParser()
20
+ config.read(config_file.as_posix())
21
+
22
+ username = config.get("global", "username", fallback=None)
23
+ password = config.get("global", "password", fallback=None)
24
+ subscription_key = config.get("global", "subscription_key", fallback=None)
25
+ token = config.get("global", "token", fallback=None)
26
+
27
+
28
+ async def login(client: httpx.AsyncClient) -> None | Authentication:
29
+ """
30
+ Create credentials for the user (if any). If the environment variables:
31
+
32
+ - `subscription_key` and `token` is set: it returns the pair
33
+ - `username` and `password` is set: it fetches the token and
34
+ subscription key from the API
35
+ - otherwise, it returns `None`
36
+ """
37
+ if username is None or password is None:
38
+ if not subscription_key:
39
+ return None
40
+ return {
41
+ "userData": {
42
+ "subscriptionKey": subscription_key,
43
+ "accessToken": token,
44
+ },
45
+ "message": "using subscriptionKey and/or accessToken.",
46
+ }
47
+
48
+ res = await client.post(
49
+ "https://www.flightradar24.com/user/login",
50
+ data={"email": username, "password": password},
51
+ headers=DEFAULT_HEADERS,
52
+ )
53
+ res.raise_for_status()
54
+ return res.json() # type: ignore
55
+ # json['userData']['accessToken'] => Bearer
56
+ # json['userData']['subscriptionKey'] => token
@@ -0,0 +1,157 @@
1
+ from __future__ import annotations
2
+
3
+ from abc import ABC, abstractmethod
4
+ from pathlib import Path
5
+ from typing import Any, Generic, TypeVar
6
+
7
+ import httpx
8
+ import pyarrow as pa
9
+ import pyarrow.parquet as pq
10
+ from loguru import logger
11
+ from typing_extensions import Self
12
+
13
+ import pandas as pd
14
+
15
+ from .authentication import login
16
+ from .types.fr24 import Authentication
17
+
18
+
19
+ class HTTPClient:
20
+ """
21
+ An HTTPX client for making requests to the API and storing
22
+ authentication data.
23
+ """
24
+
25
+ def __init__(self, *, retries: int = 5) -> None:
26
+ transport = httpx.AsyncHTTPTransport(retries=retries)
27
+ self.client = httpx.AsyncClient(transport=transport)
28
+ self.auth: Authentication | None = None
29
+
30
+ async def __aenter__(self) -> Self:
31
+ self.auth = await login(self.client)
32
+ return self
33
+
34
+ async def __aexit__(self, *args: Any) -> None:
35
+ if self.client is not None:
36
+ await self.client.aclose()
37
+
38
+
39
+ ApiRsp = TypeVar("ApiRsp")
40
+ """Type returned by the API, e.g. [fr24.types.fr24.FlightList][]"""
41
+ Ctx = TypeVar("Ctx")
42
+ """Type of the context for the service, a TypedDict"""
43
+
44
+
45
+ class APIBase(Generic[ApiRsp, Ctx], ABC):
46
+ def __init__(self, http: HTTPClient, ctx: Ctx) -> None:
47
+ self.http = http
48
+ self.ctx = ctx
49
+
50
+ @abstractmethod
51
+ async def fetch(self, *args: Any, **kwargs: Any) -> ApiRsp:
52
+ """Fetch data from the API."""
53
+ ...
54
+
55
+
56
+ class ArrowBase(Generic[ApiRsp, Ctx], ABC):
57
+ """A base class for handling arrow tables."""
58
+
59
+ schema: pa.Schema | None = None
60
+
61
+ def __init__(self, base_dir: str, ctx: Ctx) -> None:
62
+ self.base_dir = Path(base_dir)
63
+ self._table: pa.Table | None = None
64
+ self.ctx = ctx
65
+
66
+ @property
67
+ @abstractmethod
68
+ def fp(self) -> Path:
69
+ """Path to the parquet file."""
70
+ ...
71
+
72
+ @property
73
+ def table(self) -> pa.Table | None:
74
+ return self._table
75
+
76
+ @table.setter
77
+ def table(self, table: pa.Table) -> None:
78
+ """Set the arrow table or extend it if it already exists."""
79
+ self._table = (
80
+ table
81
+ if self._table is None
82
+ else self._concat_tables(self._table, table)
83
+ )
84
+
85
+ @staticmethod
86
+ def _concat_tables(tbl_old: pa.Table, tbl_new: pa.Table) -> pa.Table:
87
+ """Override this to customize how tables should be concatenated."""
88
+ return pa.concat_tables([tbl_old, tbl_new])
89
+
90
+ @abstractmethod
91
+ def add_api_response(self, data: ApiRsp) -> Self:
92
+ """Parse API response and add to the arrow table."""
93
+
94
+ def add_parquet(self, fp: Path | None = None) -> Self:
95
+ """
96
+ Read parquet file and add to the arrow table.
97
+
98
+ :param fp: Path to the parquet file - if not provided, the default cache
99
+ directory is used.
100
+ """
101
+ out_fp = fp if fp is not None else self.fp
102
+
103
+ # pq.read_table apparently doesn't read schema metadata:
104
+ # overwriting self.schema using pq.read_schema instead.
105
+ sch = pq.read_schema(out_fp)
106
+ if sch_diffs := set(sch).difference(set(self.schema or [])):
107
+ logger.warning(f"Parquet schema mismatch:\n{sch_diffs}, will cast.")
108
+ sch = sch.cast(self.schema) # attempt to cast the schema
109
+ self.schema = sch
110
+
111
+ self.table = pq.read_table(out_fp, **self._schema_kwargs)
112
+ num_rows = self._table.num_rows if self._table is not None else 0
113
+ logger.debug(f"Read {out_fp}: {num_rows=}")
114
+ return self
115
+
116
+ def save_parquet(self, fp: Path | None = None) -> Self:
117
+ """
118
+ Write the arrow table to a parquet file.
119
+ :param fp: Path to the parquet file - if not provided, the default cache
120
+ directory is used.
121
+ """
122
+ if self._table is None:
123
+ logger.warning("No data to write.")
124
+ return self
125
+ out_fp = fp if fp is not None else self.fp
126
+ out_fp.parent.mkdir(parents=True, exist_ok=True)
127
+ with pq.ParquetWriter(out_fp, **self._schema_kwargs) as writer:
128
+ writer.write_table(self._table)
129
+ logger.debug(f"Saved {self._table.num_rows} rows to {out_fp}")
130
+ return self
131
+
132
+ def clear(self) -> None:
133
+ """Clear the arrow table."""
134
+ self._table = None
135
+
136
+ @property
137
+ def _schema_kwargs(self) -> dict[str, Any]:
138
+ return {} if self.schema is None else {"schema": self.schema}
139
+
140
+ @property
141
+ def df(self) -> pd.DataFrame | None:
142
+ return self._table.to_pandas() if self._table is not None else None
143
+
144
+
145
+ ApiBaseT = TypeVar("ApiBaseT")
146
+ """`APIBase[ApiRsp]`"""
147
+ FileBaseT = TypeVar("FileBaseT")
148
+ """`FileBase[ApiRsp]`"""
149
+
150
+
151
+ class ServiceBase(Generic[ApiBaseT, FileBaseT, Ctx]):
152
+ """A service to handle the API and file operations."""
153
+
154
+ def __init__(self, api: ApiBaseT, data: FileBaseT, ctx: Ctx) -> None:
155
+ self.api = api
156
+ self.data = data
157
+ self.ctx = ctx
@@ -0,0 +1,102 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ from datetime import datetime
5
+ from pathlib import Path
6
+ from typing import Annotated, Optional
7
+
8
+ import rich
9
+ import typer
10
+ from appdirs import user_cache_dir, user_config_dir
11
+
12
+ from .core import FR24, FlightListService, LiveFeedService, PlaybackService
13
+ from .tui.tui import main as tui_main
14
+
15
+ app = typer.Typer(no_args_is_help=True)
16
+
17
+
18
+ @app.command()
19
+ def dirs() -> None:
20
+ """Shows relevant directories"""
21
+ rich.print(f"Config: {user_config_dir('fr24')}")
22
+ rich.print(f" Cache: {user_cache_dir('fr24')}")
23
+
24
+
25
+ @app.command()
26
+ def tui() -> None:
27
+ """Starts the TUI"""
28
+
29
+ tui_main()
30
+
31
+
32
+ app_auth = typer.Typer()
33
+ app.add_typer(
34
+ app_auth,
35
+ name="auth",
36
+ no_args_is_help=True,
37
+ help="Commands for authentication",
38
+ )
39
+
40
+
41
+ @app_auth.command()
42
+ def show() -> None:
43
+ """Shows authentication status"""
44
+
45
+ async def show_() -> None:
46
+ async with FR24() as fr24:
47
+ if fr24.http.auth is None:
48
+ rich.print(
49
+ "[bold red]You are not authenticated.[/bold red]\n"
50
+ "Provide credentials in environment variables: either \n"
51
+ "- fr24_username + fr24_password or \n"
52
+ "- fr24_subscription_key + fr24_token\n"
53
+ "Alternatively, copy the example config file to "
54
+ f"{Path(user_config_dir('fr24')) / 'fr24.conf'}."
55
+ )
56
+ else:
57
+ rich.print("[bold green]Authenticated[/bold green]")
58
+ rich.print(fr24.http.auth)
59
+
60
+ asyncio.run(show_())
61
+
62
+
63
+ def get_success_message(
64
+ service: FlightListService | LiveFeedService | PlaybackService,
65
+ ) -> str:
66
+ num_rows = t.num_rows if (t := service.data.table) is not None else 0
67
+ size = service.data.fp.stat().st_size
68
+ return (
69
+ f"[bold green]Success: Saved {num_rows} rows ({size} bytes) "
70
+ f"to {service.data.fp}.[/bold green]"
71
+ )
72
+
73
+
74
+ @app.command()
75
+ def feed(
76
+ timestamp: Annotated[
77
+ Optional[int], typer.Option(help="Start unix timestamp (s, UTC)")
78
+ ] = None,
79
+ time: Annotated[
80
+ Optional[datetime], typer.Option(help="Start datetime (UTC)")
81
+ ] = None,
82
+ ) -> None:
83
+ """Fetches current livefeed / playback of live feed at a given time"""
84
+ # if time is None and timestamp is None:
85
+ # raise typer.BadParameter("Either time or timestamp must be set")
86
+ if time is not None and timestamp is not None:
87
+ raise typer.BadParameter("Only one of time and timestamp can be set")
88
+ if time is not None:
89
+ timestamp = int(time.timestamp())
90
+
91
+ async def feed_() -> None:
92
+ async with FR24() as fr24:
93
+ lf = fr24.livefeed(timestamp)
94
+ lf.data.add_api_response(await lf.api.fetch())
95
+ lf.data.save_parquet()
96
+ rich.print(get_success_message(lf))
97
+
98
+ asyncio.run(feed_())
99
+
100
+
101
+ if __name__ == "__main__":
102
+ app()
@@ -0,0 +1,45 @@
1
+ from __future__ import annotations
2
+
3
+ from datetime import datetime
4
+
5
+ import pandas as pd
6
+
7
+ DEFAULT_HEADERS = {
8
+ "User-Agent": "Mozilla/5.0 (X11; Linux x86_64; rv:109.0)"
9
+ "Gecko/20100101 Firefox/116.0",
10
+ "Accept": "text/html,application/xhtml+xml,application/xml;"
11
+ "q=0.9,image/avif,image/webp,*/*;q=0.8",
12
+ "Accept-Language": "en-US,en;q=0.5",
13
+ "Accept-Encoding": "gzip, deflate, br",
14
+ "Origin": "https://www.flightradar24.com",
15
+ "Connection": "keep-alive",
16
+ "Referer": "https://www.flightradar24.com/",
17
+ "Sec-Fetch-Dest": "empty",
18
+ "Sec-Fetch-Mode": "cors",
19
+ "Sec-Fetch-Site": "same-site",
20
+ "TE": "trailers",
21
+ }
22
+
23
+ DEFAULT_HEADERS_GRPC = {
24
+ **DEFAULT_HEADERS,
25
+ "Accept": "*/*",
26
+ "fr24-device-id": "web-00000000000000000000000000000000",
27
+ "x-envoy-retry-grpc-on": "unavailable",
28
+ "Content-Type": "application/grpc-web+proto",
29
+ "X-User-Agent": "grpc-web-javascript/0.1",
30
+ "X-Grpc-Web": "1",
31
+ "DNT": "1",
32
+ }
33
+
34
+
35
+ def to_unix_timestamp(
36
+ timestamp: int | datetime | pd.Timestamp | str | None,
37
+ ) -> int | None:
38
+ """
39
+ Casts timestamp-like object to Unix timestamp.
40
+ """
41
+ if isinstance(timestamp, (str, datetime)):
42
+ return int(pd.Timestamp(timestamp).timestamp())
43
+ if isinstance(timestamp, pd.Timestamp):
44
+ return int(timestamp.timestamp())
45
+ return timestamp