Ajuda de campos e tipos

Consulte o contrato no próprio Python antes de preencher uma NF-e ou NFC-e. A ajuda funciona offline, sem runtime nativo, certificado A1 ou Node.js. Ela descreve os metadados incluídos no pacote; não executa operações fiscais.

O que está disponível em cada versão

Recurso	0.1.0a3 publicada no PyPI	0.1.0a4 e 0.1.0a5 publicadas no PyPI
python -m acbr --help	Disponível	Disponível
python -m acbr ajuda TARGET	JSON	JSON compatível
describe_field(TARGET)	Disponível	Disponível
python -m acbr describe TARGET	Indisponível	Texto em português
describe TARGET --json	Indisponível	JSON para automação
python -m acbr --version	Indisponível	Versão do SDK
describe_type(nome)	Indisponível	Consulta estrita de tipo

Referência publicada

Os exemplos atuais usam a alpha 0.1.0a5 do PyPI, tag v0.1.0a5, commit dc0f2bba9927. A coluna a3 conserva a diferença de compatibilidade: instalar 0.1.0a3 não oferece describe, --version nem describe_type.

Consulta JSON compatível com a a3

Depois da instalação com pip, execute no ambiente virtual:

python -m acbr --help
python -m acbr ajuda --help
python -m acbr ajuda Ide.tpNF
python -m acbr ajuda TTipoNFe

As duas últimas consultas mostram values com tnEntrada e tnSaida. O campo Ide.tpNF também informa declaredDefault: "tnSaida"; a descrição do tipo TTipoNFe não tem esse padrão, pois ele pertence ao campo. A ajuda não escolhe a opção fiscal nem converte os nomes em códigos numéricos.

ajuda imprime JSON. Para guardar a descrição sem executar o motor:

python -m acbr ajuda Ide.tpNF > campo.json

Sem TARGET, ajuda descreve a raiz TNFe. A partir da a4, consulte a versão com python -m acbr --version. A API padrão abaixo também funciona na a3:

python -c "from importlib.metadata import version; print(version('acbr-python'))"

Usar a ajuda em código Python

Este exemplo completo funciona na a5 publicada, preservando a compatibilidade com a a3:

from typing import get_args

from acbr import describe_field
from acbr.models import TTipoNFe

campo = describe_field("Ide.tpNF")
assert campo["pascalType"] == "TTipoNFe"
assert campo["values"] == ["tnEntrada", "tnSaida"]
assert campo["declaredDefault"] == "tnSaida"

tipo = describe_field("TTipoNFe")
assert tipo["values"] == campo["values"]
assert "declaredDefault" not in tipo
assert get_args(TTipoNFe) == ("tnEntrada", "tnSaida")

print(campo["path"], campo["values"])

TTipoNFe é um alias Literal para o editor, não uma classe Enum. Use typing.get_args para consultar os valores do alias. Na entrada de um Documento, use a string exata do contrato. Um padrão declarado na ajuda não é inserido automaticamente em campos omitidos.

Campos, caminhos e coleções

python -m acbr ajuda TNFe.Ide.tpNF
python -m acbr ajuda TProd
python -m acbr ajuda Det
python -m acbr ajuda 'Det[].Prod.vProd'
python -m acbr ajuda 'Det[0].Prod.vProd'

Os nomes distinguem maiúsculas e minúsculas. O prefixo TNFe. é opcional em caminhos de campos. Um nome curto pode ser ambíguo; prefira o caminho completo.

Det descreve a lista e seu tipo de item. Para chegar a Prod.vProd, selecione um item com [] ou um índice. Det[0].Prod.vProd é normalizado para TNFe.Det[].Prod.vProd; a ajuda não acessa o primeiro item de um documento real.

O JSON informa path, pascalType, kind, inputType, readonly, revisão, hashes e versão do SDK. Conforme o alvo, inclui members, itemType, values, constraints e declaredDefault. Por exemplo, um decimal tem entrada JSON em string. Ausência de limite ou padrão na resposta não autoriza inventar esse metadado.

Veja regras de entrada e validação estrutural e o catálogo dos 204 tipos. A ajuda não determina obrigatoriedade, regras tributárias, validade do XML ou autorização fiscal.

Descrição legível no terminal

Introduzido na a4 e disponível na a5 publicada:

python -m acbr --version
python -m acbr describe --help
python -m acbr describe Ide.tpNF
python -m acbr describe TTipoNFe
python -m acbr describe TTipoNFe --json

A consulta describe Ide.tpNF produz:

TNFe.Ide.tpNF
Tipo: TTipoNFe (enum; entrada string)
Somente leitura: não
Valores: tnEntrada, tnSaida
Padrão declarado: tnSaida

O tipo TTipoNFe mostra os mesmos valores, sem a linha do padrão. Objetos listam campos; listas mostram o tipo dos itens; limites e escala aparecem quando declarados no contrato. describe sem TARGET consulta TNFe.

describe TARGET --json retorna os metadados de describe_field(TARGET); --json também pode vir antes do TARGET. ajuda TARGET mantém a interface JSON existente e não aceita --json. Na a5 publicada, --version mostra acbr-python 0.1.0a5.

Consulta estrita de um tipo

describe_type existe a partir da a4 publicada; não existe na a3. Exemplo completo:

from acbr import AcbrError, describe_type

tipo = describe_type("TTipoNFe")
assert tipo["values"] == ["tnEntrada", "tnSaida"]
assert "declaredDefault" not in tipo

try:
    describe_type("Ide.tpNF")
except AcbrError as erro:
    assert erro.diagnostico.codigo == "TIPO_INVALIDO"
else:
    raise AssertionError("Um caminho de campo não é um nome de tipo")

describe_type aceita nomes exatos de tipos de objeto, lista ou enum do contrato, como TProd, TDetCollection e TTipoNFe. Rejeita caminhos de campos, espaços, capitalização diferente e aliases Python terminados em Output. Para um campo, continue usando describe_field.

As consultas devolvem dicionários independentes; alterá-los não modifica o contrato incluído no pacote.

Erros e automação

Interface	Sucesso	Erro de consulta
ajuda TARGET — a3, a4 e a5	JSON em stdout; saída 0	Diagnóstico JSON em stdout; saída 1
describe TARGET — a4 e a5	Texto em stdout; saída 0	Mensagem e ação em stderr; saída 1, stdout vazio
describe TARGET --json — a4 e a5	JSON em stdout; saída 0	Diagnóstico JSON em stdout; saída 1

Uma opção desconhecida ou argumento excedente é erro de sintaxe do argparse: stderr e saída 2. Um campo inexistente é erro de consulta, com saída 1. Não use o texto do erro como protocolo; em automações, prefira o código do diagnóstico JSON.

Entre os diagnósticos estão CAMPO_INEXISTENTE, CAMPO_AMBIGUO e COLECAO_REQUER_INDICE. Na API Python, trate AcbrError e leia erro.diagnostico.codigo. Veja tratamento de erros.

As fontes da versão atual são o CLI da a5, o guia de ajuda do SDK e a implementação do contrato. O CLI histórico da a3 ancora a coluna de compatibilidade. A validação desta documentação identifica os testes contra o wheel público.