Skip to content

Commit af691a0

Browse files
felps-devclaude
felps-dev
and
claude
committed
docs: Add source maps for large files and CLAUDE.md for LLM navigation
Source maps provide section-by-section breakdowns with exact line ranges for all files over 200 lines, enabling LLMs to navigate directly to specific code sections instead of reading entire files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent c69ef73 commit af691a0

10 files changed

Lines changed: 684 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# CLAUDE.md - PyNFe
2+
3+
Brazilian electronic fiscal document library (NF-e, NFC-e, NFS-e, MDF-e, CT-e) for SEFAZ webservice communication.
4+
5+
## Source Map Navigation (MANDATORY)
6+
7+
**Before reading any large file (>200 lines), you MUST first read its `{filename}_map.md` file** in the same directory. The source map contains:
8+
- Section-by-section breakdown with exact line ranges
9+
- Class/method index with purpose descriptions
10+
- Field group documentation
11+
12+
This allows you to navigate directly to the specific line-window you need instead of reading the entire file.
13+
14+
### Available Source Maps
15+
16+
| Source Map | File | Lines | Description |
17+
|------------|------|-------|-------------|
18+
| `pynfe/processamento/serializacao_map.md` | `serializacao.py` | 2630 | XML serialization (NF-e, MDF-e, QR codes) |
19+
| `pynfe/processamento/comunicacao_map.md` | `comunicacao.py` | 1348 | SEFAZ webservice communication |
20+
| `pynfe/processamento/autorizador_nfse_map.md` | `autorizador_nfse.py` | 538 | NFS-e authorization (Betha/Ginfes) |
21+
| `pynfe/entidades/notafiscal_map.md` | `notafiscal.py` | 1253 | Invoice entities and tax fields |
22+
| `pynfe/entidades/manifesto_map.md` | `manifesto.py` | 447 | MDF-e manifest entities |
23+
| `pynfe/entidades/evento_map.md` | `evento.py` | 237 | Event entities (cancel, correction, etc.) |
24+
| `pynfe/utils/flags_map.md` | `flags.py` | 645 | Constants, namespaces, tax codes |
25+
| `pynfe/utils/webservices_map.md` | `webservices.py` | 572 | SEFAZ endpoint URLs by state |
26+
| `pynfe/utils/utils_map.md` | `__init__.py` | 253 | Utility functions (municipality lookup, signing) |
27+
28+
### How to Use Source Maps
29+
30+
1. **Read the `_map.md` file first** to understand the file structure
31+
2. **Identify the line range** you need from the map tables
32+
3. **Read only that section** using `offset` and `limit` parameters
33+
4. Example: To understand ICMS CST 60 serialization, read `serializacao_map.md`, find it's at lines 747-770, then read `serializacao.py` with `offset=747, limit=25`
34+
35+
## Project Structure
36+
37+
```
38+
pynfe/
39+
├── entidades/ # Domain entities (data models)
40+
│ ├── base.py # Base entity class with kwargs init
41+
│ ├── certificado.py # A1 certificate handling
42+
│ ├── cliente.py # Customer entity
43+
│ ├── emitente.py # Issuer entity
44+
│ ├── evento.py # Event entities (cancel, correction, MDF-e events)
45+
│ ├── manifesto.py # MDF-e manifest entity
46+
│ ├── notafiscal.py # NF-e/NFC-e invoice entity + products + taxes
47+
│ ├── produto.py # Product entity (standalone)
48+
│ ├── servico.py # Service entity (NFS-e)
49+
│ └── transportadora.py # Carrier entity
50+
├── processamento/ # Core processing logic
51+
│ ├── assinatura.py # XML digital signing with A1 certificates
52+
│ ├── autorizador_nfse.py # NFS-e serialization (Betha/Ginfes PyXB bindings)
53+
│ ├── comunicacao.py # SEFAZ SOAP webservice communication
54+
│ ├── serializacao.py # XML serialization (entities → SEFAZ XML)
55+
│ └── validacao.py # XML schema validation
56+
├── utils/ # Utilities
57+
│ ├── __init__.py # Municipality lookup, XML signing helpers
58+
│ ├── flags.py # Constants, namespaces, tax code enumerations
59+
│ ├── webservices.py # SEFAZ endpoint URLs by state/environment
60+
│ ├── bar_code_128.py # Code 128 barcode generation for DANFE
61+
│ ├── xml_writer.py # XML element writing helpers
62+
│ └── nfse/ # NFS-e provider-specific PyXB bindings (GENERATED - do not edit)
63+
│ ├── betha/ # Betha provider bindings (13,941+ lines)
64+
│ └── ginfes/ # Ginfes provider bindings (8,028+ lines)
65+
├── data/ # Reference data files
66+
│ ├── IBPT/ # Tax tables by state (CSV)
67+
│ ├── ISSQN/ # Service tax classification
68+
│ ├── MunIBGE/ # Municipality IBGE codes by UF
69+
│ └── XSDs/ # XML Schema definitions (NF-e, NFC-e, NFS-e, MDF-e, CT-e)
70+
tests/ # Test suite (37 test files)
71+
```
72+
73+
## Key Concepts
74+
75+
- **NF-e** (modelo 55): Standard electronic invoice
76+
- **NFC-e** (modelo 65): Consumer electronic invoice (retail)
77+
- **NFS-e**: Municipal service invoice (Betha/Ginfes providers)
78+
- **MDF-e** (modelo 58): Transport manifest
79+
- **CT-e**: Transport knowledge document (partial support)
80+
- **SEFAZ**: State tax authority webservices
81+
- **Homologacao**: Test environment (`_ambiente=2`)
82+
- **SVRS/SVAN**: Virtual SEFAZ environments for states without own webservices
83+
84+
## Commands
85+
86+
```bash
87+
# Run tests
88+
pytest tests/
89+
90+
# Run specific test
91+
pytest tests/test_nfe_serializacao_geral.py
92+
93+
# Lint
94+
ruff check pynfe/
95+
96+
# Format
97+
ruff format pynfe/
98+
```
99+
100+
## Dependencies
101+
102+
- `lxml` — XML processing
103+
- `signxml` — XML digital signatures
104+
- `cryptography` / `pyopenssl` — Certificate handling
105+
- `requests` — HTTP communication with SEFAZ
106+
- `suds-community` — SOAP client (NFS-e only)
107+
- `PyXB-X` — XML Schema bindings (NFS-e only)
108+
109+
## Important Notes
110+
111+
- Files under `pynfe/utils/nfse/` are **auto-generated** PyXB bindings — do not edit manually
112+
- The `pynfe/data/` directory contains reference data files that should not be modified casually
113+
- Tax code serialization follows strict SEFAZ XML schema ordering — field order matters
114+
- Each Brazilian state has its own SEFAZ endpoint configuration in `webservices.py`

