pynotas 0.12.0__py3-none-any.whl

pynotas/__init__.py

@@ -0,0 +1,42 @@
+"""PyNotas: código → modelo → representación → SVG/HTML."""
+from .analyzer import analyze as analizar
+from .selector import select as seleccionar
+from .renderers import render as renderizar
+from .notebook import activate as activar, deactivate as desactivar, diagnostics as diagnostico
+
+from ._version import __version__
+__all__ = ["analizar", "seleccionar", "renderizar", "generar", "mostrar", "activar", "desactivar", "diagnostico", "guardar", "explicar_archivo", "exportar"]
+
+
+def generar(codigo, formato="auto", nivel="inicial",
+            objetivo="Comprender cómo los datos se transforman en un resultado",
+            contexto="auto", oculto=False, descargas=True):
+    """Devuelve HTML autocontenido. No ejecuta codigo."""
+    model = analizar(codigo, objetivo, nivel, context=contexto)
+    return renderizar(model, seleccionar(model, formato), collapsed=oculto, downloads=descargas)
+
+
+def mostrar(codigo, **opciones):
+    """Muestra una lámina estática sin ejecutar codigo."""
+    try:
+        from IPython.display import HTML, display
+    except ImportError as error:
+        raise RuntimeError("mostrar() necesita IPython. Instala pynotas[notebook] o usa guardar().") from error
+    display(HTML(generar(codigo, **opciones)))
+
+
+def load_ipython_extension(ipython):
+    activar(shell=ipython)
+
+
+def unload_ipython_extension(ipython):
+    desactivar(shell=ipython)
+
+
+from .files import guardar, explicar_archivo
+from .exports import exportar
+
+# Importing in a notebook starts the existing post-run observer. No user code
+# is executed here; normal Python imports do not create an interactive shell.
+from .notebook import auto_activate as _auto_activate
+_auto_activate()

pynotas/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

pynotas/_version.py

@@ -0,0 +1 @@
+__version__ = "0.12.0"

pynotas/analysis_context.py

@@ -0,0 +1,47 @@
+"""Reviewed analytical purpose, principle and interpretation; no runtime values."""
+from dataclasses import dataclass
+from .lessons import LESSONS
+
+
+@dataclass(frozen=True)
+class AnalysisContext:
+    title: str
+    purpose: str
+    principle: str
+    interpretation: str
+    formula: str = ''
+    source: str = ''
+
+
+RMS_SOURCE='https://www.ifm.com/ca/en/shared/technologies/real-time-maintenance/technology/time-domain'
+
+
+def for_model(model,representation):
+    keys={t.key for t in model.theories}
+    if 'rms' in keys:
+        return AnalysisContext('RMS · medir la magnitud de una señal',
+            'Resumir la magnitud global de una señal real. En vibraciones ayuda a seguir cambios en el nivel de un registro.',
+            'Los signos pueden cancelarse al promediar. Elevar al cuadrado evita esa cancelación; promediar resume y la raíz recupera las unidades.',
+            'Un RMS mayor indica mayor magnitud en el registro. Compara iguales unidades, banda y condiciones. Por sí solo no identifica una falla.',
+            'RMS = √[(x₁² + … + xₙ²) / N]     x: muestras reales · N: cantidad de muestras',RMS_SOURCE)
+    if 'fft' in keys:
+        return AnalysisContext('FFT · reconocer componentes de frecuencia',
+            'Pasar de cómo cambia una señal en el tiempo a qué componentes de frecuencia contiene.',
+            'La transformada expresa la señal muestreada como componentes sinusoidales. La frecuencia de muestreo permite construir el eje en Hz.',
+            'Un pico señala una componente destacada. Revisa escalado, ventana y muestreo antes de interpretar amplitudes; un pico no confirma una falla.',
+            'Separación entre frecuencias = fs / N · Límite de Nyquist = fs / 2',
+            'https://numpy.org/doc/stable/reference/routines.fft.html')
+    if model.case:
+        vibration=('En vibraciones, ' if model.context=='vibraciones' else 'Si los datos son vibraciones, ')
+        return AnalysisContext('Archivo MATLAB · preparar los datos para analizarlos',
+            'Identificar qué variables hay y cómo están organizadas antes de elegir los datos del análisis.',
+            'Un .mat guarda variables. loadmat las organiza por nombre en un diccionario; type indica su tipo y shape, sus dimensiones.',
+            vibration+'identifica canal, eje de muestras, unidades y frecuencia de muestreo. Cargar el archivo todavía no calcula RMS ni FFT.',
+            source='https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.loadmat.html')
+    if model.theories:
+        theory=model.theories[0]
+        return AnalysisContext(theory.title,theory.idea,' → '.join(theory.steps)+'.',theory.meaning,source=theory.source)
+    lesson=LESSONS.get(representation.lesson_key,LESSONS['generic'])
+    return AnalysisContext(lesson.title,lesson.idea,
+        (' → '.join(s for s in (lesson.incoming,lesson.action,lesson.outgoing) if s)+'.') if lesson.incoming else 'Importar permite usar herramientas; no realiza todavía el análisis.',
+        lesson.meaning,source=lesson.source)

