bncc 0.1.0__py3-none-any.whl

bncc/__init__.py

@@ -0,0 +1,18 @@
+"""bncc — a BNCC (Base Nacional Comum Curricular) como dados estruturados e
+verificados, com API de consulta em português.
+
+Dados embutidos, zero dependências, zero rede. Cada registro é rastreável à
+fonte oficial. Projeto bncc.dev · dados CC BY 4.0 · código MIT.
+"""
+from ._codigos import decodificar
+from ._consultas import (
+    buscar, estatisticas, estrutura, habilidades_ef, habilidades_em,
+    objetivos_ei, por_codigo, progressao_ei, versao,
+)
+from ._pandas import para_dataframe
+
+__all__ = [
+    'buscar', 'decodificar', 'estatisticas', 'estrutura', 'habilidades_ef',
+    'habilidades_em', 'objetivos_ei', 'para_dataframe', 'por_codigo',
+    'progressao_ei', 'versao',
+]

bncc/_codigos.py

@@ -0,0 +1,63 @@
+"""Decodificador de códigos da BNCC (as três gramáticas oficiais).
+
+Cópia adaptada de bncc-dados/pipeline/codigos.py (mesma origem, mesmos erros),
+onde é exercitado pelos 1.580 códigos do dataset a cada CI.
+"""
+import re
+
+CAMPOS_EI = {'EO': 'O eu, o outro e o nós', 'CG': 'Corpo, gestos e movimentos',
+             'TS': 'Traços, sons, cores e formas', 'EF': 'Escuta, fala, pensamento e imaginação',
+             'ET': 'Espaços, tempos, quantidades, relações e transformações'}
+GRUPOS_EI = {'01': 'Bebês (0–1a6m)', '02': 'Crianças bem pequenas (1a7m–3a11m)',
+             '03': 'Crianças pequenas (4a–5a11m)'}
+COMPONENTES_EF = {'AR': 'Arte', 'CI': 'Ciências', 'EF': 'Educação Física', 'ER': 'Ensino Religioso',
+                  'GE': 'Geografia', 'HI': 'História', 'LI': 'Língua Inglesa',
+                  'LP': 'Língua Portuguesa', 'MA': 'Matemática'}
+BLOCOS_EF = {'15': [1, 2, 3, 4, 5], '69': [6, 7, 8, 9], '12': [1, 2], '35': [3, 4, 5],
+             '67': [6, 7], '89': [8, 9]}
+BLOCOS_VALIDOS_POR_COMPONENTE = {'AR': {'15', '69'}, 'LP': {'15', '69', '12', '35', '67', '89'},
+                                 'EF': {'12', '35', '67', '89'}}
+AREAS_EM = {'LGG': 'Linguagens e suas Tecnologias', 'MAT': 'Matemática e suas Tecnologias',
+            'CNT': 'Ciências da Natureza e suas Tecnologias', 'CHS': 'Ciências Humanas e Sociais Aplicadas'}
+
+
+def decodificar(codigo):
+    """Decodifica um código BNCC → dict estruturado, ou lança ValueError."""
+    codigo = codigo.strip().upper()
+
+    m = re.fullmatch(r'EI(0[123])(EO|CG|TS|EF|ET)(\d{2})', codigo)
+    if m:
+        grupo, campo, seq = m.groups()
+        return {'codigo': codigo, 'etapa': 'EI', 'grupo_etario': grupo,
+                'grupo_etario_nome': GRUPOS_EI[grupo], 'campo_experiencias': campo,
+                'campo_experiencias_nome': CAMPOS_EI[campo], 'sequencia': int(seq)}
+
+    m = re.fullmatch(r'EF(\d{2})([A-Z]{2})(\d{2})', codigo)
+    if m:
+        anos_str, comp, seq = m.groups()
+        if comp not in COMPONENTES_EF:
+            raise ValueError(f'{codigo}: componente {comp!r} desconhecido')
+        if anos_str in BLOCOS_EF:
+            if anos_str not in BLOCOS_VALIDOS_POR_COMPONENTE.get(comp, set()):
+                raise ValueError(f'{codigo}: bloco {anos_str!r} inválido para {COMPONENTES_EF[comp]}')
+            anos = BLOCOS_EF[anos_str]
+        elif anos_str.startswith('0') and 1 <= int(anos_str) <= 9:
+            anos = [int(anos_str)]
+        else:
+            raise ValueError(f'{codigo}: ano/bloco {anos_str!r} inválido')
+        return {'codigo': codigo, 'etapa': 'EF', 'anos': anos, 'bloco': anos_str in BLOCOS_EF,
+                'componente': comp, 'componente_nome': COMPONENTES_EF[comp], 'sequencia': int(seq)}
+
+    m = re.fullmatch(r'EM13([A-Z]{3})(\d)(\d{2})', codigo)
+    if m and m.group(1) in AREAS_EM:
+        area, ce, seq = m.groups()
+        return {'codigo': codigo, 'etapa': 'EM', 'seriacao': None, 'area': area,
+                'area_nome': AREAS_EM[area], 'competencia_especifica': int(ce), 'sequencia': int(seq)}
+
+    m = re.fullmatch(r'EM13LP(\d{2})', codigo)
+    if m:
+        return {'codigo': codigo, 'etapa': 'EM', 'seriacao': None, 'area': 'LGG',
+                'area_nome': AREAS_EM['LGG'], 'componente': 'LP',
+                'competencia_especifica': None, 'sequencia': int(m.group(1))}
+
+    raise ValueError(f'{codigo}: não corresponde a nenhuma gramática BNCC (EI/EF/EM)')