‎pynfe/entidades/evento_map.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Source Map: `evento.py` (237 lines)
2+
3+
Event entity models for NF-e and MDF-e lifecycle operations.
4+
5+
## Classes Overview
6+
7+
| Class | Lines | Purpose |
8+
|-------|-------|---------|
9+
| `Evento` | 11-46 | Base event class |
10+
| `EventoCancelarNota` | 49-60 | NF-e cancellation (tp_evento=110111) |
11+
| `EventoCartaCorrecao` | 63-90 | NF-e correction letter (tp_evento=110110) |
12+
| `EventoManifestacaoDest` | 93-130 | Recipient manifestation (confirm/unknown/not performed/unaware) |
13+
| `EventoOperacaoNaoRealizada` | ~132-145 | Operation not performed |
14+
| `EventoCancelarMDFe` | ~147-160 | MDF-e cancellation |
15+
| `EventoEncerrarMDFe` | ~162-180 | MDF-e closure |
16+
| `EventoIncluirCondutorMDFe` | ~182-195 | Add driver to MDF-e |
17+
| `EventoIncluirDFeMDFe` | ~197-215 | Add DF-e to MDF-e |
18+
| `EventoPagamentoMDFe` | ~217-237 | MDF-e operation payment |
19+
20+
## `Evento` (base) — Lines 11-46
21+
22+
Fields: `id`, `orgao`, `cnpj`, `chave`, `data_emissao`, `uf`, `tp_evento`, `n_seq_evento`, `descricao`.
23+
24+
Property `identificador` builds: `"ID" + tp_evento + chave + n_seq_evento(2 digits)`.
25+
26+
## Key Event Types
27+
28+
| Class | tp_evento | descricao |
29+
|-------|-----------|-----------|
30+
| `EventoCancelarNota` | 110111 | "Cancelamento" |
31+
| `EventoCartaCorrecao` | 110110 | "Carta de Correcao" |
32+
| `EventoManifestacaoDest` | 210200-210240 | Various manifestation types |
33+
| `EventoOperacaoNaoRealizada` | 110112 | "Operacao nao Realizada" |
34+
| `EventoCancelarMDFe` | 110111 | "Cancelamento" (MDF-e) |
35+
| `EventoEncerrarMDFe` | 110112 | "Encerramento" |
36+
| `EventoIncluirCondutorMDFe` | 110114 | "Inclusão Condutor" |
37+
| `EventoIncluirDFeMDFe` | 110115 | "Inclusao DF-e" |
38+
| `EventoPagamentoMDFe` | 110116 | "Pagamento Operacao MDF-e" |

