# Comprobación de tipos

> Una página de la documentación de phonometry, en Markdown. Índice: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/es/start/environments/type-checking/
Language: es
Alternate: https://docs.jmrp.io/phonometry/start/environments/type-checking/index.md
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Unreleased: esta página cambió después de phonometry 4.0.0, la última versión publicada en PyPI, así que puede describir código que esa versión aún no tiene; lo nuevo desde entonces figura en Unreleased en https://github.com/jmrplens/phonometry/blob/main/CHANGELOG.md#unreleased
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-11-11
Updated: 2026-11-18T01:01:07Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Comprueba con mypy o pyright los tipos del código que usa phonometry: el wheel trae py.typed, se comprueban opciones y números y los campos FDTD son Any.

---

phonometry trae sus tipos dentro del wheel, con la marca `py.typed` que le
indica a un comprobador de tipos que los lea, así que
[mypy](https://mypy.readthedocs.io/en/stable/) y
[pyright](https://microsoft.github.io/pyright/) comprueban una llamada a la
biblioteca sin instalar nada más. Cada módulo público declara lo que publica,
y los dominios perezosos de `import phonometry as ph` los ve tanto el
comprobador como la ejecución. Los tipos que lee un comprobador son los que la
[referencia de la API](https://docs.jmrp.io/phonometry/es/reference/api/) imprime en cada firma.

Comprobado el 17 de noviembre de 2026 con phonometry 4.0.0 de PyPI, en las
imágenes `python:3.12-slim` y `python:3.14-slim`, con Python 3.12.16 y 3.14.10
y NumPy 2.5.5: mypy 2.4.1 y pyright 1.1.414.

## Un script en los modos estrictos

```python
import numpy as np

from phonometry import filters, io, signals, simulation

fs = 48000
x = 0.1 * np.sin(2 * np.pi * 1000.0 * np.arange(fs) / fs)

bands = filters.octave_filter(x, fs, fraction=3)
levels = bands.require_levels()          # un array, donde bands.levels puede ser None

recording = io.Signal(x, fs)
weighted = filters.WeightingFilter(fs, "A").filter(recording)   # entra un Signal, sale un Signal
level = float(signals.leq(weighted))      # leq devuelve un float, o un array si hay varios canales
print(f"Leq = {level:.1f} dB en {levels.size} bandas")

engine = simulation.FDTD2D(c=343.0, dx=0.01, shape=(64, 64))
pressure = engine.numpy_field("p")       # un array de NumPy; engine.p es el del propio dispositivo
print(pressure.shape)
```

`mypy --strict` y pyright, en su modo básico y en su modo estricto, no
señalan nada en este script, en Python 3.12 a 3.14 y con cualquier NumPy que
la biblioteca acepte en ellos, desde NumPy 2.0.2 en Python 3.12 hasta el más
reciente. Antes de NumPy 2.3, `np.ndarray` y los tipos escalares abstractos
como `np.floating` no tienen argumentos de tipo por defecto, y un comprobador
lee como parcialmente desconocido uno escrito solo; phonometry escribe el
dtype de cada array que anota (`NDArray[np.float64]`), así que un comprobador
lee sus tipos igual con cualquier NumPy.

## Qué detecta un comprobador

Un texto donde la biblioteca espera números, una opción fuera de las que
acepta un parámetro, una escritura en una tabla publicada y un campo que una
fila de catálogo no tiene se rechazan antes de ejecutar el código. En
`wrong.py`:

```py
from phonometry import filters, materials, signals

signals.leq("not a signal")
filters.WeightingFilter(48000, "Q")
row = next(iter(materials.PUBLISHED_ABSORPTION.values()))
materials.PUBLISHED_ABSORPTION["mine"] = row
print(row.density)
```

`mypy wrong.py` dice:

```text
wrong.py:3: error: Argument 1 to "leq" has incompatible type "str"; expected "Signal | complex | NestedSequence[complex] | SupportsNumericArray | NestedSequence[SupportsNumericArray]"  [arg-type]
wrong.py:4: error: Argument 2 to "WeightingFilter" has incompatible type "Literal['Q']"; expected "Literal['A', 'C', 'B', 'D', 'G', 'AU', '468', 'Z']"  [arg-type]
wrong.py:6: error: Unsupported target for indexed assignment ("Mapping[str, AbsorptionSpectrum]")  [index]
wrong.py:7: error: "AbsorptionSpectrum" has no attribute "density"  [attr-defined]
Found 4 errors in 1 file (checked 1 source file)
```

y pyright rechaza las mismas cuatro líneas.

## Donde el tipo es más amplio que el valor

- **Un campo que puede faltar.** `bands.levels` es `None` en una llamada que
  no pidió niveles, así que su tipo dice `np.ndarray | None`; el
  `require_levels()` del resultado devuelve el array, o lanza un ValueError
  que explica por qué no lo hay. `require_bands()` hace lo mismo con las
  señales de cada banda.
- **El tipo que devuelve un filtro.** `WeightingFilter.filter()` y
  `ParametricEQ.filter()` devuelven un `Signal` para un `Signal` y un array
  para un array, y el comprobador ve cuál.
- **Los campos de las simulaciones FDTD.** `engine.p`, `engine.vx` y los
  demás campos que avanza un motor FDTD son arrays de la biblioteca con la que
  calcula: un array de NumPy, uno de CuPy o un tensor de PyTorch. Un
  comprobador los lee como `Any`. `engine.numpy_field("p")` devuelve una
  copia de NumPy en cualquier dispositivo, con su tipo.
- **Los argumentos de palabra clave de una figura.** `.plot()` pasa a
  matplotlib los argumentos de palabra clave que no toma él mismo, con tipo
  `Any`, así que un comprobador deja pasar uno mal escrito como
  `bands.plot(colour="red")`, que matplotlib rechaza con un AttributeError
  cuando se ejecuta la línea.

## Completitud

`pyright --verifytypes phonometry --ignoreexternal` lee el paquete instalado
como lo hace el comprobador de un usuario y le da un 100 % con cualquier
NumPy que la biblioteca acepte, desde NumPy 2.0.2 en Python 3.12 hasta el más
reciente: cada símbolo que exporta el paquete tiene un tipo conocido. La CI
del repositorio ejecuta la misma orden sobre el wheel construido con el NumPy
más reciente, y sobre el paquete instalado con las versiones más antiguas que
acepta cada Python, y falla por debajo del 100 %.