bncc/_consultas.py

@@ -0,0 +1,165 @@
+"""API de consulta em português — espelho 1:1 do pacote npm @bncc/dados (snake_case)."""
+from ._codigos import decodificar
+from ._indice import indice, normalizar_texto, resolver_nome, versao as _versao
+
+
+def _resolver(reg):
+    i = indice()
+    etapa = decodificar(reg['codigo'])['etapa']
+    base = {'codigo': reg['codigo'], 'etapa': etapa, 'texto': reg['texto'],
+            'vigencia': reg['vigencia'], 'fonte': reg['fonte']}
+
+    if etapa == 'EI':
+        return {**base,
+                'campo_experiencias': {'id': reg['campo_experiencias'], 'nome': resolver_nome(reg['campo_experiencias'])},
+                'grupo_etario': reg['grupo_etario'],
+                'alinhamento': reg['alinhamento']}
+
+    if etapa == 'EF':
+        org = reg['organizacao']
+        nomes = {}
+        if 'unidade_tematica' in org:
+            nomes['unidade_tematica'] = resolver_nome(org['unidade_tematica'])
+        if org['tipo'] == 'campo_pratica':
+            nomes['campos_atuacao'] = [resolver_nome(c) for c in org['campos_atuacao']]
+            nomes['pratica_linguagem'] = resolver_nome(org['pratica_linguagem'])
+        if org['tipo'] == 'eixo':
+            nomes['eixo'] = resolver_nome(org['eixo'])
+        return {**base,
+                'componente': {'id': reg['componente'], 'nome': resolver_nome(reg['componente'])},
+                'anos': reg['anos'],
+                'organizacao': {'tipo': org['tipo'], 'nomes': nomes},
+                'objetos_conhecimento': [{'id': o, 'nome': resolver_nome(o)} for o in reg['objetos_conhecimento']]}
+
+    comps = []
+    for cid in reg['competencias_especificas']:
+        c = indice()['competencias'].get(cid, {})
+        comps.append({'id': cid, 'numero': c.get('numero', 0), 'texto': c.get('texto', '')})
+    return {**base,
+            'area': {'id': reg['area'], 'nome': resolver_nome(reg['area'])},
+            'componente': ({'id': reg['componente'], 'nome': resolver_nome(reg['componente'])}
+                           if reg['componente'] else None),
+            'competencias_especificas': comps,
+            'campos_atuacao_social': ([{'id': c, 'nome': resolver_nome(c)} for c in reg['campos_atuacao_social']]
+                                      if reg['campos_atuacao_social'] else None)}
+
+
+def por_codigo(codigo):
+    """Registro completo de uma aprendizagem pelo código (case-insensitive), com nomes resolvidos."""
+    cod = codigo.strip().upper()
+    reg = indice()['por_codigo'].get(cod)
+    if reg is None:
+        decodificar(cod)  # gramática inválida gera o erro explicativo
+        raise ValueError(f'{cod}: código válido na forma, mas não existe na BNCC '
+                         '(dica: a numeração tem lacunas legítimas)')
+    return _resolver(reg)
+
+
+def _id_componente(componente):
+    if componente is None:
+        return None
+    return componente if componente.startswith('ef-comp-') else f'ef-comp-{componente.lower()}'
+
+
+def habilidades_ef(componente=None, ano=None, unidade_tematica=None, pratica=None, campo_atuacao=None):
+    """Habilidades do Ensino Fundamental, com filtros opcionais (sigla ou id de componente)."""
+    comp = _id_componente(componente)
+    saida = []
+    for h in indice()['habilidades_ef']:
+        org = h['organizacao']
+        if comp and h['componente'] != comp:
+            continue
+        if ano and ano not in h['anos']:
+            continue
+        if unidade_tematica and not ('unidade_tematica' in org and resolver_nome(org['unidade_tematica']) == unidade_tematica):
+            continue
+        if pratica and not (org['tipo'] == 'campo_pratica' and resolver_nome(org['pratica_linguagem']) == pratica):
+            continue
+        if campo_atuacao and not (org['tipo'] == 'campo_pratica'
+                                  and any(resolver_nome(c) == campo_atuacao for c in org['campos_atuacao'])):
+            continue
+        saida.append(_resolver(h))
+    return saida
+
+
+def habilidades_em(area=None, competencia=None, apenas_lp=False):
+    """Habilidades do Ensino Médio. `area` aceita id (em-area-lgg) ou sigla (LGG)."""
+    aid = area if (area is None or area.startswith('em-area-')) else f'em-area-{area.lower()}'
+    i = indice()
+    saida = []
+    for h in i['habilidades_em']:
+        if aid and h['area'] != aid:
+            continue
+        if apenas_lp and h['componente'] != 'em-comp-lp':
+            continue
+        if competencia and not any(i['competencias'].get(c, {}).get('numero') == competencia
+                                   for c in h['competencias_especificas']):
+            continue
+        saida.append(_resolver(h))
+    return saida
+
+
+def objetivos_ei(campo=None, grupo_etario=None):
+    """Objetivos da Educação Infantil. `campo` aceita id (ei-campo-ts) ou sigla (TS)."""
+    cid = campo if (campo is None or campo.startswith('ei-campo-')) else f'ei-campo-{campo.lower()}'
+    gid = grupo_etario if (grupo_etario is None or grupo_etario.startswith('ei-grupo-')) else f'ei-grupo-{grupo_etario}'
+    return [_resolver(o) for o in indice()['objetivos_ei']
+            if (not cid or o['campo_experiencias'] == cid) and (not gid or o['grupo_etario'] == gid)]
+
+
+def buscar(texto, etapa=None, componente=None, ano=None):
+    """Busca textual normalizada (sem acentos/caixa) nos enunciados. Sem rede."""
+    alvo = normalizar_texto(texto)
+    i = indice()
+    universo = []
+    if etapa in (None, 'EI'):
+        universo += i['objetivos_ei']
+    if etapa in (None, 'EF'):
+        universo += i['habilidades_ef']
+    if etapa in (None, 'EM'):
+        universo += i['habilidades_em']
+    comp = componente if (componente is None or '-comp-' in componente) else f'ef-comp-{componente.lower()}'
+    saida = []
+    for r in universo:
+        if alvo not in normalizar_texto(r['texto']):
+            continue
+        if comp and r.get('componente') != comp:
+            continue
+        if ano and ano not in r.get('anos', []):
+            continue
+        saida.append(_resolver(r))
+    return saida
+
+
+def progressao_ei(codigo):
+    """Progressão oficial da EI: os objetivos do mesmo aspecto nas três faixas etárias."""
+    reg = por_codigo(codigo)
+    if reg['etapa'] != 'EI':
+        raise ValueError(f"{reg['codigo']}: progressão por alinhamento só existe na Educação Infantil")
+    al = indice()['alinhamento_por_id'][reg['alinhamento']]
+    return {'alinhamento': al['id'], 'objetivos': [por_codigo(c) for c in al['objetivos']],
+            'nota': al.get('nota')}
+
+
+def estrutura():
+    """A espinha estrutural completa (etapas, áreas, componentes, competências, recortes)."""
+    return indice()['estrutura']
+
+
+def estatisticas():
+    """Contagens do dataset."""
+    i = indice()
+    return {
+        'total': len(i['objetivos_ei']) + len(i['habilidades_ef']) + len(i['habilidades_em']),
+        'educacao_infantil': len(i['objetivos_ei']),
+        'ensino_fundamental': len(i['habilidades_ef']),
+        'ensino_medio': len(i['habilidades_em']),
+        'alinhamentos_ei': len(i['alinhamentos']),
+        'competencias_gerais': len(i['estrutura']['competencias_gerais']),
+        'competencias_especificas': len(i['estrutura']['competencias_especificas']),
+    }
+
+
+def versao():
+    """Data-version, commit de origem e checksums dos dados embutidos."""
+    return _versao()