pynotas/analyzer.py

@@ -0,0 +1,173 @@
+"""Lee sintaxis exclusivamente: no evalúa, ejecuta ni inspecciona variables."""
+import ast
+from .model import Block, Expression, PedagogicalModel, Section
+from .resources import describe_import, enrich_setup
+from .teaching import explain, enrich_sequence
+
+OPS = {ast.Add: "Suma (+)", ast.Sub: "Resta (−)", ast.Mult: "Producto (×)",
+       ast.Div: "División (/)", ast.FloorDiv: "División entera (//)",
+       ast.Mod: "Resto (%)", ast.Pow: "Potencia (**)"}
+
+
+def analyze(source, objective="Comprender cómo los datos se transforman en un resultado",
+            level="inicial", context="auto", bindings=None):
+    if not isinstance(source, str):
+        raise TypeError("El código debe ser texto.")
+    if not isinstance(objective, str):
+        raise TypeError("El objetivo debe ser texto.")
+    if level not in {"inicial", "intermedio", "avanzado"}:
+        raise ValueError("Nivel válido: inicial, intermedio, avanzado.")
+    if len(source) > 60000:
+        raise ValueError("La lámina admite hasta 60 000 caracteres por celda.")
+    tree = ast.parse(source)
+    if sum(1 for _ in ast.walk(tree)) > 1500:
+        raise ValueError("Celda demasiado extensa: divídela en pasos pedagógicos.")
+    notes = []
+    counter = 0
+
+    def segment(node):
+        return ast.get_source_segment(source, node) or ""
+
+    def expr(node, depth=0):
+        children = ()
+        label = "Expresión"
+        if isinstance(node, ast.BinOp):
+            label = OPS.get(type(node.op), "Operación " + type(node.op).__name__)
+            if isinstance(node.op, ast.Add):
+                label = "Unir listas (+)" if any(isinstance(n, ast.List) for n in (node.left, node.right)) else "Combinar con +"
+            if depth < 4:
+                children = (expr(node.left, depth + 1), expr(node.right, depth + 1))
+        elif isinstance(node, ast.Name):
+            label = "Dato que usaremos"
+        elif isinstance(node, ast.Constant):
+            label = "Valor escrito"
+        elif isinstance(node, ast.Call):
+            label = "Resultado de una función"
+        return Expression(segment(node), label, node.lineno, node.end_lineno, children)
+
+    def block(node):
+        nonlocal counter
+        counter += 1
+        if counter > 60:
+            raise ValueError("La lámina admite hasta 60 instrucciones; divide el código.")
+        ident = f"b{counter}"
+        code = segment(node)
+        kind, title = "opaque", "Bloque de código"
+        explanation = "Estructura agrupada; sus pasos internos no se representan en esta versión."
+        body, alternative, expression = (), (), None
+        reads, writes = (), ()
+        summaries = ()
+        resources = ()
+        sections = []
+        if isinstance(node, ast.If):
+            kind, title = "decision", "Evaluar condición"
+            code = segment(node.test)
+            explanation = "La condición selecciona una alternativa. No se observa qué rama se ejecutó."
+            body = tuple(block(n) for n in node.body)
+            alternative = tuple(block(n) for n in node.orelse)
+        elif isinstance(node, (ast.Assign, ast.AnnAssign, ast.AugAssign)):
+            value = node.value
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+            simple = all(isinstance(t, ast.Name) for t in targets)
+            if simple and value is not None:
+                kind, title = "transform", "Obtener y asignar"
+                if isinstance(value, (ast.Constant, ast.List, ast.Tuple, ast.Dict, ast.Set)):
+                    kind, title = "data", "Definir datos"
+                if isinstance(value, ast.BinOp):
+                    kind, title, expression = "operation", "Combinar expresiones", expr(value)
+                reads = tuple(sorted({n.id for n in ast.walk(value)
+                                      if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Load)}))
+                writes = tuple(t.id for t in targets)
+                if isinstance(node, ast.AugAssign):
+                    reads = tuple(sorted(set(reads) | set(writes)))
+                # Scope-changing expressions cannot support simple name dependencies.
+                if any(isinstance(n, (ast.NamedExpr, ast.Lambda, ast.ListComp,
+                                      ast.SetComp, ast.DictComp, ast.GeneratorExp))
+                       for n in ast.walk(value)):
+                    kind = "opaque"
+                explanation = "Relaciona el destino con la expresión de la derecha; no se calcula su valor."
+            elif isinstance(node, ast.AnnAssign) and value is None:
+                kind, title = "opaque", "Anotar un nombre"
+                explanation = "Declara una anotación de tipo sin asignar un valor."
+        elif isinstance(node, ast.Expr):
+            kind, title = "call", "Evaluar expresión"
+            explanation = "Expresión tal como aparece en el código; no se vuelve a evaluar."
+            if isinstance(node.value, ast.Call):
+                title = "Llamar una operación"
+                if isinstance(node.value.func, ast.Name) and node.value.func.id == "print":
+                    title = "Mostrar información"
+                    explanation = "Llama al nombre print. La salida original permanece en el notebook."
+            reads = tuple(sorted({n.id for n in ast.walk(node)
+                                  if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Load)}))
+            if any(isinstance(n, (ast.NamedExpr, ast.Lambda, ast.ListComp,
+                                  ast.SetComp, ast.DictComp, ast.GeneratorExp)) for n in ast.walk(node)):
+                kind = "opaque"
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            kind = "import"
+            title, summaries, explanation, resources = describe_import(node)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            title = "Definir " + node.name
+            explanation = "Definición agrupada. Su cuerpo no se presenta como si se hubiera ejecutado."
+        elif isinstance(node, (ast.For, ast.AsyncFor, ast.While)):
+            title = "Repetición · bloque agrupado"
+        elif isinstance(node, ast.Raise):
+            kind, title = "stop", "Lanzar excepción"
+            explanation = "Interrumpe este camino mediante una excepción."
+        # Nested scopes are explained in foldouts, not attached as executed paths.
+        def section(label, statements):
+            if statements:
+                sections.append(Section(label, enrich_sequence(tuple(block(n) for n in statements), statements)))
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            section("Dentro de la función · se utiliza mediante una llamada", node.body)
+        elif isinstance(node, ast.ClassDef):
+            section("Dentro de la definición de clase", node.body)
+        elif isinstance(node, (ast.For, ast.AsyncFor, ast.While)):
+            section("Dentro de la repetición", node.body)
+            section("Al terminar sin break", node.orelse)
+        elif isinstance(node, (ast.With, ast.AsyncWith)):
+            section("Dentro del contexto", node.body)
+        elif isinstance(node, (ast.Try, getattr(ast, 'TryStar', ast.Try))):
+            section("Instrucciones que se intentan", node.body)
+            for handler in node.handlers:
+                section("Respuesta al error: " + (ast.unparse(handler.type) if handler.type else "cualquier excepción"), handler.body)
+            section("Si termina sin excepción", node.orelse)
+            section("Al salir de este intento (finally)", node.finalbody)
+        elif isinstance(node, ast.Match):
+            for case in node.cases:
+                label = "Caso: " + ast.unparse(case.pattern)
+                if case.guard: label += " · si " + ast.unparse(case.guard)
+                section(label, case.body)
+        if kind == "opaque":
+            notes.append(f"Línea {node.lineno}: ver el código para seguir todos sus pasos.")
+        return explain(Block(ident, kind, title, code, node.lineno, node.end_lineno,
+                     explanation, reads, writes, body, alternative, expression, summaries, resources, sections=tuple(sections),
+                     column=node.col_offset,end_column=node.end_col_offset), node)
+
+    blocks = tuple(block(node) for node in tree.body)
+    blocks = enrich_sequence(blocks, tree.body)
+    blocks = enrich_setup(blocks, tree.body, source)
+    if len(list(walk_blocks(blocks))) > 60:
+        raise ValueError("La lámina admite hasta 60 bloques; divide la celda.")
+    from .theory import enrich
+    blocks, theories = enrich(blocks, tree.body, context, bindings)
+    model = PedagogicalModel(source, blocks, objective, level, tuple(notes), context=context, theories=theories)
+    from .walkthrough import enrich_reading
+    from .stages import enrich_stages
+    return enrich_stages(enrich_reading(model, tree, bindings), tree, bindings)
+
+
+def walk_blocks(blocks):
+    for block in blocks:
+        yield block
+        yield from walk_blocks(block.body)
+        yield from walk_blocks(block.alternative)
+
+
+def walk_details(blocks):
+    """Walk all source instructions, including deferred/compound scopes, for detail only."""
+    for b in blocks:
+        yield b
+        yield from walk_details(b.body)
+        yield from walk_details(b.alternative)
+        for section in b.sections:
+            yield from walk_details(section.blocks)