‎pynfe/entidades/manifesto_map.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Source Map: `manifesto.py` (447 lines)
2+
3+
Entity models for MDF-e (Manifesto de Documentos Fiscais Eletrônicos).
4+
5+
## Classes Overview
6+
7+
| Class | Lines | Purpose |
8+
|-------|-------|---------|
9+
| `Manifesto` | 12-200 | Main MDF-e entity |
10+
| `ManifestoEmitente` | ~203-230 | MDF-e issuer |
11+
| `ManifestoMunicipioCarrega` | ~232-240 | Loading municipality |
12+
| `ManifestoPercurso` | ~242-248 | Route waypoint (UF) |
13+
| `ManifestoModalRodoviario` | ~250-290 | Road transport modal |
14+
| `ManifestoCIOT` | ~292-300 | CIOT (toll system) |
15+
| `ManifestoPedagio` | ~302-315 | Toll information |
16+
| `ManifestoContratante` | ~317-330 | Contractor info |
17+
| `ManifestoVeiculoTracao` | ~332-360 | Traction vehicle |
18+
| `ManifestoVeiculoReboque` | ~362-385 | Trailer vehicle |
19+
| `ManifestoProprietario` | ~387-400 | Vehicle owner |
20+
| `ManifestoCondutor` | ~402-410 | Driver |
21+
| `ManifestoDocumentos` | ~412-425 | Linked documents (NF-e/CT-e) |
22+
| `ManifestoSeguradora` | ~427-440 | Insurance |
23+
| `ManifestoTotais` | ~442-447 | Totals (weight, cargo value) |
24+
25+
## `Manifesto` — Lines 12-200
26+
27+
### Field Groups
28+
| Section | Lines | Fields |
29+
|---------|-------|--------|
30+
| Identity | 12-68 | uf, tipo_emitente, tipo_transportador, modelo (58), serie, numero_mdfe, codigo_numerico_aleatorio, modal, data_emissao, forma_emissao, processo_emissao, UFIni, UFFim |
31+
| Read-only | 65-72 | digest_value, protocolo, data |
32+
| Relationships | 74-110 | municipio_carrega, percurso, dhIniViagem, emitente, modal_rodoviario, documentos, seguradora, produto, totais, lacres, responsavel_tecnico |
33+
| Additional info | ~112-120 | informacoes_adicionais_interesse_fisco, informacoes_complementares_interesse_contribuinte |
34+
35+
### Methods
36+
| Method | Lines | Purpose |
37+
|--------|-------|---------|
38+
| `__init__()` | ~122-140 | Initialize all list fields |
39+
| `adicionar_*()` | ~142-185 | Add municipio_carrega, percurso, emitente, modal_rodoviario, documento, seguradora, produto, totais, lacre, responsavel_tecnico |
40+
| `_codigo_numerico_aleatorio()` | ~187-190 | Generate random 8-digit code |
41+
| `_dv_codigo_numerico()` | ~192-200 | Calculate check digit (mod 11) |
42+
| `identificador_unico` (property) | ~200+ | Build 44-char MDF-e access key |

