Null translations of new 2.1 beta 3 content. (#71)

Author: microbit-matt-hillsdon

lang/es-es/typeshed/stdlib/audio.pyi

@@ -7,4 +7,5 @@ from .microbit.audio import (
     play as play,
     stop as stop,
     AudioFrame as AudioFrame,
+    SoundEffect as SoundEffect,
 )

lang/es-es/typeshed/stdlib/log.pyi

@@ -11,40 +11,42 @@ HOURS = 36000
 DAYS = 864000
 """Formato de marca temporal en días. (días)"""
 
-def set_labels(*args: str, timestamp: Optional[Literal[1, 10, 36000, 864000]]=SECONDS) -> None:
+def set_labels(*labels: str, timestamp: Optional[Literal[1, 10, 36000, 864000]]=SECONDS) -> None:
     """Configura la cabecera del archivo de registro. (configurar etiquetas)
 
-Example: ``log.set_labels('x', 'y', 'z', timestamp=log.MINUTES)``
+Example: ``log.set_labels('X', 'Y', 'Z', timestamp=log.MINUTES)``
 
-Each call to this function with positional arguments will generate a new
-header entry into the log file.
+Ideally this function should be called a single time, before any data is
+logged, to configure the data table header once.
 
-If the program starts and a log file already exists it will compare the
-labels set up by this function call to the last headers declared in the
-file. If the headers are different it will add a new header entry at the
-end of the file.
+If a log file already exists when the program starts, or if this function
+is called multiple times, it will check the labels already defined in the
+log file. If this function call contains any new labels not already
+present, it will generate a new header row with the additional columns.
 
-:param *args: Un argumento posicional para cada cabecera de registro.
-:param timestamp: (marca de tiempo) La unidad de marca temporal que se añadirá automáticamente como la primera columna en cada fila.
-Establecer este argumento a ``None`` desactiva la marca temporal. Se le pueden pasar los valores ``log.MILLISECONDS``, ``log.SECONDS``, ``log.MINUTES``, ``log.HOURS`` o ``log.DAYS`` definidos en este módulo. Un valor no válido lanzará una excepción."""
+By default the first column contains a timestamp for each row. The time
+unit can be selected via the timestamp argument.
+
+:param *labels: Any number of positional arguments, each corresponding to an entry in the log header.
+:param timestamp: (marca de tiempo) Select the timestamp unit that will be automatically added as the first column in every row. Timestamp values can be one of ``log.MILLISECONDS``, ``log.SECONDS``, ``log.MINUTES``, ``log.HOURS``, ``log.DAYS`` or ``None`` to disable the timestamp. The default value is ``log.SECONDS``."""
     ...
 
 @overload
-def add(log_data: Optional[dict[str, Union[str, int, float]]]) -> None:
+def add(data_dictionary: Optional[dict[str, Union[str, int, float]]]) -> None:
     """Añade una fila de datos al registro pasando un diccionario de cabeceras y valores. (añadir)
 
 Example: ``log.add({ 'temp': temperature() })``
 
 Each call to this function adds a row to the log.
 
-Dictionary keys not already specified via the ``set_labels`` function,
-or by a previous call to this function, will trigger a new header
-entry to be added to the log with the extra label.
+New labels not previously specified via the set_labels function, or by a
+previous call to this function, will trigger a new header entry to be added
+to the log with the extra labels.
 
-Labels previously specified and not present in this function call will be
-skipped with an empty value in the log row.
+Labels previously specified and not present in a call to this function will
+be skipped with an empty value in the log row.
 
-:param log_data: (registrar datos) Los datos a registrar como un diccionario con una clave para cada cabecera."""
+:param data_dictionary: The data to log as a dictionary with a key for each header."""
     ...
 
 @overload
@@ -55,32 +57,33 @@ Example: ``log.add(temp=temperature())``
 
 Each call to this function adds a row to the log.
 
-Keyword arguments not already specified via the ``set_labels`` function,
-or by a previous call to this function, will trigger a new header entry
-to be added to the log with the extra label.
+New labels not previously specified via the set_labels function, or by a
+previous call to this function, will trigger a new header entry to be added
+to the log with the extra labels.
 
-Labels previously specified and not present in this function call will be
-skipped with an empty value in the log row."""
+Labels previously specified and not present in a call to this function will
+be skipped with an empty value in the log row."""
     ...
 
 def delete(full=False):
     """Elimina el contenido del registro, incluyendo las cabeceras. (eliminar)
 
 Example: ``log.delete()``
 
-To add the log headers the ``set_labels`` function has to be called again
-after this.
+To add the log headers again the ``set_labels`` function should to be called after this function.
+
+There are two erase modes; “full” completely removes the data from the physical storage,
+and “fast” invalidates the data without removing it.
 
-:param full: (completo) Selecciona un formato de borrado "completo" que elimina los datos del almacenamiento flash.
-Si se pone a ``False`` (falso), usa un método "rápido" que invalida los datos en lugar de realizar un borrado completo más lento."""
+:param full: (completo) ``True`` selects a “full” erase and ``False`` selects the “fast” erase method."""
     ...
 
 def set_mirroring(serial: bool):
-    """Replica la actividad del registro de datos en la salida serie. (configurar replicación)
+    """Configure mirroring of the data logging activity to the serial output. (configurar replicación)
 
 Example: ``log.set_mirroring(True)``
 
-Mirroring is disabled by default.
+Serial mirroring is disabled by default. When enabled, it will print to serial each row logged into the log file.
 
-:param serial: (serie) Si se le pasa ``True`` (verdadero), replicará la actividad del registro de datos en la salida serie; si se le pasa ``False`` (falso), se desactivará la replicación."""
+:param serial: (serie) ``True`` enables mirroring data to the serial output."""
     ...

lang/es-es/typeshed/stdlib/microbit/__init__.pyi

@@ -1,39 +1,47 @@
 """Pines, imágenes, sonidos, temperatura y volumen."""
+from typing import Any, Callable, List, Optional, Tuple, overload
 from _typeshed import ReadableBuffer
-from typing import Any, Callable, List, Optional, overload
 from . import accelerometer as accelerometer
+from . import audio as audio
 from . import compass as compass
 from . import display as display
 from . import i2c as i2c
 from . import microphone as microphone
 from . import speaker as speaker
 from . import spi as spi
 from . import uart as uart
-from . import audio as audio
 
 def run_every(callback: Optional[Callable[[], None]]=None, days: int=0, h: int=0, min: int=0, s: int=0, ms: int=0) -> Callable[[Callable[[], None]], Callable[[], None]]:
-    """Programa una función para llamarla en un intervalo dado **solo V2**. (ejecutar cada)
+    """Schedule to run a function at the interval specified by the time arguments **V2 only**. (ejecutar cada)
 
 Example: ``run_every(my_logging, min=5)``
 
-This function can be passed a callback::
-
-    run_every(your_function, h=1, min=20, s=30, ms=50)
+``run_every`` can be used in two ways:
 
-or used as a decorator::
+As a Decorator - placed on top of the function to schedule. For example::
 
     @run_every(h=1, min=20, s=30, ms=50)
-    def your_function():
-        pass
+    def my_function():
+        # Do something here
+
+As a Function - passing the callback as a positional argument. For example::
+
+    def my_function():
+        # Do something here
+    run_every(my_function, s=30)
+
+Each argument corresponds to a different time unit and they are additive.
+So ``run_every(min=1, s=30)`` schedules the callback every minute and a half.
 
-Arguments with different time units are additive.
+When an exception is thrown inside the callback function it deschedules the
+function. To avoid this you can catch exceptions with ``try/except``.
 
-:param callback: La función "callback" (devolución de llamada) que se llama; omitir si se usa en un patrón "Decorator"
-:param days: (días) El intervalo en días.
-:param h: El intervalo en horas.
-:param min: El intervalo en minutos.
-:param s: El intervalo en segundos.
-:param ms: El intervalo en milisegundos."""
+:param callback: Function to call at the provided interval. Omit when using as a decorator.
+:param days: (días) Sets the day mark for the scheduling.
+:param h: Sets the hour mark for the scheduling.
+:param min: Sets the minute mark for the scheduling.
+:param s: Sets the second mark for the scheduling.
+:param ms: Sets the millisecond mark for the scheduling."""
 
 def panic(n: int) -> None:
     """Entra en modo pánico (pánico)
@@ -47,6 +55,20 @@ Requires restart."""
 def reset() -> None:
     """Reiniciar la placa. (restablecer)"""
 
+def scale(value: float, from_: Tuple[float, float], to: Tuple[float, float]) -> float:
+    """Converts a value from a range to another range.
+
+Example: ``temp_fahrenheit = scale(30, from_=(0, 100), to=(32, 212))``
+
+This can be useful to convert values between inputs and outputs, for example an accelerometer X value to a speaker volume.
+
+Negative scaling is also supported, for example ``scale(25, from_=(0, 100), to=(0, -200))`` will return ``-50``.
+
+:param value: (valor) A number to convert.
+:param from_: A tuple to define the range to convert from.
+:param to: A tuple to define the range to convert to.
+:return: The ``value`` converted to the ``to`` range."""
+
 def sleep(n: float) -> None:
     """Espera ``n`` milisegundos. (dormir)
 
@@ -412,6 +434,8 @@ Given an image object it's possible to display it via the ``display`` API::
     """Imagen de un paraguas. (paraguas)"""
     SNAKE: Image
     """Imagen de una serpiente. (serpiente)"""
+    SCISSORS: Image
+    """Scissors image."""
     ALL_CLOCKS: List[Image]
     """Una lista que contiene todas las imágenes CLOCK_ en secuencia. (todos los relojes)"""
     ALL_ARROWS: List[Image]

lang/es-es/typeshed/stdlib/microbit/accelerometer.pyi

@@ -33,6 +33,14 @@ Example: ``x, y, z = accelerometer.get_values()``
 :return: a three-element tuple of integers ordered as X, Y, Z, each value a positive or negative integer depending on direction in the range +/- 2000mg"""
     ...
 
+def get_strength() -> int:
+    """Get the acceleration measurement of all axes combined, as a positive integer. This is the Pythagorean sum of the X, Y and Z axes.
+
+Example: ``accelerometer.get_strength()``
+
+:return: The combined acceleration strength of all the axes, in milli-g."""
+    ...
+
 def current_gesture() -> str:
     """Obtiene el nombre del gesto actual. (gesto actual)
 
@@ -85,4 +93,11 @@ calls to some accelerometer method to do the gesture detection. Usually
 gestures can be detected using a loop with a small :func:`microbit.sleep` delay.
 
 :return: The history as a tuple, most recent last."""
-    ...
+    ...
+
+def set_range(value: int) -> None:
+    """Set the accelerometer sensitivity range, in g (standard gravity), to the closest values supported by the hardware, so it rounds to either ``2``, ``4``, or ``8`` g.
+
+Example: ``accelerometer.set_range(8)``
+
+:param value: (valor) New range for the accelerometer, an integer in ``g``."""

lang/es-es/typeshed/stdlib/microbit/audio.pyi

@@ -1,13 +1,13 @@
 """Reproducir sonidos usando el micro:bit (importar ``audio`` para compatibilidad con V1)."""
 from ..microbit import MicroBitDigitalPin, Sound, pin0
-from typing import Iterable, Union
+from typing import ClassVar, Iterable, Union
 
-def play(source: Union[Iterable[AudioFrame], Sound], wait: bool=True, pin: MicroBitDigitalPin=pin0, return_pin: Union[MicroBitDigitalPin, None]=None) -> None:
-    """Reproduce un sonido predefinido o pistas de audio personalizadas. (reproducir)
+def play(source: Union[Iterable[AudioFrame], Sound, SoundEffect], wait: bool=True, pin: MicroBitDigitalPin=pin0, return_pin: Union[MicroBitDigitalPin, None]=None) -> None:
+    """Play a built-in sound, sound effect or custom audio frames. (reproducir)
 
 Example: ``audio.play(Sound.GIGGLE)``
 
-:param source: (origen) Un ``Sound`` predefinido como ``Sound.GIGGLE`` o datos de muestra como un iterable de objetos ``AudioFrame``.
+:param source: (origen) A built-in ``Sound`` such as ``Sound.GIGGLE``, a ``SoundEffect`` or sample data as an iterable of ``AudioFrame`` objects.
 :param wait: (esperar) Si ``wait`` es ``True`` (verdadero), la función se bloqueará hasta que el sonido finalice.
 :param pin: Se puede usar un argumento opcional para especificar el pin de salida, reemplazando el valor predeterminado de ``pin0``. Si no queremos que se reproduzca ningún sonido, podemos usar ``pin=None``.
 :param return_pin: (devolver pin) Especifica un pin de conector de borde diferencial para conectarse a un altavoz externo en lugar de tierra. Esto se ignora para la revisión **V2**."""
@@ -26,6 +26,75 @@ def stop() -> None:
 Example: ``audio.stop()``"""
     ...
 
+class SoundEffect:
+    """A sound effect, composed by a set of parameters configured via the constructor or attributes."""
+    WAVEFORM_SINE: ClassVar[int]
+    """Sine wave option used for the ``waveform`` parameter."""
+    WAVEFORM_SAWTOOTH: ClassVar[int]
+    """Sawtooth wave option used for the ``waveform`` parameter."""
+    WAVEFORM_TRIANGLE: ClassVar[int]
+    """Triangle wave option used for the ``waveform`` parameter."""
+    WAVEFORM_SQUARE: ClassVar[int]
+    """Square wave option used for the ``waveform`` parameter."""
+    WAVEFORM_NOISE: ClassVar[int]
+    """Noise option used for the ``waveform`` parameter."""
+    SHAPE_LINEAR: ClassVar[int]
+    """Linear interpolation option used for the ``shape`` parameter."""
+    SHAPE_CURVE: ClassVar[int]
+    """Curve interpolation option used for the ``shape`` parameter."""
+    SHAPE_LOG: ClassVar[int]
+    """Logarithmic interpolation option used for the ``shape`` parameter."""
+    FX_NONE: ClassVar[int]
+    """No effect option used for the ``fx`` parameter."""
+    FX_TREMOLO: ClassVar[int]
+    """Tremelo effect option used for the ``fx`` parameter."""
+    FX_VIBRATO: ClassVar[int]
+    """Vibrato effect option used for the ``fx`` parameter."""
+    FX_WARBLE: ClassVar[int]
+    """Warble effect option used for the ``fx`` parameter."""
+    freq_start: int
+    """Start frequency in Hertz (Hz), a number between ``0`` and ``9999``"""
+    freq_end: int
+    """End frequency in Hertz (Hz), a number between ``0`` and ``9999``"""
+    duration: int
+    """Duration of the sound in milliseconds, a number between ``0`` and ``9999`` (duración)"""
+    vol_start: int
+    """Start volume value, a number between ``0`` and ``255``"""
+    vol_end: int
+    """End volume value, a number between ``0`` and ``255``"""
+    waveform: int
+    """Type of waveform shape, one of these values: ``WAVEFORM_SINE``, ``WAVEFORM_SAWTOOTH``, ``WAVEFORM_TRIANGLE``, ``WAVEFORM_SQUARE``, ``WAVEFORM_NOISE`` (randomly generated noise)"""
+    fx: int
+    """Effect to add on the sound, one of the following values: ``FX_TREMOLO``, ``FX_VIBRATO``, ``FX_WARBLE``, or ``FX_NONE``"""
+    shape: int
+    """The type of the interpolation curve between the start and end frequencies, different wave shapes have different rates of change in frequency. One of the following values: ``SHAPE_LINEAR``, ``SHAPE_CURVE``, ``SHAPE_LOG``"""
+
+    def __init__(self, freq_start: int=500, freq_end: int=2500, duration: int=500, vol_start: int=255, vol_end: int=0, waveform: int=WAVEFORM_SQUARE, fx: int=FX_NONE, shape: int=SHAPE_LOG):
+        """Create a new sound effect.
+
+Example: ``my_effect = SoundEffect(duration=1000)``
+
+All the parameters are optional, with default values as shown above, and
+they can all be modified via attributes of the same name. For example, we
+can first create an effect ``my_effect = SoundEffect(duration=1000)``,
+and then change its attributes ``my_effect.duration = 500``.
+
+:param freq_start: Start frequency in Hertz (Hz), a number between ``0`` and ``9999``.
+:param freq_end: End frequency in Hertz (Hz), a number between ``0`` and ``9999``.
+:param duration: (duración) Duration of the sound in milliseconds, a number between ``0`` and ``9999``.
+:param vol_start: Start volume value, a number between ``0`` and ``255``.
+:param vol_end: End volume value, a number between ``0`` and ``255``.
+:param waveform: Type of waveform shape, one of these values: ``WAVEFORM_SINE``, ``WAVEFORM_SAWTOOTH``, ``WAVEFORM_TRIANGLE``, ``WAVEFORM_SQUARE``, ``WAVEFORM_NOISE`` (randomly generated noise).
+:param fx: Effect to add on the sound, one of the following values: ``FX_TREMOLO``, ``FX_VIBRATO``, ``FX_WARBLE``, or ``FX_NONE``.
+:param shape: The type of the interpolation curve between the start and end frequencies, different wave shapes have different rates of change in frequency. One of the following values: ``SHAPE_LINEAR``, ``SHAPE_CURVE``, ``SHAPE_LOG``."""
+
+    def copy(self) -> SoundEffect:
+        """Create a copy of this ``SoundEffect``. (copiar)
+
+Example: ``sound_2 = sound_1.copy()``
+
+:return: A copy of the SoundEffect."""
+
 class AudioFrame:
     """Un objeto ``AudioFrame`` es una lista de 32 muestras, cada una de las cuales es un byte
 sin signo (número entero entre 0 y 255).
@@ -38,6 +107,13 @@ Example::
     for i in range(len(frame)):
         frame[i] = 252 - i * 8"""
 
+    def copyfrom(self, other: AudioFrame) -> None:
+        """Overwrite the data in this ``AudioFrame`` with the data from another ``AudioFrame`` instance.
+
+Example: ``my_frame.copyfrom(source_frame)``
+
+:param other: (otro) ``AudioFrame`` instance from which to copy the data."""
+
     def __len__(self) -> int:
         ...
 

lang/es-es/typeshed/stdlib/power.pyi

@@ -0,0 +1,48 @@
+"""Manage the power modes of the micro:bit (V2 only).
+"""
+
+from microbit import MicroBitDigitalPin, Button
+from typing import Optional, Tuple, Union
+
+def off() -> None:
+    """Power down the board to the lowest possible power mode.
+
+    Example: ``power.off()``
+
+    This is the equivalent to pressing the reset button for a few seconds,
+    to set the board in "Off mode".
+
+    The micro:bit will only wake up if the reset button is pressed or,
+    if on battery power, when a USB cable is connected.
+
+    When the board wakes up it will start for a reset state, so your program
+    will start running from the beginning.
+    """
+    ...
+
+def deep_sleep(
+    ms: Optional[int] = None,
+    wake_on: Optional[
+        Union[MicroBitDigitalPin, Button] | Tuple[MicroBitDigitalPin | Button, ...]
+    ] = None,
+    run_every: bool = True,
+) -> None:
+    """Set the micro:bit into a low power mode where it can wake up and continue operation.
+
+    Example: ``power.deep_sleep(wake_on=(button_a, button_b))``
+
+    The program state is preserved and when it wakes up it will resume operation where it left off.
+
+    Deep Sleep mode will consume more battery power than Off mode.
+
+    The wake up sources are configured via arguments.
+
+    If no wake up sources have been configured it will sleep until the reset button is pressed (which resets the Target MCU) or, in battery power, when the USB cable is inserted.
+
+    When the ``run_every`` parameter is set to ``True`` (the default), any function scheduled with ``microbit.run_every`` will still run while the board sleeps. When the scheduled time is reached the micro:bit will momentarily wake up to run the scheduled function and then automatically go back to sleep.
+
+    :param ms: A time in milliseconds to wait before it wakes up.
+    :param wake_on: A single instance or a tuple of pins and/or buttons to wake up the board, e.g. ``deep_sleep(wake_on=button_a)`` or ``deep_sleep(wake_on=(pin0, pin2, button_b))``.
+    :param run_every: A boolean to configure if the functions scheduled with ``microbit.run_every`` will continue to run while it sleeps.
+    """
+    ...