Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Add comprehensive FlatBuffers documentation page

Aperta
  • Qualcosa non va?
#1,827 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
48/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
python
Ambito
documentation

Direzione di ricerca

Inizia esaminando il riferimento allo schema FlatBuffers esistente, il riferimento all’API Python e il percorso proposto docs/wamp/flatbuffers.rst. Controlla le directory referenziate autobahn/flatbuffers/, autobahn/wamp/flatbuffers/*.fbs e deps/flatbuffers, nonché i comandi di build in hatch_build.py. L’attività è completata quando la nuova pagina tratta gli argomenti elencati relativi a runtime, compilatore, schemi, sincronizzazione, build e risoluzione dei problemi, ed è collegata dalle sezioni pertinenti della documentazione.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

docs enhancement

Summary

Create a dedicated documentation page explaining autobahn-python's FlatBuffers features, bundled flatc compiler, and
integration with the WAMP ecosystem.

Background

autobahn-python now includes significant FlatBuffers functionality that is not well-documented:

  1. Bundled flatc compiler in binary wheels (since v25.12.x)
  2. Vendored FlatBuffers runtime for serialization
  3. WAMP FlatBuffers schemas for efficient binary serialization
  4. Cross-project version synchronization with zlmdb

Currently, FlatBuffers information is scattered across:

Proposed Documentation Content

1. Overview Section
  • What is FlatBuffers and why autobahn-python uses it
  • Benefits: zero-copy access, efficient serialization, cross-language compatibility
  • Use cases: WAMP binary serialization, high-performance messaging
2. Bundled flatc Compiler
  • Feature: Wheels include a pre-compiled flatc executable; source installs compile it from deps/flatbuffers
  • Usage: After pip install autobahn, run flatc --version
  • Platform support: Linux (x86_64, aarch64), macOS (arm64), Windows (x86_64)
  • ISA requirements: Need GLIBC 2.28+ (e.g., Ubuntu 20.04+, Debian 11+, RHEL 8+)
    • Linux x86_64: manylinux_2_28 (GLIBC 2.28+)
    • Linux aarch64: manylinux_2_28 (GLIBC 2.28+)
  • Benefits: No need to install system-wide flatc, version matches vendored runtime
  • Source builds: Require cmake to compile flatc from deps/flatbuffers during install
3. Vendored FlatBuffers Runtime
  • Version tracking: autobahn.flatbuffers.version() returns exact version tuple
  • Location: autobahn/flatbuffers/ (vendored from google/flatbuffers)
  • Includes reflection schema (reflection.fbs, reflection.bfbs)
4. WAMP FlatBuffers Schemas
  • Schema files location: autobahn/wamp/flatbuffers/*.fbs
  • Available schemas: wamp.fbs, session.fbs, auth.fbs, pubsub.fbs, rpc.fbs, roles.fbs, types.fbs
  • Binary schemas (.bfbs) generated at wheel build time
  • Link to existing schema reference
    documentation
5. Cross-Project Version Synchronization
  • autobahn-python and zlmdb share the same FlatBuffers version
  • Verification function: autobahn.check_zlmdb_flatbuffers_version_in_sync()
  • Why this matters: cfxdb and Crossbar.io depend on both libraries
  • Example usage: 
    import autobahn
version = autobahn.check_zlmdb_flatbuffers_version_in_sync()
print(f"FlatBuffers version: {version}")  # e.g., (25, 9, 23, None, None)
  1. Development & Build Information
  • FlatBuffers source: deps/flatbuffers git submodule (tracks google/flatbuffers)
  • Build process: hatch_build.py compiles flatc during both wheel and source builds
  • Updating vendored FlatBuffers: just bump-flatbuffers
  • Testing bundled flatc: just test-bundled-flatc
  1. Troubleshooting
  • "flatc not found after source install": Ensure cmake is installed before pip install
  • Version mismatch with zlmdb: Update both packages to latest versions
  • GLIBC errors on old Linux: Need GLIBC 2.28+ (e.g., Ubuntu 20.04+, Debian 11+, RHEL 8+)

Documentation Location

Suggested location: docs/wamp/flatbuffers.rst (or docs/flatbuffers.rst if scope extends beyond WAMP)

Should be linked from:

  • Main documentation index
  • WAMP serialization documentation
  • Installation guide (mention bundled flatc)

Related

  • #1817 - FlatBuffers vendoring verification
  • #1821 - CI/CD and FlatBuffers sync with zlmdb
  • #1822 - Synchronize CI/CD, FlatBuffers vendoring between autobahn-python and zlmdb
  • crossbario/zlmdb#100 - Sync autobahn-python and zlmdb

Checklist

  • I have searched existing issues to avoid duplicates
  • I have described the problem clearly
  • I have provided use cases
  • I have considered alternatives
  • I have assessed impact and breaking changes
Lingua principale
Python
Stelle
2.5k
Fork
769
Merge medio
1g 12h
PR unite (30g)
15

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di crossbario/autobahn-python

Tutte le issue di crossbario/autobahn-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.