pynotas/artwork.py

@@ -0,0 +1,223 @@
+"""Automatic vector compositions selected from the pedagogical model.
+
+All diagrams are conceptual. This module never evaluates code, reads notebook
+variables, or reconstructs results. SVG and PDF consume the same primitives.
+"""
+import math
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Theme:
+    kind: str
+    label: str
+    accent: str
+    light: str
+    bright: str
+    secondary: str = '#FAAA72'
+
+
+THEMES = {
+    'signal': Theme('signal', 'SEÑALES Y MAGNITUDES', '#007B74', '#E2F2E9', '#78E8CB'),
+    'network': Theme('network', 'REDES NEURONALES', '#6451BF', '#EEE9FB', '#C9B3FF'),
+    'learning': Theme('learning', 'APRENDIZAJE CON DATOS', '#2857AB', '#E8EEFB', '#94C5FF'),
+    'decision': Theme('decision', 'DECISIONES EN PYTHON', '#A94825', '#FBEBDC', '#FFBE8B'),
+    'expression': Theme('expression', 'DATOS Y OPERACIONES', '#18787B', '#E3F2EF', '#79DDD7'),
+    'resources': Theme('resources', 'HERRAMIENTAS DE PYTHON', '#476199', '#E9EEFA', '#AAC4FF'),
+    'code': Theme('code', 'LEER Y COMPRENDER PYTHON', '#18787B', '#E3F2EF', '#79DDD7'),
+}
+
+
+def theme_for(model, representation):
+    from .illustrations import kind_for
+    from .model import is_preparation
+    if representation.format == 'decisiones':
+        return THEMES['decision']
+    if is_preparation(model):
+        return THEMES['resources']
+    kind = kind_for(tuple(t.key for t in model.theories))
+    if kind == 'code' and representation.format == 'despiece':
+        kind = 'expression'
+    return THEMES[kind]
+
+
+def wave(p, x, y, w, h, color, squared=False):
+    """A schematic oscillation, with no measured coordinates or values."""
+    points = []
+    for i in range(81):
+        value = math.sin(i / 80 * math.pi * 4)
+        if squared:
+            value = value * value
+        points.append((x + i * w / 80, y - h * value))
+    p.line(x, y, x+w, y, '#47606A', .6)
+    for a, b in zip(points, points[1:]):
+        p.line(*a, *b, color, 1.65)
+    for i in (7, 29, 49, 72):
+        p.circle(*points[i], 2.1, '#FAAA72')
+
+
+def connector(p, x, y, x2, y2, color):
+    dx = (x2-x) * .52
+    p.path([('M', x, y), ('C', x+dx, y, x2-dx, y2, x2, y2)], stroke=color, width=1)
+
+
+def icon(p, cx, cy, kind, color, size=19):
+    if kind == 'table':
+        for row in range(3):
+            for col in range(3):
+                p.rect(cx-size+col*14, cy-size+row*13, 10, 9,
+                       color if row != 2 else '#FAAA72', 2)
+    elif kind == 'braces':
+        p.text(cx-23, cy+9, '{ }', 24, color, 'PyNotasMono')
+    elif kind == 'bars':
+        for i, height in enumerate((14, 30, 21, 39, 17)):
+            p.rect(cx-27+i*12, cy+20-height, 7, height, color if i != 3 else '#FAAA72', 2)
+    elif kind == 'dots':
+        for i, (dx, dy) in enumerate(((-16,-12),(-5,4),(9,-17),(20,10),(-20,18),(4,21))):
+            p.circle(cx+dx, cy+dy, 4, color if i < 4 else '#FAAA72')
+    else:
+        p.circle(cx, cy, 18, color)
+        p.circle(cx, cy, 8, '#153944')
+
+
+def _label(p, x, y, text, width, color, size=8.1):
+    # Page.paragraph preserves every label, wrapping inside its allocated space.
+    p.paragraph(x, y, text, width, size, color, step=max(11,size*1.3))
+
+
+def draw(p, x, y, w, theme, keys=(), steps=(), resources=(), decision=None):
+    """Full-width teaching canvas. Returns height for the pagination engine."""
+    kind = theme.kind
+    h = 140 if kind == 'decision' else 156
+    p.rect(x, y, w, h, '#102F3B', 12)
+    # Small dotted construction grid gives the diagram a drawing-board texture.
+    for xx in range(16, int(w)-8, 22):
+        for yy in range(16, h-8, 22):
+            p.circle(x+xx, y+yy, .55, '#28434D')
+    p.rect(x+14, y+13, 3, 10, theme.bright, 1)
+    p.text(x+24, y+21, 'MAPA VISUAL', 7.4, theme.bright, 'PyNotasBold')
+    p.text(x+w-202, y+21, 'Esquema conceptual · sin resultados', 7, '#C3D4D8')
+
+    if kind == 'network':
+        layers = [[(x+72,y+q) for q in (56,83,110)],
+                  [(x+208,y+q) for q in (46,70,94,118)],
+                  [(x+337,y+q) for q in (69,99)]]
+        for a, b in zip(layers, layers[1:]):
+            for ax, ay in a:
+                for bx, by in b:
+                    connector(p, ax+6, ay, bx-6, by, '#58647F')
+        for i, layer in enumerate(layers):
+            for xx, yy in layer:
+                p.circle(xx, yy, 12, '#3B465E')
+                p.circle(xx, yy, 7.2, (theme.bright, '#82DDC5', theme.secondary)[i])
+                p.circle(xx, yy, 2.3, '#FFFFFF')
+        for xx, label in [(x+40,'Entradas'),(x+172,'Capas conectadas'),(x+317,'Salidas')]:
+            p.text(xx, y+143, label, 8, '#EDF7F6')
+        p.line(x+385,y+45,x+385,y+124,'#45616A',.8)
+        _label(p,x+399,y+61,'Cada conexión participa en el cálculo.',w-414,'#E2EAF0',9)
+        _label(p,x+399,y+107,'La cantidad de nodos es ilustrativa.',w-414,'#B5C8D0',7.4)
+
+    elif kind == 'signal':
+        is_rms = 'rms' in keys
+        labels = ('Datos reales','Elevar al cuadrado','Promediar','Obtener la raíz') if is_rms else tuple(steps)
+        if not labels:
+            labels = ('Muestras','Operación','Representación')
+        count = min(len(labels), 4)
+        span = (w-30)/count
+        for i, label in enumerate(labels[:count]):
+            xx=x+15+i*span; cx=xx+span/2
+            p.text(xx+8,y+43,f'{i+1:02d}',7,theme.bright,'PyNotasBold')
+            if i==0 or (is_rms and i==1):
+                wave(p,xx+12,y+86,span-27,19,theme.bright,squared=(i==1))
+            elif is_rms and i==2:
+                for j,height in enumerate((23,11,33,18,26)):
+                    p.rect(cx-31+j*13,y+105-height,8,height,'#557E80',2)
+                p.line(cx-37,y+81,cx+37,y+81,theme.secondary,2)
+                p.text(cx-19,y+62,'media',8.5,theme.secondary)
+            elif is_rms:
+                p.circle(cx,y+80,26,'#2B534F')
+                p.text(cx-17,y+91,'√',32,theme.bright,'PyNotasBold')
+            elif i==1 and 'fft' in keys:
+                p.text(cx-27,y+88,'FFT',22,theme.bright,'PyNotasBold')
+            else:
+                icon(p,cx,y+82,'bars' if 'fft' in keys else 'braces',theme.bright)
+            _label(p,xx+7,y+127,label,span-15,'#F4F7F7')
+            if i<count-1:
+                p.arrow(xx+span-10,y+83,xx+span+4,y+83,theme.secondary)
+
+    elif kind == 'learning':
+        split = 'split' in keys
+        icon(p,x+67,y+81,'table',theme.bright)
+        if split:
+            connector(p,x+104,y+81,x+221,y+57,theme.bright)
+            connector(p,x+104,y+81,x+221,y+107,theme.secondary)
+            p.rect(x+223,y+39,154,35,'#244A65',7)
+            p.rect(x+223,y+90,154,35,'#60463C',7)
+            p.text(x+237,y+61,'Entrenamiento',10,theme.bright,'PyNotasBold')
+            p.text(x+237,y+112,'Prueba',10,theme.secondary,'PyNotasBold')
+            _label(p,x+393,y+57,'Aprender con una parte.',w-407,'#D8E7F1',8.5)
+            _label(p,x+393,y+108,'Evaluar con otra.',w-407,'#F5DAC4',8.5)
+            p.text(x+38,y+139,'Conjunto de datos',8,'#E6EFF3')
+        else:
+            centers=(x+67,x+267,x+462)
+            p.arrow(centers[0]+41,y+82,centers[1]-39,y+82,theme.bright)
+            p.arrow(centers[1]+40,y+82,centers[2]-41,y+82,theme.secondary)
+            p.circle(centers[1],y+82,30,'#28465E')
+            icon(p,centers[1],y+82,'braces',theme.bright)
+            icon(p,centers[2],y+82,'dots',theme.secondary)
+            labels=tuple(steps) if len(steps)==3 else ('Datos','Operación reconocida','Salida conceptual')
+            for cx,label in zip(centers,labels):_label(p,cx-58,y+135,label,118,'#E6EFF3')
+
+    elif kind == 'decision':
+        cx=x+249;cy=y+72
+        p.path([('M',cx,cy-37),('L',cx+61,cy),('L',cx,cy+37),('L',cx-61,cy),('Z',)],
+               fill='#624936',stroke=theme.bright,width=1.4)
+        if decision:
+            from .layout import wrap
+            condition=decision.code.removeprefix('if ').removeprefix('elif ').rstrip(':').strip()
+            rows=wrap(condition,92,8,'PyNotasMono')
+            if len(rows)>2:rows=[rows[0],rows[1][:-1]+'…']
+            for i,row in enumerate(rows):p.text(cx-46,cy+3+(i-(len(rows)-1)/2)*12,row,8,theme.bright,'PyNotasMono')
+            p.text(cx-28,cy-43,f'CONDICIÓN · L{decision.line}',6.8,theme.bright,'PyNotasBold')
+        else:p.text(cx-11,cy+10,'?',30,theme.bright,'PyNotasBold')
+        p.text(x+22,y+68,'Evaluar',11,'#F6EEE6','PyNotasBold')
+        p.text(x+22,y+83,'la condición',9,'#C7D6D9')
+        p.arrow(x+121,cy,cx-67,cy,theme.bright)
+        connector(p,cx+63,cy,x+389,y+49,'#90DBBA')
+        connector(p,cx+63,cy,x+389,y+101,theme.secondary)
+        for yy,label,col in ((49,'Verdadero','#90DBBA'),(101,'Falso',theme.secondary)):
+            p.circle(x+399,y+yy,6,col);p.text(x+414,y+yy+4,label,10,col,'PyNotasBold')
+        p.text(x+157,y+131,'Se muestran alternativas; no una rama observada.',8,'#C7D6D9')
+
+    elif kind == 'resources':
+        names=list(dict.fromkeys(resources))[:5]
+        if not names:names=[('','Recursos')]
+        span=(w-28)/len(names)
+        from .layout import wrap,fonts
+        for i,(qualified,name) in enumerate(names):
+            cx=x+90 if len(names)==1 else x+14+(i+.5)*span
+            p.circle(cx,y+78,28,'#2C4661')
+            shape='bars' if 'matplotlib' in qualified or 'seaborn' in qualified else 'table' if qualified.split('.')[0] in {'pandas','numpy'} else 'braces'
+            icon(p,cx,y+77,shape,theme.bright)
+            if len(name)>24:name=name[:23]+'…'
+            if len(names)==1:
+                headline=qualified or name
+                if len(headline)>35:headline=headline[:34]+'…'
+                _label(p,x+160,y+66,headline,w-181,theme.bright,14)
+                p.text(x+160,y+96,'Nombre de uso: '+name,10,'#ECF1F8')
+                p.text(x+160,y+123,'Disponible para tus próximas instrucciones.',8,'#B9CED9')
+            else:
+                for j,row in enumerate(wrap(name,span-18,8.4)):
+                    p.text(cx-fonts().stringWidth(row,'PyNotas',8.4)/2,y+125+j*11,row,8.4,'#ECF1F8')
+        # Imports are grouped tools, not a sequence or a data dependency graph.
+
+    else:
+        centers=(x+73,x+266,x+459)
+        icon(p,centers[0],y+82,'table',theme.bright)
+        p.circle(centers[1],y+82,32,'#255054')
+        icon(p,centers[1],y+82,'braces',theme.bright)
+        icon(p,centers[2],y+82,'dots',theme.secondary)
+        for a,b in zip(centers,centers[1:]):p.arrow(a+43,y+82,b-45,y+82,theme.bright)
+        for cx,label in zip(centers,('Datos de entrada','Instrucciones','Salida conceptual')):
+            p.text(cx-44,y+137,label,8.2,'#EEF5F5')
+    return h

