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.

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 2O 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
- SDK de Python, sdk/python/jsonw.py
- Exemplo oficial em Python, sdk/python/exemplo.py
- README dos SDKs do jsonW
- llms.txt do repositório jsonW
- Página oficial do jsonW
- Licença Sustainable Use do jsonW
- Página para desenvolvedores da Wortic
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 consultorEquipe editorial
Equipe editorial da Wortic especializada em automacao, IA, ERP, CRM e crescimento operacional.
- Automacao com IA
- Gestao empresarial
- CRM
- ERP
- Marketing digital
