Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Add comprehensive FlatBuffers documentation page

Abierto
  • ¿Algo no está bien?
#1,827 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
48/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Estancado
Stack tecnológico
python
Área
documentation

Línea de trabajo

Empieza revisando la referencia de esquemas de FlatBuffers existente, la referencia de la API de Python y la ubicación propuesta docs/wamp/flatbuffers.rst. Comprueba los directorios referenciados autobahn/flatbuffers/, autobahn/wamp/flatbuffers/*.fbs y deps/flatbuffers, así como los comandos de compilación de hatch_build.py. La tarea se considera completada cuando la nueva página cubre los temas indicados de runtime, compilador, esquemas, sincronización, compilación y resolución de problemas, y está enlazada desde las secciones de documentación relevantes.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
Python
Estrellas
2.5k
Forks
767
Merge medio
23 h 55 min
PR fusionados (30 d)
25

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de crossbario/autobahn-python

Todos los issues de crossbario/autobahn-python

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.