Tutoriais

jsonW em Python: como ler com ctypes e sem dependências?

O SDK de Python do jsonW usa ctypes e não tem dependências além da linguagem. Veja como ele acha a biblioteca, o exemplo oficial e o Reconhecedor.

Por Equipe Wortic 7 min de leitura

Em Python, o SDK fica no diretório sdk/python, no arquivo jsonw.py, e chama a libjsonw pela biblioteca ctypes da própria linguagem. Com Python 3.10 ou mais novo, você abre o arquivo com jsonw.Leitor, usa a instrução with, indexa a coluna e busca pela chave. O SDK não tem dependências além da linguagem, mas precisa encontrar a biblioteca dinâmica do jsonW.

Antes do código, vale situar o formato. Segundo a página oficial do jsonW, ele é um modelo com três formas sem perda (linha, coluna e texto), tem 19 recursos e está na versão 1.4.1. A mesma biblioteca serve a várias linguagens, e o SDK de Python é uma das portas de entrada.

Como o SDK encontra a biblioteca dinâmica?

Python, PHP, Java e Kotlin carregam a libjsonw dinâmica nesta ordem. Primeiro vem a variável de ambiente JSONW_LIB, que recebe o caminho inteiro do arquivo. Depois vêm o diretório do SDK, o diretório sdk e, por fim, o diretório bin da sua plataforma, com nomes como macos-arm64, linux-x86_64 ou windows-x86_64. Sem a biblioteca em um desses lugares, o SDK não tem como carregar o formato.

Essa ordem importa em produção. Se você tem duas cópias da biblioteca, a primeira da lista é a que vence. Para testar outra versão sem mexer no diretório do projeto, aponte JSONW_LIB para o arquivo certo.

Como rodar o exemplo de leitura?

O exemplo oficial, em sdk/python/exemplo.py, recebe o arquivo, o campo e o valor em JSON. O cabeçalho do arquivo traz o comando de uso:

python3 exemplo.py dados.jsw id 2

O núcleo do exemplo tem poucas linhas. Ele abre o arquivo com with, pega o índice do campo, indexa e percorre as linhas que batem com o valor:

with jsonw.Leitor(arquivo) as a:
    k = a.indice(campo)
    a.indexar(k)
    for i in a.chave(k, json.loads(texto)):

O valor passa por json.loads, então o argumento da linha de comando é lido como JSON e não como texto puro. Dentro do bloco, a.json(i) devolve cada linha. A opção --varrer, quando presente, pula a indexação e faz a busca direta.

Como tratar erros e saídas?

Os erros do SDK saem como jsonw.ErroJsonW. O exemplo captura essa exceção e a transforma em mensagem de saída, com código de erro, sem mostrar um rastro de pilha para quem usa o terminal. Esse é um bom padrão para copiar em um script de linha de comando.

except jsonw.ErroJsonW as e:
    sys.exit(str(e))

Em um serviço web, a mesma exceção pode virar uma resposta de erro com status apropriado. A escolha fica com quem escreve o serviço, porque a biblioteca só informa o que aconteceu.

Como gravar sem publicar um arquivo pela metade?

A escrita usa as ideias do README dos SDKs: criar(caminho, esquema) abre o escritor, gravar(json) recebe cada linha, e fechar() publica tudo de uma vez. O README diz que isso já acontece sozinho no with do Python quando o bloco sai por exceção, e nesse caso nada é publicado. Para desistir de propósito, use abandonar, que também fecha sem publicar.

Assim, um script que cai no meio da gravação não deixa um arquivo jsonW incompleto no destino. Ele deixa o destino como estava, e isso vale para a regra geral do formato.

Como usar o Reconhecedor para achar termos em texto?

O SDK também traz o Reconhecedor. Ele carrega uma tabela de termos em um arquivo jsonW, com as colunas termo, forma, sinal, peso, idioma e origem, e aplica a busca a um texto. A resposta traz os termos encontrados e a soma de cada sinal. O README dá o uso como Reconhecedor(termos.jsw) seguido de reconhecer(texto).