bncc/_indice.py

@@ -0,0 +1,61 @@
+"""Carregamento lazy dos dados embutidos e índices em memória."""
+import json
+import re
+import unicodedata
+from functools import lru_cache
+from pathlib import Path
+
+_DADOS = Path(__file__).parent / 'dados'
+
+
+def _carregar(arquivo):
+    return json.loads((_DADOS / f'{arquivo}.json').read_text(encoding='utf-8'))
+
+
+@lru_cache(maxsize=1)
+def indice():
+    estrutura = _carregar('estrutura')
+    ei = _carregar('educacao-infantil')
+    ef = _carregar('ensino-fundamental')
+    em = _carregar('ensino-medio')
+
+    por_codigo = {}
+    for o in ei['objetivos']:
+        por_codigo[o['codigo']] = o
+    for h in ef['habilidades'] + em['habilidades']:
+        por_codigo[h['codigo']] = h
+
+    contextos = {c['id']: c for c in ef['contextos_organizacao'] + em['contextos_organizacao']}
+    competencias = {c['id']: c for c in estrutura['competencias_especificas']}
+    alinhamentos = {a['id']: a for a in ei['alinhamentos']}
+    nomes = {}
+    for c in estrutura['componentes_curriculares'] + estrutura['areas_conhecimento'] + estrutura['campos_experiencias']:
+        nomes[c['id']] = c['nome']
+
+    return {
+        'estrutura': estrutura,
+        'objetivos_ei': ei['objetivos'], 'alinhamentos': ei['alinhamentos'],
+        'habilidades_ef': ef['habilidades'], 'habilidades_em': em['habilidades'],
+        'por_codigo': por_codigo, 'contextos': contextos,
+        'competencias': competencias, 'alinhamento_por_id': alinhamentos, 'nomes': nomes,
+    }
+
+
+def versao():
+    """Metadados dos dados embutidos: data-version, commit de origem, checksums."""
+    return json.loads((_DADOS / 'VERSAO.json').read_text(encoding='utf-8'))
+
+
+def normalizar_texto(t):
+    """Normalização de busca: sem acentos, minúsculas, espaços únicos (mesma regra do @bncc/dados)."""
+    t = unicodedata.normalize('NFD', t)
+    t = ''.join(ch for ch in t if not unicodedata.combining(ch))
+    return re.sub(r'\s+', ' ', t.casefold()).strip()
+
+
+def resolver_nome(id_):
+    i = indice()
+    ctx = i['contextos'].get(id_)
+    if ctx:
+        return ctx['nome']
+    return i['nomes'].get(id_, id_)