pynotas/capture.py

@@ -0,0 +1,81 @@
+"""Copy bounded PNG/JPEG display messages, forwarding the original unchanged."""
+import base64
+import io
+from .model import CapturedFigure
+
+MAX_BYTES=8_000_000
+MAX_PIXELS=20_000_000
+MAX_FIGURES=4
+
+
+def raster(mime,payload):
+    from PIL import Image
+    if mime not in {'image/png','image/jpeg'}:raise ValueError('Formato no admitido')
+    if not isinstance(payload,(str,bytes)) or len(payload)>MAX_BYTES*4//3+8:raise ValueError('Imagen demasiado grande')
+    raw=base64.b64decode(payload,validate=True) if isinstance(payload,str) else payload
+    if len(raw)>MAX_BYTES:raise ValueError('Imagen demasiado grande')
+    with Image.open(io.BytesIO(raw)) as im:
+        w,h=im.size
+        if w*h>MAX_PIXELS or im.format!=({'image/png':'PNG','image/jpeg':'JPEG'}[mime]):raise ValueError('Imagen no admitida')
+        im.verify()
+    return CapturedFigure(mime,base64.b64encode(raw).decode('ascii'),w,h)
+
+
+class DisplayCapture:
+    def __init__(self,publisher):
+        self.publisher=publisher;self.saved=[];self.images=[];self.notes=[];self.clear_pending=False
+
+    def note(self):
+        message='Alguna imagen no se incorporó por su formato, tamaño o límite de 4 imágenes. Consulta la salida original.'
+        if message not in self.notes:self.notes.append(message)
+
+    def receive(self,data,transient=None,update=False):
+        if not isinstance(data,dict):return
+        if self.clear_pending:self.images.clear();self.clear_pending=False
+        key=(transient or {}).get('display_id')
+        for mime in ('image/png','image/jpeg'):
+            if mime not in data:continue
+            try:
+                fig=raster(mime,data[mime])
+                index=next((i for i,(old,_) in enumerate(self.images) if key and old==key),None)
+                if update and index is None:return
+                candidates=list(self.images)
+                if index is not None:candidates[index]=(key,fig)
+                else:candidates.append((key,fig))
+                if len(candidates)>MAX_FIGURES or sum(len(f.data)*3//4 for _,f in candidates)>MAX_BYTES:raise ValueError('Límite')
+                self.images=candidates
+            except Exception:self.note()
+            return
+
+    def install(self):
+        original=self.publisher.publish
+        def publish(*args,**kwargs):
+            result=original(*args,**kwargs)
+            try:self.receive(kwargs.get('data',args[0] if args else None),kwargs.get('transient'),kwargs.get('update',False))
+            except Exception:self.note()
+            return result
+        self.wrap('publish',publish)
+        original_clear=getattr(self.publisher,'clear_output',None)
+        if original_clear:
+            def clear(*args,**kwargs):
+                result=original_clear(*args,**kwargs)
+                wait=kwargs.get('wait',args[0] if args else False)
+                if wait:self.clear_pending=True
+                else:self.images.clear();self.clear_pending=False
+                return result
+            self.wrap('clear_output',clear)
+
+    def wrap(self,name,wrapper):
+        namespace=vars(self.publisher)
+        self.saved.append((name,name in namespace,namespace.get(name),wrapper))
+        setattr(self.publisher,name,wrapper)
+
+    def restore(self):
+        for name,existed,old,wrapper in reversed(self.saved):
+            if getattr(self.publisher,name,None) is wrapper:
+                if existed:setattr(self.publisher,name,old)
+                else:delattr(self.publisher,name)
+        self.saved.clear()
+
+    @property
+    def figures(self):return tuple(f for _,f in self.images)

pynotas/cli.py

@@ -0,0 +1,22 @@
+"""Command-line entry point. User scripts are always read, never executed."""
+import argparse
+import sys
+from .files import explicar_archivo
+from ._version import __version__
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description='Explica un archivo Python como lámina HTML sin ejecutarlo.')
+    parser.add_argument('--version', action='version', version='PyNotas '+__version__)
+    parser.add_argument('archivo', help='Archivo .py que quieres comprender')
+    parser.add_argument('-o','--salida', help='Ruta del HTML; por defecto: archivo.pynotas.html')
+    parser.add_argument('--formato', choices=['auto','flujo','despiece','decisiones'], default='auto')
+    parser.add_argument('--sobrescribir', action='store_true', help='Permite reemplazar el HTML de destino')
+    args = parser.parse_args(argv)
+    try:
+        output = explicar_archivo(args.archivo,args.salida,sobrescribir=args.sobrescribir,formato=args.formato)
+    except (OSError,UnicodeError,SyntaxError,ValueError,RecursionError) as error:
+        print(f'No se pudo crear la lámina: {error}', file=sys.stderr)
+        return 2
+    print(f'Lámina guardada en {output}. El archivo Python no se ejecutó.')
+    return 0