‎pynfe/entidades/notafiscal_map.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Source Map: `notafiscal.py` (1253 lines)
2+
3+
Entity models for NF-e/NFC-e invoices and related objects (products, taxes, payments, transport, etc.).
4+
5+
## Classes Overview
6+
7+
| Class | Lines | Purpose |
8+
|-------|-------|---------|
9+
| `NotaFiscal` | 14-572 | Main invoice entity |
10+
| `NotaFiscalReferenciada` | 575-603 | Referenced invoice |
11+
| `NotaFiscalProduto` | 606-1019 | Product/service item with all tax fields |
12+
| `NotaFiscalDeclaracaoImportacao` | 1022-1067 | Import declaration |
13+
| `NotaFiscalDeclaracaoImportacaoAdicao` | 1070-1082 | Import declaration addition |
14+
| `NotaFiscalTransporteVolume` | 1084-1113 | Transport volume |
15+
| `NotaFiscalTransporteVolumeLacre` | 1116-1118 | Volume seal |
16+
| `NotaFiscalCobrancaDuplicata` | 1121-1129 | Billing duplicate |
17+
| `NotaFiscalObservacaoContribuinte` | 1132-1137 | Taxpayer note |
18+
| `NotaFiscalProcessoReferenciado` | 1140-1150 | Referenced process |
19+
| `NotaFiscalEntregaRetirada` | 1153-1190 | Delivery/withdrawal address |
20+
| `NotaFiscalServico` | 1192-1220 | NFS-e service invoice |
21+
| `NotaFiscalResponsavelTecnico` | 1223-1229 | Technical responsible (NT2018/003) |
22+
| `AutorizadosBaixarXML` | 1232-1233 | Authorized XML downloaders |
23+
| `NotaFiscalPagamentos` | 1236-1253 | Payment details |
24+
25+
---
26+
27+
## `NotaFiscal` — Lines 14-572
28+
29+
### Field Groups
30+
| Section | Lines | Fields |
31+
|---------|-------|--------|
32+
| Deprecated fields | 16-23 | `tipo_pagamento` deprecated |
33+
| Invoice identity | 25-127 | status, codigo_numerico, modelo, serie, numero_nf, data_emissao, natureza_operacao, tipo_documento, processo_emissao, tipo_impressao_danfe, forma_emissao, finalidade_emissao, cliente_final, indicador_presencial, indicador_intermediador, indicador_destino, uf, municipio |
34+
| Read-only fields | 128-144 | digest_value, valor_total_nota, valor_icms_nota, valor_icms_st_nota, protocolo, data |
35+
| Relationships | 146-173 | notas_fiscais_referenciadas, emitente, destinatario_remetente, entrega, retirada, autorizados_baixar_xml, produtos_e_servicos |
36+
| ICMS totals | 175-303 | totais_icms_base_calculo, totais_icms_total, totais_icms_desonerado, totais_icms_st_*, totais_icms_total_*, totais_fcp_*, totais_icms_inter_*, totais_icms_*_mono_* |
37+
| Transport | 305-361 | transporte_modalidade_frete, transporte_transportadora, transporte_retencao_icms_*, transporte_veiculo_*, transporte_reboque_*, transporte_volumes |
38+
| Billing | 363-378 | fatura_numero, fatura_valor_original, fatura_valor_desconto, fatura_valor_liquido, duplicatas |
39+
| Additional info | 380-397 | informacoes_adicionais_*, observacoes_contribuinte, processos_referenciados, pagamentos, valor_troco |
40+
41+
### Methods
42+
| Method | Lines | Purpose |
43+
|--------|-------|---------|
44+
| `__init__()` | 399-410 | Initialize all list fields |
45+
| `adicionar_pagamento()` | 415-419 | Add payment |
46+
| `adicionar_autorizados_baixar_xml()` | 421-424 | Add authorized XML downloader |
47+
| `adicionar_nota_fiscal_referenciada()` | 426-430 | Add referenced invoice |
48+
| `adicionar_produto_servico()` | 432-484 | **Add product** — also accumulates all ICMS/tax totals |
49+
| `adicionar_transporte_volume()` | 486-490 | Add transport volume |
50+
| `adicionar_duplicata()` | 492-496 | Add billing duplicate |
51+
| `adicionar_observacao_contribuinte()` | 498-502 | Add taxpayer note |
52+
| `adicionar_processo_referenciado()` | 504-508 | Add referenced process |
53+
| `adicionar_responsavel_tecnico()` | 510-514 | Add technical responsible |
54+
| `_codigo_numerico_aleatorio()` | 516-519 | Generate random 8-digit code |
55+
| `_dv_codigo_numerico()` | 521-543 | Calculate check digit (mod 11) |
56+
| `identificador_unico` (property) | 545-572 | Build 44-char NF-e access key |
57+
58+
---
59+
60+
## `NotaFiscalProduto` — Lines 606-1019
61+
62+
### Field Groups
63+
| Section | Lines | Fields |
64+
|---------|-------|--------|
65+
| Product data | 612-686 | codigo, descricao, ean, ncm, cfop, unidade_comercial, quantidade_comercial, valor_unitario_comercial, unidade_tributavel, cbenef, quantidade_tributavel, valor_unitario_tributavel, ean_tributavel, total_frete, total_seguro, desconto, outras_despesas_acessorias, valor_total_bruto, numero_pedido, numero_item |
66+
| Fuel data | 688-733 | cProdANP, descANP, pGLP, pGNn, pGNi, vPart, UFCons, comb_codif, comb_q_temp, comb_n_bico, comb_n_bomba, comb_n_tanque, comb_v_enc_ini, comb_v_enc_fin, comb_p_bio |
67+
| ICMS fields | 735-826 | icms_modalidade, icms_origem, icms_modalidade_determinacao_bc, icms_percentual_reducao_bc, icms_valor_base_calculo, icms_aliquota, icms_valor, icms_desonerado, icms_motivo_desoneracao, icms_st_*, fcp_*, icms_inter_*, icms_st_ret_*, icms_*_mono_* |
68+
| IPI fields | 828-877 | ipi_situacao_tributaria, ipi_classe_enquadramento, ipi_codigo_enquadramento, ipi_valor_base_calculo, ipi_aliquota, ipi_valor_ipi, pdevol, ipi_valor_ipi_dev |
69+
| PIS fields | 879-923 | pis_modalidade (via pis_situacao_tributaria), pis_valor_base_calculo, pis_aliquota_percentual, pis_aliquota_reais, pis_valor, pis_st_* |
70+
| COFINS fields | 925-969 | cofins_modalidade, cofins_valor_base_calculo, cofins_aliquota_percentual, cofins_aliquota_reais, cofins_valor, cofins_st_* |
71+
| ISSQN fields | 971-990 | issqn_valor_base_calculo, issqn_aliquota, issqn_lista_servico, issqn_uf, issqn_municipio, issqn_valor |
72+
| Import tax fields | 992-1003 | imposto_importacao_valor_base_calculo, imposto_importacao_valor_despesas_aduaneiras, imposto_importacao_valor_iof, imposto_importacao_valor |
73+
| Additional info | 1005-1019 | informacoes_adicionais, declaracoes_importacao |
74+
75+
---
76+
77+
## Supporting Entities (Lines 1022-1253)
78+
79+
Small entity classes for nested data — see class table above for line ranges. All extend `Entidade` base class and use kwargs initialization.

