Skip to content

refactor: harden SDK error taxonomy, fix Python Makefile, add project…#103

Merged
JeanExtreme002 merged 2 commits into
mainfrom
jeanextreme002/improve
May 12, 2026
Merged

refactor: harden SDK error taxonomy, fix Python Makefile, add project…#103
JeanExtreme002 merged 2 commits into
mainfrom
jeanextreme002/improve

Conversation

@JeanExtreme002
Copy link
Copy Markdown
Owner

@JeanExtreme002 JeanExtreme002 commented May 12, 2026

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 FlightRadarAPI

Aligns the Python internal package name with the PyPI distribution and with the npm package flightradarapi, so both SDKs share the same identifier.

  • Python: FlightRadar24FlightRadarAPI. A deprecation shim keeps from FlightRadar24 import ... working for one more release (re-exports the new package
    and aliases every submodule via sys.modules, emitting a DeprecationWarning).
  • Node.js: only the directory was renamed (nodejs/FlightRadar24nodejs/FlightRadarAPI). Since users import via the npm name flightradarapi, the change
    is invisible to consumers.

2. Harden error taxonomy, Python Makefile, and project docs (bump to 1.5.1)

Node SDK:

  • Replace generic Error throws with TypeError/RangeError in api.js, entities/entity.js, and flightTrackerConfig.js, matching the taxonomy already
    used by the Python SDK. Specific instanceof checks now work 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). getAirports and getFlightDetails now use it, so concurrent fan-out can't race writes onto session cookies.
  • Method exported in index.d.ts.

Cross-SDK code clarity:

  • Name the magic bearings in get_bounds_by_point (bearing_sw / bearing_ne) with short comments explaining the haversine corner derivation. Python and Node
    updated in lockstep.

Python packaging:

  • Force-include py.typed in the wheel via [tool.hatch.build.targets.wheel.force-include], guaranteeing the PEP 561 marker regardless of the global exclude
    list.

Python Makefile (substantial revision):

  • Auto-detects venv/make test/lint/etc. work without activating the venv first.
  • Fixes make dev-setup, which previously installed deps into the system interpreter instead of the freshly created venv.
  • Centralises dev tooling in DEV_TOOLS; adds pip-audit, removes deprecated safety.
  • Centralises COVERAGE_MIN = 60.
  • Splits clean-build (build artefacts) from cleanbuild/validate/publish no longer wipe coverage/test caches.
  • all now depends on install-dev.
  • Replaces broken Sphinx docs target with mkdocs build; adds docs-serve.
  • update-deps also upgrades dev tools.
  • venv target uses literal python3 to avoid the venv recreating itself through its own interpreter.
  • Removes dead code (install-deps, venv-activate, unused colour vars).

Project documentation:

  • Adds SECURITY.md (disclosure process, scope, supported-version policy).
  • Adds CONTRIBUTING.md (dev setup for both SDKs, the four test tiers, public surface that must stay aligned between Python and Node, style, release/versioning
    rules).
  • Links both from the top-level README.md.

Checklist (complete all items):

  • Added tests as necessary.
  • There is no breaking change for existing features.

References:

No references to be shared.

Notes:

The Python package rename is the only user-visible change, and it is backwards compatible via the FlightRadar24 deprecation shim (covered by
python/tests/test_legacy_import.py). Suggested migration path for consumers: switch imports to FlightRadarAPI before the shim is removed in a future
release

… 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`.
@JeanExtreme002 JeanExtreme002 self-assigned this May 12, 2026
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.
@JeanExtreme002 JeanExtreme002 merged commit 290dadc into main May 12, 2026
7 checks passed
@JeanExtreme002 JeanExtreme002 deleted the jeanextreme002/improve branch May 13, 2026 04:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant