"""Guion práctico y sencillo de U2.3, U2.4 y U2.5.

El ejemplo común utiliza temperaturas para que la clase avance de forma
progresiva:

1. U2.3: controlamos entradas que pueden fallar.
2. U2.4: investigamos y corregimos un error lógico.
3. U2.5: comentamos y documentamos el programa.

El código utiliza únicamente conceptos básicos: variables, listas, funciones,
condicionales, bucles, excepciones, aserciones y comentarios.

Uso desde una terminal:

    python PROG-U2.-ClasePractica2345.py 2.3
    python PROG-U2.-ClasePractica2345.py 2.4
    python PROG-U2.-ClasePractica2345.py 2.5
    python PROG-U2.-ClasePractica2345.py todas

En PyCharm y Visual Studio Code, las marcas ``# %%`` separan bloques que se
pueden ejecutar de forma independiente. También se pueden ejecutar las
funciones ``ejecutar_u23()``, ``ejecutar_u24()`` y ``ejecutar_u25()`` desde la
consola Python.
"""

import sys


# Referencias generales de U1 que aparecen en este guion:
# - Bloques y funciones: https://revilofe.github.io/section1/u01/teoria/PROG-U1.2.-PracticaConUnLenguajes/#12-bloques-habituales-en-python
# - Variables y tipos: https://revilofe.github.io/section1/u01/teoria/PROG-U1.2.-PracticaConUnLenguajes/#31-valores-variables-y-tipos
# - Operadores lógicos: https://revilofe.github.io/section1/u01/teoria/PROG-U1.2.-PracticaConUnLenguajes/#44-operadores-logicos
# - Conversiones: https://revilofe.github.io/section1/u01/teoria/PROG-U1.2.-PracticaConUnLenguajes/#6-entrada-de-datos-y-conversiones
# - Comentarios y docstrings: https://revilofe.github.io/section1/u01/teoria/PROG-U1.2.-PracticaConUnLenguajes/#7-comentarios-y-documentacion-docstrings


# %% Preparación común

# GUÍA DE PREPARACIÓN:
# Ejecuta esta celda una vez antes de trabajar con U2.3, U2.4 o U2.5 desde
# PyCharm o Visual Studio Code. Define el título que utilizan las tres partes.

def mostrar_titulo(titulo: str) -> None:
    """Muestra un título para separar las demostraciones de la clase.

    Args:
        titulo (str): Texto que se mostrará como encabezado.

    Returns:
        None: Esta función solo muestra información por pantalla.
    """

    print("\n" + "=" * 72)
    print(titulo)
    print("=" * 72)


# %% U2.3 - Control de excepciones

# Referencias exactas de los apuntes:
# - Tracebacks: https://revilofe.github.io/section1/u02/teoria/PROG-U2.3.-Excepciones/#13-como-leer-un-traceback
# - try-except y conversión: https://revilofe.github.io/section1/u02/teoria/PROG-U2.3.-Excepciones/#21-conversion-segura-de-una-temperatura
# - else: https://revilofe.github.io/section1/u02/teoria/PROG-U2.3.-Excepciones/#32-la-clausula-else
# - finally: https://revilofe.github.io/section1/u02/teoria/PROG-U2.3.-Excepciones/#33-la-clausula-finally
# - raise: https://revilofe.github.io/section1/u02/teoria/PROG-U2.3.-Excepciones/#41-la-sentencia-raise
# - assert: https://revilofe.github.io/section1/u02/teoria/PROG-U2.3.-Excepciones/#44-aserciones-para-desarrollo
# - Validación y pruebas: https://revilofe.github.io/section1/u02/teoria/PROG-U2.3.-Excepciones/#5-aplicacion-validar-entradas-y-probar-el-comportamiento

# GUÍA PARA MOSTRAR U2.3 EN CLASE:
# 1. Ejecuta primero la celda `Preparación común` y después esta celda para
#    cargar las funciones. El marcador # %% no llama automáticamente a ninguna.
# 2. Antes de ejecutar la demostración, pide al grupo que prediga qué ocurrirá:
#       procesar_temperatura("72")
#       procesar_temperatura("rojo")
#       procesar_temperatura("-500")
# 3. Ejecuta esas tres llamadas desde la consola y relaciona cada resultado con
#    try, except, else, finally y raise.
# 4. Ejecuta la demostración completa escribiendo en la consola:
#       ejecutar_u23()
# 5. En la salida, detente en la pregunta final y pide una explicación antes
#    de consultar la respuesta orientativa escrita como comentario.
# 6. Para mostrar un traceback real, ejecuta por separado `float("rojo")` en
#    la consola. Después explica por qué el try-except evita que se detenga el
#    programa en la demostración.
# 7. Desde una terminal, la misma parte se ejecuta con:
#       python docs/section1/u02/teoria/otrosRecursos/PROG-U2.-ClasePractica2345.py 2.3


def procesar_temperatura(entrada: str) -> None:
    """Convierte una temperatura y muestra qué ocurre en cada caso.

    Args:
        entrada (str): Temperatura en grados Fahrenheit escrita como texto.

    Returns:
        None: Muestra el resultado, el error o el final de la comprobación.
    """

    print(f"\nEntrada recibida: {entrada!r}")

    try:
        # float() puede fallar si el texto no representa un número.
        # fahrenheit y celsius son números decimales: tipo float.
        fahrenheit: float = float(entrada)
        celsius: float = (fahrenheit - 32) * 5 / 9

        # raise permite rechazar un dato que no cumple una condición del
        # problema, aunque la conversión a número sí haya funcionado.
        if celsius < -273.15:
            raise ValueError("La temperatura es inferior al cero absoluto.")
    except ValueError as error:
        # Capturamos una excepción concreta y comunicamos su motivo.
        print(f"No se puede procesar la entrada: {error}")
    else:
        # else solo se ejecuta cuando no ha ocurrido ninguna excepción.
        print(f"Temperatura convertida: {celsius:.2f} °C")
    finally:
        # finally se ejecuta tanto si la entrada era correcta como si fallaba.
        print("Fin de la comprobación.")


def calcular_media(valores: list[float]) -> float:
    """Calcula una media para mostrar una aserción de desarrollo.

    Args:
        valores (list[float]): Lista de números que se van a promediar.

    Returns:
        float: Media aritmética de los valores recibidos.

    Raises:
        AssertionError: Si la lista está vacía durante el desarrollo.
    """

    # La aserción detecta un supuesto que debería cumplirse en el programa.
    # No sustituye a validar entradas que proceden de una persona usuaria.
    assert valores, "La lista no debería estar vacía durante el desarrollo."
    return sum(valores) / len(valores)


def ejecutar_u23() -> None:
    """Ejecuta la parte práctica de control de excepciones.

    Returns:
        None: Muestra por pantalla los ejemplos de U2.3.
    """

    mostrar_titulo("U2.3 - CONTROL DE EXCEPCIONES")
    print("Objetivo: distinguir una entrada válida de una situación que")
    print("debe comunicarse mediante una excepción.")

    print("\n1) Leer un traceback sin ocultar el tipo de excepción")
    try:
        # Si quitamos el try-except, Python mostraría un traceback completo.
        float("rojo")
    except ValueError as error:
        print(f"Python detectaría ValueError: {error}")
        print("Qué observar: la última línea indica el tipo y el mensaje.")

    print("\n2) try-except, else y finally")
    for entrada in ("72", "rojo", "-500"):
        procesar_temperatura(entrada)

    print("\n3) assert durante el desarrollo")
    print(f"Media correcta: {calcular_media([10, 20, 30]):.1f}")
    try:
        # El caso vacío permite ver AssertionError sin detener toda la clase.
        calcular_media([])
    except AssertionError as error:
        print(f"Aserción detectada: {error}")

    print("\nPregunta para el grupo:")
    print("¿Qué diferencia hay entre corregir un bug y tratar una")
    print("entrada externa que no cumple el formato esperado?")
    # Respuesta orientativa: corregir un bug significa modificar el programa
    # porque su lógica no produce el resultado esperado. Tratar una entrada
    # externa significa preparar el programa para comunicar o manejar un dato
    # incorrecto sin que se detenga de forma inesperada.


# %% U2.4 - Depuración de programas

# Referencias exactas de los apuntes:
# - Error lógico: https://revilofe.github.io/section1/u02/teoria/PROG-U2.4.-Depurar/#11-tipos-de-problemas
# - Proceso reproducible: https://revilofe.github.io/section1/u02/teoria/PROG-U2.4.-Depurar/#12-un-proceso-de-depuracion-reproducible
# - Herramientas, assert y pruebas: https://revilofe.github.io/section1/u02/teoria/PROG-U2.4.-Depurar/#2-herramientas-y-conceptos-del-depurador
# - breakpoint y pdb: https://revilofe.github.io/section1/u02/teoria/PROG-U2.4.-Depurar/#21-pdb-el-depurador-de-la-biblioteca-estandar
# - Puntos de interrupción: https://revilofe.github.io/section1/u02/teoria/PROG-U2.4.-Depurar/#32-puntos-de-interrupcion-y-estado-del-programa
# - Ejecución paso a paso: https://revilofe.github.io/section1/u02/teoria/PROG-U2.4.-Depurar/#33-ejecutar-paso-a-paso

# GUÍA PARA MOSTRAR U2.4 EN CLASE:
# 1. Ejecuta primero la celda `Preparación común` y, después, esta celda para
#    cargar las funciones de depuración.
# 2. Pide al grupo que indique qué resultado espera en estos casos:
#       temperatura_valida_con_error(-300)
#       temperatura_valida_con_error(20)
#       temperatura_valida_con_error(200)
# 3. Ejecuta la demostración escribiendo en la consola:
#       ejecutar_u24()
#    El resultado INCORRECTO muestra un error lógico: el programa funciona,
#    pero la condición con `or` no cumple lo que pide el problema.
# 4. Para detener la ejecución en breakpoint(), ejecuta:
#       ejecutar_u24(usar_breakpoint=True)
#    En la terminal también puedes usar:
#       python docs/section1/u02/teoria/otrosRecursos/PROG-U2.-ClasePractica2345.py 2.4 depurar
# 5. Cuando se detenga el depurador, consulta `celsius` y `resultado`. En pdb
#    puedes utilizar `p celsius`, `p resultado`, `n`, `c` y `q`.
# 6. Coloca después un punto de interrupción en el IDE sobre la línea de
#    `resultado = ...` y repite el caso 200 para observar el estado.
# 7. Finalmente compara `temperatura_valida_con_error` con `temperatura_valida`
#    y ejecuta las pruebas que aparecen al final de `ejecutar_u24()`.
# 8. Desde una terminal, sin detenerse en el breakpoint, ejecuta:
#       python docs/section1/u02/teoria/otrosRecursos/PROG-U2.-ClasePractica2345.py 2.4


def temperatura_valida_con_error(celsius: float) -> bool:
    """Versión con un error lógico intencionado para depurarla.

    Args:
        celsius (float): Temperatura que se quiere comprobar.

    Returns:
        bool: Resultado de la condición incorrecta; sirve para localizar el
            error lógico durante la depuración.
    """

    # ERROR INTENCIONADO: con or, casi cualquier valor resulta válido.
    # El programa se ejecuta, pero su resultado no cumple el problema.
    return celsius >= -273.15 or celsius <= 100


def temperatura_valida(celsius: float) -> bool:
    """Versión corregida: el valor debe cumplir los dos límites.

    Args:
        celsius (float): Temperatura que se quiere comprobar.

    Returns:
        bool: ``True`` si está entre -273,15 y 100 °C; ``False`` en otro caso.
    """

    # and exige que se cumplan simultáneamente el límite inferior y el superior.
    return celsius >= -273.15 and celsius <= 100


def observar_error(celsius: float, activar_breakpoint: bool = False) -> bool:
    """Permite observar variables antes de devolver el resultado incorrecto.

    Args:
        celsius (float): Temperatura que se quiere comprobar.
        activar_breakpoint (bool): Indica si se debe detener la ejecución en
            el punto de interrupción.

    Returns:
        bool: Resultado producido por la función con el error lógico.
    """

    # resultado es booleano porque solo puede valer True o False.
    resultado: bool = temperatura_valida_con_error(celsius)

    if activar_breakpoint:
        # En la terminal se pueden probar n, p celsius, p resultado, c y q.
        # En PyCharm o VS Code también se puede poner un breakpoint aquí.
        breakpoint()

    return resultado


def ejecutar_pruebas() -> None:
    """Comprueba la solución con casos normales y casos límite.

    Returns:
        None: Muestra un mensaje si todas las aserciones se superan.

    Raises:
        AssertionError: Si algún resultado no coincide con el esperado.
    """

    # Los resultados esperados se escriben antes de probar para poder comparar.
    # Cada caso es una pareja: (temperatura, resultado esperado).
    casos: list[tuple[float, bool]] = [
        (-300, False),    # Fuera por debajo.
        (-273.15, True),  # Límite inferior.
        (20, True),       # Caso normal.
        (100, True),      # Límite superior.
        (200, False),     # Fuera por arriba.
    ]

    for entrada, esperado in casos:
        obtenido: bool = temperatura_valida(entrada)
        assert obtenido == esperado, (
            f"Para {entrada} se esperaba {esperado}, se obtuvo {obtenido}."
        )

    print("Todas las pruebas han terminado correctamente.")


def ejecutar_u24(usar_breakpoint: bool = False) -> None:
    """Ejecuta una demostración básica del proceso de depuración.

    Args:
        usar_breakpoint (bool): Indica si se activa el punto de interrupción.

    Returns:
        None: Muestra por pantalla el proceso de depuración de U2.4.
    """

    mostrar_titulo("U2.4 - DEPURACIÓN DE PROGRAMAS")
    print("Objetivo: reproducir un fallo, formular una hipótesis,")
    print("observar variables, corregir el código y repetir las pruebas.")

    # Lista de parejas con una temperatura y el resultado que esperamos.
    casos: list[tuple[float, bool]] = [
        (-300, False),
        (20, True),
        (200, False),
    ]

    print("\n1) Reproducir el problema con datos conocidos")
    for entrada, esperado in casos:
        obtenido = temperatura_valida_con_error(entrada)
        resultado: str = "correcto" if obtenido == esperado else "INCORRECTO"
        # Usamos una salida sencilla para centrarnos en comparar resultados.
        print(entrada, "°C -> obtenido=", obtenido,
              ", esperado=", esperado, ":", resultado)

    print("\n2) Formular una hipótesis")
    print("La condición utiliza or cuando necesita comprobar dos límites")
    print("a la vez. Es un error lógico: no aparece ningún traceback.")

    print("\n3) Observar el estado")
    if usar_breakpoint:
        print("Se detendrá la ejecución en el breakpoint opcional.")
        observar_error(200, activar_breakpoint=True)
    else:
        print("Para detener la ejecución, ejecuta con el argumento depurar:")
        print("python PROG-U2.-ClasePractica2345.py 2.4 depurar")
        print("También puedes colocar un breakpoint en observar_error().")

    print("\n4) Corregir y verificar")
    ejecutar_pruebas()

    print("\nQué hemos utilizado:")
    print("- print(): observar rápidamente un valor.")
    print("- breakpoint(): detenerse e inspeccionar el estado.")
    print("- assert: comprobar resultados esperados durante el desarrollo.")
    print("- pruebas: repetir casos normales y casos límite.")


# %% U2.5 - Documentación del código

# Referencias exactas de los apuntes:
# - Comentarios: https://revilofe.github.io/section1/u02/teoria/PROG-U2.5.-Documentar/#21-comentarios-con
# - Comentarios útiles: https://revilofe.github.io/section1/u02/teoria/PROG-U2.5.-Documentar/#23-escribe-comentarios-que-aporten-informacion
# - Anotaciones de tipo: https://revilofe.github.io/section1/u02/teoria/PROG-U2.5.-Documentar/#25-las-anotaciones-de-tipo-tambien-comunican
# - Docstrings y __doc__: https://revilofe.github.io/section1/u02/teoria/PROG-U2.5.-Documentar/#31-que-es-una-docstring
# - Parámetros, retornos y excepciones: https://revilofe.github.io/section1/u02/teoria/PROG-U2.5.-Documentar/#33-docstrings-de-funciones-y-metodos
# - Formato Google Style: https://revilofe.github.io/section1/u02/teoria/PROG-U2.5.-Documentar/#41-elegir-un-formato-de-docstring
# - README mínimo: https://revilofe.github.io/section1/u02/teoria/PROG-U2.5.-Documentar/#424-un-readmemd-minimo

# GUÍA PARA MOSTRAR U2.5 EN CLASE:
# 1. Ejecuta primero la celda `Preparación común` y, después, esta celda para
#    cargar las funciones y poder consultar sus docstrings.
# 2. Revisa con el grupo la cabecera de `calcular_promedio`: los tipos indican
#    qué recibe (`list[float]`) y qué devuelve (`float`).
# 3. Consulta su documentación desde la consola con:
#       print(calcular_promedio.__doc__)
#       help(calcular_promedio)
# 4. Ejecuta la demostración completa con:
#       ejecutar_u25()
#    Detente en el apartado de comentarios y pide identificar cuál es
#    redundante y cuál explica una decisión.
# 5. Para mostrar también `help()`, ejecuta:
#       ejecutar_u25(mostrar_ayuda=True)
# 6. Pide al grupo que diferencie la información que debe estar en el código
#    (funcionamiento y decisiones) de la que debe estar en el README
#    (propósito, requisitos, uso y limitaciones).
# 7. Desde una terminal, la parte se ejecuta con:
#       python docs/section1/u02/teoria/otrosRecursos/PROG-U2.-ClasePractica2345.py 2.5
#    Para incluir help(), añade la opción `ayuda` al final del comando.


def calcular_promedio(temperaturas: list[float]) -> float:
    """Calcula el promedio de una lista de temperaturas.

    Args:
        temperaturas (list[float]): Lista de temperaturas en grados Celsius.

    Returns:
        float: Promedio de las temperaturas recibidas.

    Raises:
        ValueError: Si la lista está vacía.
    """

    if not temperaturas:
        raise ValueError("Debe haber al menos una temperatura.")
    return sum(temperaturas) / len(temperaturas)


def clasificar_temperatura(celsius: float) -> str:
    """Clasifica una temperatura usando varios intervalos.

    Args:
        celsius (float): Temperatura en grados Celsius.

    Returns:
        str: Categoría textual: ``fría``, ``templada``, ``cálida`` o
            ``calurosa``.
    """

    if celsius < 0:
        return "fría"
    elif celsius <= 20:
        return "templada"
    elif celsius <= 30:
        return "cálida"
    else:
        return "calurosa"


def es_temperatura_extrema(celsius: float) -> bool:
    """Indica si la temperatura es inferior a -10 o superior a 40 °C.

    Args:
        celsius (float): Temperatura que se quiere comprobar.

    Returns:
        bool: ``True`` si la temperatura es extrema; ``False`` en otro caso.
    """

    return celsius < -10 or celsius > 40


def mostrar_informe(temperaturas: list[float]) -> None:
    """Muestra un informe sencillo para la lista recibida.

    Args:
        temperaturas (list[float]): Temperaturas en grados Celsius.

    Returns:
        None: Muestra el promedio y la clasificación de cada temperatura.
    """

    promedio: float = calcular_promedio(temperaturas)
    print(f"Promedio: {promedio:.2f} °C")

    for temperatura in temperaturas:
        categoria: str = clasificar_temperatura(temperatura)
        extrema: bool = es_temperatura_extrema(temperatura)
        print(f"{temperatura:.1f} °C: {categoria}; extrema: {extrema}")


def ejecutar_u25(mostrar_ayuda: bool = False) -> None:
    """Ejecuta una demostración básica de comentarios y documentación.

    Args:
        mostrar_ayuda (bool): Indica si también se ejecuta ``help()``.

    Returns:
        None: Muestra por pantalla los ejemplos de documentación de U2.5.
    """

    mostrar_titulo("U2.5 - DOCUMENTACIÓN DEL CÓDIGO")
    print("Objetivo: explicar qué hace el código y por qué toma sus decisiones.")

    print("\n1) Comentario redundante frente a comentario útil")
    # contador es un número entero: tipo int.
    contador: int = 0
    contador += 1  # Redundante: la instrucción ya explica qué ocurre.

    # Útil: explica una decisión que no se deduce de la instrucción.
    # El contador empieza en cero porque todavía no se ha procesado ningún dato.
    contador += 1
    print(f"Contador: {contador}")
    print("Regla: comenta el porqué, no repitas el qué.")

    print("\n2) Docstrings")
    print("Documentación de calcular_promedio:")
    print(calcular_promedio.__doc__)
    print("La documentación está junto a la función y se puede consultar con")
    print("help(calcular_promedio) desde la consola Python.")

    if mostrar_ayuda:
        # help() es una herramienta de consulta, no una parte necesaria del
        # cálculo. Se activa solo cuando queremos enseñar su funcionamiento.
        help(calcular_promedio)
    else:
        print("Para mostrar help(), ejecuta el fichero con el argumento ayuda.")

    print("\n3) El programa debe explicar su uso")
    print("Un README básico debe incluir:")
    print("- propósito del programa;")
    print("- requisitos y forma de ejecución;")
    print("- ejemplo de uso y salida;")
    print("- limitaciones y decisiones importantes.")
    print("Desde la terminal también se puede consultar pydoc con:")
    print("python -m pydoc nombre_del_fichero")

    print("\n4) Ejecutar el código documentado")
    mostrar_informe([-2, 18.5, 36])
    print("\nPregunta para el grupo:")
    print("¿Qué explicación pertenece al código y cuál pertenece al README?")
    # Respuesta orientativa: el código debe explicar lo necesario para entender
    # su funcionamiento y sus decisiones. El README debe explicar el propósito
    # del proyecto, sus requisitos, cómo se ejecuta y sus limitaciones.


def ejecutar_parte(parte: str, opcion: str = "") -> None:
    """Ejecuta una parte desde la terminal sin introducir conceptos nuevos.

    Args:
        parte (str): Parte que se ejecutará: ``2.3``, ``2.4``, ``2.5`` o
            ``todas``.
        opcion (str): Opción adicional: ``depurar`` o ``ayuda``.

    Returns:
        None: Ejecuta la parte seleccionada y muestra su resultado.
    """

    if parte == "2.3":
        ejecutar_u23()
    elif parte == "2.4":
        ejecutar_u24(usar_breakpoint=opcion == "depurar")
    elif parte == "2.5":
        ejecutar_u25(mostrar_ayuda=opcion == "ayuda")
    else:
        ejecutar_u23()
        ejecutar_u24()
        ejecutar_u25()


if __name__ == "__main__":
    # Este pequeño selector solo permite elegir una parte desde la terminal.
    # No es un concepto que haya que explicar al alumnado.
    parte: str = sys.argv[1] if len(sys.argv) > 1 else "todas"
    opcion: str = sys.argv[2] if len(sys.argv) > 2 else ""
    ejecutar_parte(parte, opcion)
