refactor: harden SDK error taxonomy, fix Python Makefile, add project…#103
Merged
Conversation
… docs Bump both SDKs to 1.5.1. Node SDK - Replace plain `Error` throws with `TypeError`/`RangeError` in `api.js`, `entities/entity.js` and `flightTrackerConfig.js`, matching the exception taxonomy already used by the Python SDK. Consumers catching the generic `Error` keep working; specific `instanceof` checks now match correctly. - Add `APIClient.requestStandalone()` — a stateless request path that reuses the TLS dispatcher but bypasses the shared cookie jar. Mirrors `request_standalone` in the Python SDK. - Use the new standalone path in `getAirports` and `getFlightDetails` so the concurrent fan-out cannot race writes onto the shared session cookies. - Export the method on `index.d.ts` so TypeScript consumers see it. Cross-SDK code clarity - Name the magic bearings in `get_bounds_by_point` (`bearing_sw` / `bearing_ne`) and add short comments explaining the haversine corner derivation. Python and Node updated in lockstep. Python packaging - Force-include `FlightRadar24/py.typed` in the wheel via `[tool.hatch.build.targets.wheel.force-include]` so downstream type checkers always see the PEP 561 marker, regardless of future changes to the global `exclude` list. Python Makefile (substantial revision) - Auto-detect `venv/` so `make test` / `make lint` / etc. work without `source venv/bin/activate` first. - Fix `make dev-setup` which previously installed dev dependencies into the system interpreter instead of the freshly created venv. - Centralise dev tooling in `DEV_TOOLS` so `install-dev` and `dev-setup` cannot drift; add `pip-audit` and remove deprecated `safety`. - Centralise coverage threshold in `COVERAGE_MIN = 60`. - Split `clean-build` (build artefacts) from `clean` (everything) so `build` / `validate` / `publish` no longer wipe coverage/test caches. - Make `all` depend on `install-dev` so a fresh checkout has flake8/mypy/ pytest available. - Drop redundant `install-deps` body (now an alias for `install`). - Drop redundant duplicate `pip install -e .` in `install`. - Drop unused `RED`/`BLUE` colour vars and dead `venv-activate` target. - Replace broken Sphinx `docs` target with `mkdocs build` (and add `docs-serve` for local preview); the site lives at the repo root. - `update-deps` now also upgrades the dev tools. - `venv` target uses literal `python3` to avoid the venv recreating itself through its own interpreter. Project documentation - Add `SECURITY.md` documenting the disclosure process, scope and supported-version policy. - Add `CONTRIBUTING.md` covering dev setup for both SDKs, the four test tiers, public surface that must stay aligned between Python and Node, style, and release/versioning rules. - Link both files from the top-level `README.md`.
Aligns the Python import name with the PyPI distribution name and with the
Node.js package name so both SDKs share the same identifier:
Python: from FlightRadarAPI import ...
Node.js: import { ... } from "flightradarapi" (unchanged for users)
Python side keeps `FlightRadar24` as a deprecation shim that re-exports the
new package and aliases every submodule via sys.modules; the shim emits a
DeprecationWarning so legacy `from FlightRadar24 import ...` keeps working
for one release. Node.js side has no shim because users already import via
the npm name `flightradarapi`, so the directory rename is invisible.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why is this PR necessary, what does it do?
This PR bundles two related changes to align and harden both SDKs (Python and Node.js).
1. Rename packages to
FlightRadarAPIAligns the Python internal package name with the PyPI distribution and with the npm package
flightradarapi, so both SDKs share the same identifier.FlightRadar24→FlightRadarAPI. A deprecation shim keepsfrom FlightRadar24 import ...working for one more release (re-exports the new packageand aliases every submodule via
sys.modules, emitting aDeprecationWarning).nodejs/FlightRadar24→nodejs/FlightRadarAPI). Since users import via the npm nameflightradarapi, the changeis invisible to consumers.
2. Harden error taxonomy, Python Makefile, and project docs (bump to 1.5.1)
Node SDK:
Errorthrows withTypeError/RangeErrorinapi.js,entities/entity.js, andflightTrackerConfig.js, matching the taxonomy alreadyused by the Python SDK. Specific
instanceofchecks now work correctly.APIClient.requestStandalone()— a stateless request path that reuses the TLS dispatcher but bypasses the shared cookie jar (mirrorsrequest_standalonein the Python SDK).
getAirportsandgetFlightDetailsnow use it, so concurrent fan-out can't race writes onto session cookies.index.d.ts.Cross-SDK code clarity:
get_bounds_by_point(bearing_sw/bearing_ne) with short comments explaining the haversine corner derivation. Python and Nodeupdated in lockstep.
Python packaging:
py.typedin the wheel via[tool.hatch.build.targets.wheel.force-include], guaranteeing the PEP 561 marker regardless of the globalexcludelist.
Python Makefile (substantial revision):
venv/—make test/lint/etc. work without activating the venv first.make dev-setup, which previously installed deps into the system interpreter instead of the freshly created venv.DEV_TOOLS; addspip-audit, removes deprecatedsafety.COVERAGE_MIN = 60.clean-build(build artefacts) fromclean—build/validate/publishno longer wipe coverage/test caches.allnow depends oninstall-dev.docstarget withmkdocs build; addsdocs-serve.update-depsalso upgrades dev tools.venvtarget uses literalpython3to avoid the venv recreating itself through its own interpreter.install-deps,venv-activate, unused colour vars).Project documentation:
SECURITY.md(disclosure process, scope, supported-version policy).CONTRIBUTING.md(dev setup for both SDKs, the four test tiers, public surface that must stay aligned between Python and Node, style, release/versioningrules).
README.md.Checklist (complete all items):
References:
No references to be shared.
Notes:
The Python package rename is the only user-visible change, and it is backwards compatible via the
FlightRadar24deprecation shim (covered bypython/tests/test_legacy_import.py). Suggested migration path for consumers: switch imports toFlightRadarAPIbefore the shim is removed in a futurerelease