Esse recurso serve para classificar mensagens, avaliações ou textos de atendimento, sem enviar o texto para outro serviço. A tabela de termos é um arquivo seu, e o resultado sai do próprio programa.

Por que indexar antes de buscar?

Sem índice, cada busca lê o arquivo inteiro. O README principal mede isso num arquivo de 1 milhão de linhas: a mediana de 200 buscas por id levou 142,8 ms varrendo o arquivo e 0,196 ms com o índice, que levou 193 ms para ser montado. A medição é da versão 1.3.13, em macOS arm64, então trate os números como referência e meça no seu hardware.

No Python, a chamada indexar acontece uma vez no leitor, e a partir daí cada busca por chave vira uma busca binária. Por isso o exemplo oficial separa a indexação da busca, e a opção --varrer existe para comparar os dois caminhos.

Como fica o fluxo de gravar e conferir?

O README principal mostra, em Python, um fluxo curto: abre um escritor com o caminho do arquivo e o esquema de uma linha, grava um dicionário e depois abre um leitor para conferir a custódia. A forma geral fica assim:

with jsonw.Escritor(caminho, esquema) as w:
    w.gravar(linha)
with jsonw.Leitor(caminho) as r:
    r.conferir()

O conferir verifica o crc32c e o hash de cada bloco, além da cadeia do arquivo. Segundo o README principal, qualquer byte alterado faz o conferir falhar. Esse é o motivo de conferir o arquivo antes de confiar em um dado recebido de outro sistema.

Quais limites considerar em Python?

  • Versão do Python: Python 3.10 ou mais novo, segundo o llms.txt do repositório.
  • Plataforma: a biblioteca dinâmica precisa ser da mesma plataforma do programa. O repositório traz binários para macOS arm64, Linux x86_64, Linux ARM64 e Windows x86_64.
  • Versão do jsonW: o llms.txt do repositório ainda cita a 1.3.14, enquanto a página oficial traz a 1.4.1. Confira qual biblioteca está no seu diretório.

Para entrar no ecossistema, a página para desenvolvedores da Wortic reúne as APIs abertas e as linguagens com SDK, em wortic.com.br/desenvolvedores. O código público do jsonW está em github.com/developer-wortic/jsonw, e o conector para Claude e ChatGPT está em Use a Wortic dentro do Claude e do ChatGPT. Os planos da Wortic estão em wortic.com.br/planos.

A Wortic, empresa brasileira, criou e mantém o jsonW. A licença é a Sustainable Use, do modelo fair-code, então o uso dentro dos seus produtos é livre, mas a revenda do jsonW como serviço não é permitida.

Perguntas frequentes

O que é o SDK em Python 3?

É o arquivo sdk/python/jsonw.py, que usa ctypes para chamar a libjsonw. Ele traz as classes Leitor, Escritor e Reconhecedor, e não tem dependências além da própria linguagem. O SDK precisa achar a biblioteca dinâmica para funcionar.

Como usar o SDK em Python 3 na prática?

Abra o arquivo com with jsonw.Leitor, pegue o índice do campo com indice, indexe com indexar e busque com chave. Para cada linha, use json. Rode o exemplo com python3 exemplo.py dados.jsw id 2, depois de confirmar qual biblioteca dinâmica está sendo carregada.

Quais são os limites do SDK em Python 3?

O llms.txt do repositório pede Python 3.10 ou mais novo. A biblioteca dinâmica precisa estar em um dos caminhos de busca, e da mesma plataforma do programa. O llms.txt ainda cita a versão 1.3.14, enquanto a página oficial informa a 1.4.1.

Fontes

Conheça: jsonW em Python.

Quer isso funcionando na sua empresa?

Um consultor da Wortic olha o seu caso e mostra o caminho, sem compromisso.

Falar com um consultor

Equipe editorial

Equipe editorial da Wortic especializada em automacao, IA, ERP, CRM e crescimento operacional.

  • Automacao com IA
  • Gestao empresarial
  • CRM
  • ERP
  • Marketing digital

Isso funcionando no seu negócio.

Um consultor mostra o sistema do seu ramo, com a IA dentro.