📑 Referência da API¶

Referência técnica completa para todas as classes, métodos e funções do ecossistema B-FAST em Python e TypeScript.

🧭 Visão Geral¶

⚡ Módulo Principal (b_fast)¶

Funções no Nível do Módulo¶

Para maior comodidade e ergonomia, o B-FAST expõe funções de topo de nível, eliminando a necessidade de instanciar BFast() manualmente:

import b_fast

# 1-liner de serialização (compress=True por padrão)
binary_data = b_fast.encode(meus_dados)

# 1-liner de desserialização (decompress=True por padrão)
resultado = b_fast.decode(binary_data)

encode(obj: Any, compress: bool = True) -> bytes¶

Serializa qualquer objeto Python com compressão ativa por padrão.

decode(data: Union[bytes, bytearray, memoryview], decompress: bool = True) -> Any¶

Desserializa a carga binária B-FAST de volta para estruturas nativas do Python.

decode_lazy(data: bytes, decompress: bool = True) -> BFastLazyView¶

Decodifica para uma visualização preguiçosa (lazy proxy) com zero alocação de heap.

Classe BFast¶

O motor primário de serialização e decodificação implementado em Rust com PyO3.

from b_fast import BFast

bf = BFast()

Métodos¶

encode_packed(obj: Any, compress: bool = True) -> bytes¶

(Também disponível pelo alias bf.encode(obj, compress=True))

Serializa qualquer objeto Python (primitivos, dicionários, listas, modelos Pydantic, arrays NumPy, DataFrames Polars e Pandas) no formato binário B-FAST empacotado.

• Parâmetros:
  • obj: Objeto a ser serializado. Suporta modelos Pydantic v2, arrays NumPy, DataFrames e Series Polars/Pandas, datetime, UUID, Decimal, dicionários e listas.
  • compress (bool, padrão=True): Habilita compressão LZ4. Cargas > 1MB utilizam automaticamente compressão em múltiplos chunks paralelos. Passe compress=False para saída sem compressão.
• Retorno: bytes contendo a carga binária empacotada.
• Lança: BFastError caso ocorra falha na serialização.

decode_packed(data: Union[bytes, bytearray, memoryview], decompress: bool = True) -> Any¶

(Também disponível pelo alias bf.decode(data, decompress=True))

Desserializa uma carga binária B-FAST de volta para estruturas nativas do Python.

• Parâmetros:
  • data: Buffer binário a ser decodificado.
  • decompress (bool, padrão=True): Descomprime automaticamente se o payload estiver comprimido. Passe decompress=False se o payload for binário puro sem compressão.
• Retorno: Objeto nativo do Python (dict, list, primitivo, array NumPy, datetime, etc.).
• Lança: BFastError se a carga estiver malformada.

Exceção BFastError¶

Lançada sempre que a serialização ou decodificação encontra dados inválidos. Herda de ValueError.

🚀 Integrações com Frameworks Web¶

FastAPI / Starlette (b_fast.integration)¶

BFastResponse¶

Classe de resposta para FastAPI/Starlette que codifica os dados diretamente em binário B-FAST.

from b_fast import BFastResponse

@app.get("/dados")
def get_dados():
    return BFastResponse(meus_dados, compress=True)

• Content-Type: application/x-bfast

BFastStreamingResponse¶

Resposta em streaming para FastAPI/Starlette para envio contínuo de dados em frames.

from b_fast import BFastStreamingResponse

@app.get("/stream")
async def stream():
    async def gerador():
        for i in range(10):
            yield {"contagem": i}
    return BFastStreamingResponse(gerador())

• Content-Type: application/x-bfast-stream

Django & Django Ninja (b_fast.django)¶

Django & Django Ninja (b_fast.django)¶

BFastRenderer¶

Renderizador nativo para Django Ninja baseado em BaseRenderer.

from ninja import NinjaAPI
from b_fast.django import BFastRenderer

api = NinjaAPI(renderer=BFastRenderer())

• Media Type: application/x-bfast

BFastHttpResponse (Django)¶

Subclasse de HttpResponse do Django que retorna dados em binário B-FAST.

BFastStreamingHttpResponse (Django)¶