‎pynfe/processamento/autorizador_nfse_map.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Source Map: `autorizador_nfse.py` (538 lines)
2+
3+
NFS-e authorization and serialization for Betha and Ginfes providers.
4+
5+
## Classes Overview
6+
7+
| Class | Lines | Purpose |
8+
|-------|-------|---------|
9+
| `InterfaceAutorizador` | 5-11 | Abstract interface (consultar_rps, cancelar) |
10+
| `SerializacaoBetha` | 14-200 | Betha NFS-e XML generation using PyXB bindings |
11+
| `SerializacaoGinfes` | ~202-538 | Ginfes NFS-e XML generation using PyXB bindings |
12+
13+
## `SerializacaoBetha` — Lines 14-200
14+
15+
### Methods
16+
| Method | Lines | Purpose |
17+
|--------|-------|---------|
18+
| `__init__()` | 15-18 | Import Betha NFS-e v2.02 schema |
19+
| `gerar()` | 20-94 | Generate NFS-e XML (service, provider, customer, RPS) |
20+
| `consultar_rps()` | 96-130 | Query NFS-e by RPS |
21+
| `consultar_faixa()` | ~132-160 | Query NFS-e by range |
22+
| `cancelar()` | ~162-200 | Cancel NFS-e |
23+
24+
## `SerializacaoGinfes` — Lines ~202-538
25+
26+
### Methods
27+
| Method | Lines | Purpose |
28+
|--------|-------|---------|
29+
| `__init__()` | ~202-210 | Import Ginfes schema modules |
30+
| `cabecalho()` | ~212-220 | Generate XML header |
31+
| `serializar_lote_assincrono()` | ~222-310 | Serialize async batch (RPS list) |
32+
| `consultar_nfse()` | ~312-360 | Query NFS-e by provider/period |
33+
| `consultar_lote()` | ~362-390 | Query batch by number |
34+
| `consultar_rps()` | ~392-420 | Query NFS-e by RPS |
35+
| `consultar_situacao_lote()` | ~422-450 | Query batch status |
36+
| `cancelar()` / `cancelar_v2()` | ~452-538 | Cancel NFS-e (v2 and v3) |

0 commit comments

Comments
 (0)