bncc/_pandas.py

@@ -0,0 +1,38 @@
+"""Integração opcional com pandas (extra `bncc[pandas]`)."""
+
+
+def para_dataframe(etapa='EF'):
+    """DataFrame plano das aprendizagens de uma etapa ('EI', 'EF' ou 'EM').
+
+    Requer o extra: pip install bncc[pandas]
+    """
+    try:
+        import pandas as pd
+    except ImportError as e:
+        raise ImportError('para_dataframe requer pandas: pip install bncc[pandas]') from e
+
+    from ._consultas import habilidades_ef, habilidades_em, objetivos_ei
+
+    if etapa == 'EF':
+        registros = habilidades_ef()
+        linhas = [{
+            'codigo': r['codigo'], 'componente': r['componente']['nome'],
+            'anos': ' | '.join(map(str, r['anos'])),
+            'organizacao': r['organizacao']['tipo'],
+            'texto': r['texto'],
+        } for r in registros]
+    elif etapa == 'EM':
+        linhas = [{
+            'codigo': r['codigo'], 'area': r['area']['nome'],
+            'componente': r['componente']['nome'] if r['componente'] else None,
+            'competencias': ' | '.join(str(c['numero']) for c in r['competencias_especificas']),
+            'texto': r['texto'],
+        } for r in habilidades_em()]
+    elif etapa == 'EI':
+        linhas = [{
+            'codigo': r['codigo'], 'campo': r['campo_experiencias']['nome'],
+            'grupo_etario': r['grupo_etario'], 'texto': r['texto'],
+        } for r in objetivos_ei()]
+    else:
+        raise ValueError(f"etapa {etapa!r} inválida; use 'EI', 'EF' ou 'EM'")
+    return pd.DataFrame(linhas)

bncc/dados/VERSAO.json

@@ -0,0 +1,12 @@
+{
+  "data_version": "dados-2026.07",
+  "origem": "github.com/bncc-dev/bncc-dados",
+  "commit": "46accba58c68af21235c0b3d1d5ab3855834f739",
+  "sincronizado_de": "/Users/marcosbeto/Dev/bncc-dados",
+  "checksums_sha256": {
+    "estrutura.json": "0c499251a18a08508a74b1f4fa3ce4aae79ab9871bf0be65e4384629fb30b665",
+    "educacao-infantil.json": "e8549b4e35313b18d4fa02eb07b4ff603c3fef173224528a7aadd965680892e9",
+    "ensino-fundamental.json": "e18f7573a5c80ca326292160b8cc431992db80371923f2851974b919ac925817",
+    "ensino-medio.json": "380ff4761d5e287791de025ed806bcf343936a6398dbbab2e9265a2c42917adf"
+  }
+}