Subclasse de StreamingHttpResponse do Django para envio progressivo de frames B-FAST.

📊 Módulo de Data Science (b_fast.data)¶

encode_dataframe¶

Serializa DataFrames/Series do Polars ou Pandas e Tabelas PyArrow em formato B-FAST.

encode_dataframe(df: Any, orient: str = "records", compress: bool = True) -> bytes

• Parâmetros:
  • df: DataFrame ou Series.
  • orient (str, padrão="records"): Layout de serialização:
    • "records": Lista de dicionários de linha ([ {col: val}, ... ]). Ideal para APIs REST e frontends.
    • "columns": Dicionário colunar ({ col: [vals] }). Ultra-rápido, sem cópias de memória adicionais.
    • "split": Dicionário com {'columns': [...], 'data': [[...], ...]}.
  • compress (bool, padrão=True): Habilita compressão LZ4.

decode_dataframe¶

Reconstrói DataFrames a partir de bytes binários do B-FAST.

decode_dataframe(data: Union[bytes, bytearray], engine: str = "auto") -> Any

• Parâmetros:
  • data: Buffer binário B-FAST.
  • engine (str, padrão="auto"): Motor a ser instanciado ("auto", "polars", "pandas" ou "arrow").

🤖 Módulo FastMCP 2.0 (b_fast.fastmcp)¶

FastMCPBFast¶

Subclasse do servidor FastMCP com suporte pré-configurado a ferramentas e recursos binários B-FAST.

FastMCPBFast(name: str, **kwargs)

bfast_tool¶

Decorador que serializa retornos de ferramentas em blobs base64 comprimidos com B-FAST, reduzindo o consumo de tokens em até 85%.

@bfast_tool(compress: bool = True)

bfast_resource¶

Decorador para definição de recursos binários B-FAST em servidores FastMCP.

@bfast_resource(uri: str, name: Optional[str] = None, compress: bool = True)

💻 Cliente TypeScript (bfast-client)¶

npm install bfast-client

Cliente Automático Transparente (bfast-client/auto)¶

Aceleração transparente de fetch que negocia e decodifica cargas binárias B-FAST automaticamente:

import 'bfast-client/auto';

// Chamadas comuns de fetch passam a negociar B-FAST e decodificar .json() de forma transparente
const resposta = await fetch('/api/dados');
const dados = await resposta.json();

installBFastAuto(target?: GlobalScope): void¶

Instala a interceptação transparente no escopo globalThis (ou em um escopo personalizado).

uninstallBFastAuto(): void¶

Restaura a implementação original de fetch.

isBFastAutoInstalled(): boolean¶

Retorna true se o cliente automático estiver ativo no momento.

onBFastResponse(callback: (detail: BFastResponseEventDetail) => void): () => void¶

Registra um ouvinte de telemetria e métricas para respostas B-FAST (URL, status, tamanho em bytes, latência de decodificação, tamanho original). Retorna uma função para cancelar a inscrição.

bfastFetch¶

import { bfastFetch } from 'bfast-client';

const usuarios = await bfastFetch<Usuario[]>('/api/usuarios', {
    schema: UsuarioSchema, // Validação opcional com Zod ou Standard Schema
    compress: true,
});

bfastQueryOptions¶

import { useQuery } from '@tanstack/react-query';
import { bfastQueryOptions } from 'bfast-client';

const { data } = useQuery(
    bfastQueryOptions<Usuario>({
        queryKey: ['usuario', 1],
        url: '/api/usuarios/1',
        schema: UsuarioSchema,
        staleTime: 5000,
    })
);

bfastInfiniteQueryOptions¶

Utilitário para paginação e carregamento contínuo no useInfiniteQuery.

BFastDecoder¶

import { BFastDecoder } from 'bfast-client';

const dados = BFastDecoder.decode<Usuario>(buffer, {
    typedArrays: false, // true para Float64Array com zero alocações
    schema: UsuarioSchema,
});

Utilitários de Streaming¶

decodeReadableStream<T>(stream: ReadableStream<Uint8Array>, options?: StreamDecodeOptions<T>): AsyncGenerator<T>¶

Consome streams do Fetch API e itera sobre frames validados em tempo real.