Metadata-Version: 2.4
Name: pycondicionals
Version: 9.3.0
Summary: Librería de validación, persistencia y control de estado.
Author: Isaac Tamayo Garcia
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: googletrans>=4.0.0rc1
Requires-Dist: groq>=1.7.0
Requires-Dist: gTTS>=2.5.4
Requires-Dist: pygame>=2.6.1
Requires-Dist: sounddevice>=0.5.6
Requires-Dist: speechrecognition>=3.17.0
Dynamic: license-file

# 🐍 PyCondicionals 9.2.0 — Guía de uso de la API

Una referencia para saber **cómo usar cada función, clase y método público** de PyCondicionals.

## 📦 Instalación

```bash
pip install pycondicionals
```

```python
import pycondicionals
print(pycondicionals.__version__)
```

---
## 🗺️ Índice

- 🔢 Operaciones, comprobaciones y utilidades matemáticas. → [`Arithmetic.py`](#arithmetic)
- 🧠 Clases para lógica, temporizadores, estados, persistencia y control de flujo. → [`Class_logic.py`](#class_logic)
- ⏱️ Utilidades relacionadas con tiempo y ejecución programada. → [`Clock.py`](#clock)
- 🔍 Validaciones y comprobaciones sobre cadenas y valores. → [`Comparison_tools.py`](#comparison_tools)
- 🔀 Condiciones, colecciones, diccionarios, archivos y correo. → [`Conditionals.py`](#conditionals)
- 🌐 Servidores y clientes TCP mediante sockets. → [`Connections.py`](#connections)
- 📐 Distancias, posiciones, colisiones y objetos de consola. → [`Geometry.py`](#geometry)
- 🤖 Agente de aprendizaje y cliente sencillo para Groq. → [`IA.py`](#ia)
- 🎵 Reproducción de audio mediante pygame. → [`Music.py`](#music)
- 📨 Envío de información mediante la función PQRSF del proyecto. → [`PQRSF.py`](#pqrsf)
- 🛡️ Validadores de JSON, IP, email y contraseñas. → [`Verifiers.py`](#verifiers)
- 🎤 Reconocimiento y síntesis de voz. → [`Voice.py`](#voice)

---
## 🔢 Operaciones, comprobaciones y utilidades matemáticas. — `Arithmetic.py`

### 🔹 `between(valor: Any, minimo: Any, maximo: Any, inclusivo: bool=True)`

Verifica si un valor se encuentra dentro de un rango determinado de forma numerica.

**Parámetros**

- `valor` — `Any`
- `minimo` — `Any`
- `maximo` — `Any`
- `inclusivo` — `bool` (por defecto: `True`)

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import between
print(between(7, 1, 10))  # True
```


### 🔹 `chance(porcentaje_exito: Any)`

Simula una probabilidad de exito aleatoria basada en un porcentaje dado.

**Parámetros**

- `porcentaje_exito` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import chance
if chance(25):
    print('¡Ocurrió el evento!')
```


### 🔹 `is_prime(n: Any)`

Determina si un numero dado es primo mediante calculo optimizado de raiz cuadrada.

**Parámetros**

- `n` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_prime
print(is_prime(17))  # True
```


### 🔹 `is_multiple(valor: Any, divisor: Any)`

Comprueba si un valor numerico es multiplo exacto de un divisor dado mediante modulo flotante.

**Parámetros**

- `valor` — `Any`
- `divisor` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_multiple
print(is_multiple(12, 3))  # True
```


### 🔹 `is_negative(valor: Any)`

Verifica si un valor numerico es estrictamente menor que cero.

**Parámetros**

- `valor` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_negative
print(is_negative(-5))  # True
```


### 🔹 `is_even(valor: Any)`

Determina si un numero entero es par.

**Parámetros**

- `valor` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_even
print(is_even(8))  # True
```


### 🔹 `is_odd(valor: Any)`

Determina si un numero entero es impar.

**Parámetros**

- `valor` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_odd
print(is_odd(9))  # True
```


### 🔹 `is_percent(valor: Any)`

Valida si un valor se encuentra estrictamente dentro del rango porcentual valido de 0 a 100.

**Parámetros**

- `valor` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_percent
print(is_percent(75))  # True
```


### 🔹 `is_perfect_square(numero: Any)`

Comprueba si un numero entero es un cuadrado perfecto utilizando funciones nativas seguras.

**Parámetros**

- `numero` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_perfect_square
print(is_perfect_square(49))  # True
```


### 🔹 `is_percentage_drop(valor_inicial: Any, valor_actual: Any, porcentaje_limite: Any)`

Evalua si la caida porcentual desde un valor inicial hasta uno actual supera un limite establecido.

**Parámetros**

- `valor_inicial` — `Any`
- `valor_actual` — `Any`
- `porcentaje_limite` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_percentage_drop
print(is_percentage_drop(100, 80, 20))  # True
```


### 🔹 `is_in_tolerance(valor_medido: Any, valor_esperado: Any, tolerance_porcentaje: Any)`

Comprueba si un valor medido se encuentra dentro del margen de tolerancia porcentual respecto a un valor esperado.

**Parámetros**

- `valor_medido` — `Any`
- `valor_esperado` — `Any`
- `tolerance_porcentaje` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_in_tolerance
print(is_in_tolerance(10.1, 10, 2))  # True
```


### 🔹 `clamp(valor: Any, minimo: Any, maximo: Any)`

Restringe un valor para que se mantenga confinado dentro de un rango especifico delimitado por minimo y maximo.

**Parámetros**

- `valor` — `Any`
- `minimo` — `Any`
- `maximo` — `Any`

**Retorno:** `Any`.

**💻 Ejemplo práctico**

```python
from pycondicionals import clamp
print(clamp(150, 0, 100))  # 100
```


### 🔹 `lerp(inicio: Any, fin: Any, factor: Any)`

Realiza una interpolacion lineal suave entre un valor inicial y uno final segun un factor dado.

**Parámetros**

- `inicio` — `Any`
- `fin` — `Any`
- `factor` — `Any`

**Retorno:** `Any`.

**💻 Ejemplo práctico**

```python
from pycondicionals import lerp
print(lerp(0, 100, 0.5))  # 50.0
```


### 🔹 `is_positive(valor: Any)`

Verifica si un valor numerico es estrictamente mayor que cero.

**Parámetros**

- `valor` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_positive
print(is_positive(3))  # True
```


### 🔹 `is_zero(valor: Any)`

Comprueba si un valor es numericamente igual a cero con precision de punto flotante.

**Parámetros**

- `valor` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_zero
print(is_zero(0))  # True
```


## 🧠 Clases para lógica, temporizadores, estados, persistencia y control de flujo. — `Class_logic.py`

## 🧩 Clase `PrintTranslator`

Una clase diseñada para traducir texto automáticamente a un idioma configurado

### `translator(self)`

Obtiene o inicializa la instancia de Translator de forma diferida (lazy import).

**Parámetros**

- `self`

**Retorno:** `no especificado explícitamente`.

### `setLang(self, nuevo_idioma: str)`

Actualiza el idioma de destino del traductor.

**Parámetros**

- `self`
- `nuevo_idioma` — `str`

**Retorno:** `no especificado explícitamente`.

### `print(self, texto: str, end='\n', flush=False, sep=' ')`

Detecta automáticamente el idioma del texto ingresado, lo traduce al idioma

**Parámetros**

- `self`
- `texto` — `str`
- `end` (por defecto: `'\n'`)
- `flush` (por defecto: `False`)
- `sep` (por defecto: `' '`)

**Retorno:** `no especificado explícitamente`.

### `get_translate(self, texto: str)`

Detecta automáticamente el idioma del texto ingresado, lo traduce al idioma

**Parámetros**

- `self`
- `texto` — `str`

**Retorno:** `no especificado explícitamente`.


## 🧩 Clase `Switch`

Implementación de una estructura tipo switch/case avanzada para Python.

### `case(self, condicion: Any, resultado_o_funcion: Callable[..., Any])`

Añade un caso de evaluación al Switch.

**Parámetros**

- `self`
- `condicion` — `Any`
- `resultado_o_funcion` — `Callable[..., Any]`

**Retorno:** `'Switch'`.

**💻 Ejemplo práctico**

```python
from pycondicionals import Switch
resultado = (Switch(2)
    .case(1, 'Uno')
    .case(2, 'Dos')
    .default('Otro')
    .run())
print(resultado)
```

### `default(self, resultado_o_funcion: Callable[..., Any])`

Define la acción o valor por defecto si ningún caso coincide.

**Parámetros**

- `self`
- `resultado_o_funcion` — `Callable[..., Any]`

**Retorno:** `'Switch'`.

### `run(self)`

Ejecuta la evaluación secuencial de los casos definidos y retorna el resultado correspondiente.

**Parámetros**

- `self`

**Retorno:** `Any`.

**💻 Ejemplo práctico**

```python
from pycondicionals import Switch
resultado = (Switch(2)
    .case(1, 'Uno')
    .case(2, 'Dos')
    .default('Otro')
    .run())
print(resultado)
```


## 🧩 Clase `Cooldown`

Gestiona tiempos de espera, enfriamientos (cooldowns), pausas y estados temporales.

### `start(self)`

Inicia o activa el temporizador del cooldown.

**Parámetros**

- `self`

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import Cooldown
cooldown = Cooldown(5)
cooldown.start()
if cooldown.is_ready():
    print('¡Listo!')
```

### `reset(self)`

Reinicia el estado del cooldown por completo.

**Parámetros**

- `self`

**Retorno:** `None`.

### `pause(self)`

Pausa el temporizador en curso si se encuentra activo.

**Parámetros**

- `self`

**Retorno:** `None`.

### `resume(self)`

Reanuda un cooldown que se encontraba pausado.

**Parámetros**

- `self`

**Retorno:** `None`.

### `tiempo_restante(self)`

Calcula el tiempo restante antes de que finalice el cooldown.

**Parámetros**

- `self`

**Retorno:** `float`.

### `is_ready(self)`

Comprueba si el cooldown ha finalizado y está listo.

**Parámetros**

- `self`

**Retorno:** `bool`.

### `progress(self)`

Calcula el progreso actual del cooldown en una escala de 0.0 a 1.0.

**Parámetros**

- `self`

**Retorno:** `float`.


## 🧩 Clase `StepTracker`

Rastrea y gestiona el progreso secuencial por pasos numéricos.

### `is_current_step(self, paso_a_comprobar: int)`

Comprueba si el paso actual coincide con el paso especificado.

**Parámetros**

- `self`
- `paso_a_comprobar` — `int`

**Retorno:** `bool`.

### `advance(self)`

Avanza al siguiente paso incrementando el contador en uno.

**Parámetros**

- `self`

**Retorno:** `None`.

### `reset(self, paso_destino: int=1)`

Reinicia el rastreador a un paso específico (por defecto el paso 1).

**Parámetros**

- `self`
- `paso_destino` — `int` (por defecto: `1`)

**Retorno:** `None`.


## 🧩 Clase `FrameTimer`

Temporizador basado en ciclos o fotogramas (frames) para bucles de juego o renderizado.

### `check(self)`

Incrementa el contador e indica si se ha completado el intervalo de cuadros especificado.

**Parámetros**

- `self`

**Retorno:** `bool`.


## 🧩 Clase `AutoResetToggle`

Interruptor de estado que se restablece automáticamente a falso tras ser comprobado.

### `trigger(self)`

Activa el interruptor estableciendo su estado en True.

**Parámetros**

- `self`

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import AutoResetToggle
toggle = AutoResetToggle()
toggle.trigger()
if toggle.check_and_reset():
    print('Evento activado')
```

### `check_and_reset(self)`

Comprueba el estado actual. Si es True, lo cambia a False y retorna True; de lo contrario, retorna False.

**Parámetros**

- `self`

**Retorno:** `bool`.


## 🧩 Clase `RetryCounter`

Controlador y contador de reintentos para operaciones propensas a fallos.

### `fail_and_check(self)`

Registra un fallo incrementando los intentos realizados y evalúa si aún hay reintentos disponibles.

**Parámetros**

- `self`

**Retorno:** `bool`.

### `reset(self)`

Reinicia el contador de intentos realizados a cero.

**Parámetros**

- `self`

**Retorno:** `None`.


## 🧩 Clase `CircuitBreaker`

Implementación del patrón Circuit Breaker para la gestión de tolerancia a fallos en sistemas.

### `is_allowed(self)`

Comprueba si la ejecución o acceso está permitida según el estado actual del circuito.

**Parámetros**

- `self`

**Retorno:** `bool`.

### `record_failure(self)`

Registra un fallo, incrementando el contador y abriendo el circuito si se supera el umbral.

**Parámetros**

- `self`

**Retorno:** `None`.

### `record_success(self)`

Registra una ejecución exitosa, restableciendo el contador de fallos y cerrando el circuito.

**Parámetros**

- `self`

**Retorno:** `None`.


## 🧩 Clase `WeightedChoice`

Selector probabilístico que evalúa y extrae elementos basados en pesos relativos.

### `add(self, option: Any, weight: float)`

Añade una opción con su respectivo peso de probabilidad.

**Parámetros**

- `self`
- `option` — `Any`
- `weight` — `float`

**Retorno:** `None`.

### `select(self)`

Selecciona y devuelve una opción de manera aleatoria respetando sus probabilidades.

**Parámetros**

- `self`

**Retorno:** `Any`.

**💻 Ejemplo práctico**

```python
from pycondicionals import WeightedChoice
choices = WeightedChoice()
choices.add('Común', 70)
choices.add('Raro', 25)
choices.add('Legendario', 5)
print(choices.select())
```


## 🧩 Clase `AllowedStates`

Controlador simplificado de flujo de estados para restringir transiciones inválidas en tiempo de ejecución.

### `allow(self, from_state: str, to_states: List[str])`

Registra los estados destino a los que se permite transicionar desde un estado origen específico.

**Parámetros**

- `self`
- `from_state` — `str`
- `to_states` — `List[str]`

**Retorno:** `None`.

### `transition_to(self, target_state: str)`

Intenta cambiar al estado objetivo. Devuelve True si la transición está permitida.

**Parámetros**

- `self`
- `target_state` — `str`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import AllowedStates
states = AllowedStates('inicio')
states.allow('inicio', ['jugando'])
states.transition_to('jugando')
```


## 🧩 Clase `InstantData`

Gestiona persistencia atómica inmediata para configuraciones en archivos JSON.

### `load_data(cls, filename: str, access: str='public', secret_key: Optional[str]=None)`

Carga un archivo JSON existente o prepara uno nuevo si no existe.

**Parámetros**

- `cls`
- `filename` — `str`
- `access` — `str` (por defecto: `'public'`)
- `secret_key` — `Optional[str]` (por defecto: `None`)

**Retorno:** `'InstantData'`.

### `set(self, key: str, value: Any, secret_key: Optional[str]=None)`

Asigna un valor a una clave y lo guarda inmediatamente en el archivo.

**Parámetros**

- `self`
- `key` — `str`
- `value` — `Any`
- `secret_key` — `Optional[str]` (por defecto: `None`)

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import InstantData
data = InstantData('datos.json')
data.set('vida', 100)
print(data.get('vida'))
```

### `get(self, key: str, default: Any=None, secret_key: Optional[str]=None)`

Obtiene el valor de una clave. Si no existe y se define un valor por defecto, lo crea y guarda.

**Parámetros**

- `self`
- `key` — `str`
- `default` — `Any` (por defecto: `None`)
- `secret_key` — `Optional[str]` (por defecto: `None`)

**Retorno:** `Any`.

**💻 Ejemplo práctico**

```python
from pycondicionals import InstantData
data = InstantData('datos.json')
data.set('vida', 100)
print(data.get('vida'))
```

### `delete_file(self, secret_key: Optional[str]=None)`

Elimina permanentemente el archivo JSON del disco y vacía los datos en memoria.

**Parámetros**

- `self`
- `secret_key` — `Optional[str]` (por defecto: `None`)

**Retorno:** `None`.

### `clean_nulls(self)`

Elimina todos los elementos cuyo valor sea None y actualiza el archivo.

**Parámetros**

- `self`

**Retorno:** `None`.

### `exists(self, key: str)`

Comprueba si una clave existe en la configuración.

**Parámetros**

- `self`
- `key` — `str`

**Retorno:** `bool`.

### `keys(self)`

Devuelve una lista con todas las claves guardadas.

**Parámetros**

- `self`

**Retorno:** `List[str]`.

### `update(self, data_dict: Dict[str, Any], secret_key: Optional[str]=None)`

Actualiza varios elementos a la vez usando un diccionario y guarda los cambios.

**Parámetros**

- `self`
- `data_dict` — `Dict[str, Any]`
- `secret_key` — `Optional[str]` (por defecto: `None`)

**Retorno:** `None`.

### `size(self)`

Devuelve la cantidad total de elementos guardados.

**Parámetros**

- `self`

**Retorno:** `int`.


## ⏱️ Utilidades relacionadas con tiempo y ejecución programada. — `Clock.py`

### 🔹 `every(segundos: float, funcion: Callable, id_evento: str='defecto', reset: bool=False)`

Ejecuta una funcion de forma periodica en segundo plano cada cierto intervalo de segundos.

**Parámetros**

- `segundos` — `float`
- `funcion` — `Callable`
- `id_evento` — `str` (por defecto: `'defecto'`)
- `reset` — `bool` (por defecto: `False`)

**Retorno:** `None`.


### 🔹 `once(id_evento: Optional[str]=None, reset: bool=False)`

Registra o comprueba un evento de disparo unico para evitar ejecuciones repetidas.

**Parámetros**

- `id_evento` — `Optional[str]` (por defecto: `None`)
- `reset` — `bool` (por defecto: `False`)

**Retorno:** `bool`.


### 🔹 `is_leap_year(anio: Any)`

Determina si un año dado cumple con las reglas del calendario gregoriano para ser bisiesto.

**Parámetros**

- `anio` — `Any`

**Retorno:** `bool`.


### 🔹 `get_timestamp()`

Obtiene la marca de tiempo actual del sistema formateada como una cadena de texto estandar.

**Parámetros:** ninguno.

**Retorno:** `str`.

**💻 Ejemplo práctico**

```python
from pycondicionals import get_timestamp
print(get_timestamp())
```


### 🔹 `is_night(hora_actual: Optional[Any]=None)`

Verifica si una hora especifica del dia o la hora actual del sistema corresponde al periodo nocturno.

**Parámetros**

- `hora_actual` — `Optional[Any]` (por defecto: `None`)

**Retorno:** `bool`.


### 🔹 `time_count(func: Callable)`

Un decorador avanzado que mide con precision el tiempo de ejecucion de una funcion objetivo.

**Parámetros**

- `func` — `Callable`

**Retorno:** `Callable`.


## 🔍 Validaciones y comprobaciones sobre cadenas y valores. — `Comparison_tools.py`

### 🔹 `is_string(variable: Any)`

Verifica de forma segura si la variable entregada pertenece estrictamente al tipo de cadena de texto.

**Parámetros**

- `variable` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_string
print(is_string('Hola'))  # True
```


### 🔹 `is_number(variable: Any)`

Verifica si la variable entregada es un numero entero o flotante valido, excluyendo explcitamente los valores booleanos.

**Parámetros**

- `variable` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_number
print(is_number(3.14))  # True
```


### 🔹 `is_vowel(caracter: Any)`

Determina si el caracter recibido corresponde a una vocal, abarcando vocales acentuadas y con dieresis.

**Parámetros**

- `caracter` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_vowel
print(is_vowel('a'))  # True
```


### 🔹 `is_alphabetic(texto: Any)`

Verifica si la cadena de texto proporcionada contiene unicamente caracteres alfabeticos.

**Parámetros**

- `texto` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_alphabetic
print(is_alphabetic('Python'))  # True
```


### 🔹 `is_numeric_string(texto: Any)`

Comprueba si la cadena de texto esta compuesta de manera exclusiva por digitos numericos.

**Parámetros**

- `texto` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_numeric_string
print(is_numeric_string('12345'))  # True
```


### 🔹 `has_min_words(texto: Any, cantidad: Union[int, float, str])`

Evalua si la cadena de texto contiene al menos la cantidad minima de palabras especificada.

**Parámetros**

- `texto` — `Any`
- `cantidad` — `Union[int, float, str]`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import has_min_words
print(has_min_words('uno dos tres', 2))  # True
```


### 🔹 `has_uppercase(texto: Any)`

Determina si la cadena de texto evaluada posee al menos una letra en formato mayuscula.

**Parámetros**

- `texto` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import has_uppercase
print(has_uppercase('Python'))  # True
```


### 🔹 `is_binary_string(texto: Any)`

Verifica si la cadena de texto esta formada exclusivamente por caracteres binarios permitidos ('0' y '1').

**Parámetros**

- `texto` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_binary_string
print(is_binary_string('10101'))  # True
```


### 🔹 `content_text(texto_completo: Any, buscar: Any)`

Comprueba de forma flexible si un texto secundario se encuentra contenido dentro del texto principal, ignorando diferencias de mayusculas y minusculas.

**Parámetros**

- `texto_completo` — `Any`
- `buscar` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import content_text
print(content_text('Python es genial', 'genial'))  # True
```


### 🔹 `is_palindrome(texto: Any)`

Determina si una cadena de texto dada es un palindromo perfecto, ignorando tanto los espacios vacios como las mayusculas.

**Parámetros**

- `texto` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_palindrome
print(is_palindrome('radar'))  # True
```


### 🔹 `has_lowercase(texto: Any)`

Determina si la cadena de texto ingresada posee al menos una letra en formato minuscula.

**Parámetros**

- `texto` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import has_lowercase
print(has_lowercase('Python'))  # True
```


## 🔀 Condiciones, colecciones, diccionarios, archivos y correo. — `Conditionals.py`

### 🔹 `create_bar(valor: int, emoji_lleno: str, emoji_vacio: str, max_valor: int=10)`

Genera una barra de progreso visual utilizando emojis basada en un valor numérico y un máximo dado.

**Parámetros**

- `valor` — `int`
- `emoji_lleno` — `str`
- `emoji_vacio` — `str`
- `max_valor` — `int` (por defecto: `10`)

**Retorno:** `str`.

**💻 Ejemplo práctico**

```python
from pycondicionals import create_bar
print(create_bar(70, '█', '░', 10))
```


### 🔹 `variable_exist(var_name: str)`

Verifica si una variable existe dentro del ámbito local o global del marco de ejecución actual.

**Parámetros**

- `var_name` — `str`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import variable_exist
nombre = 'Isaac'
print(variable_exist('nombre'))  # True
```


### 🔹 `exists(key: Any, container: Union[Dict[Any, Any], List[Any], Set[Any], Tuple[Any, ...], Any])`

Verifica de forma segura si una clave existe en un diccionario o si un elemento está presente en una colección.

**Parámetros**

- `key` — `Any`
- `container` — `Union[Dict[Any, Any], List[Any], Set[Any], Tuple[Any, ...], Any]`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import exists
print(exists(3, [1, 2, 3]))  # True
```


### 🔹 `apply_to_all(coleccion: Iterable[Any], funcion: Callable[..., Any], *args: Any, **kwargs: Any)`

Ejecuta una función o método sobre cada elemento de una colección, devolviendo una lista con los resultados.

**Parámetros**

- `coleccion` — `Iterable[Any]`
- `funcion` — `Callable[..., Any]`
- `*args`
- `**kwargs`

**Retorno:** `List[Any]`.

**💻 Ejemplo práctico**

```python
from pycondicionals import apply_to_all
print(apply_to_all([1, 2, 3], lambda x: x * 2))  # [2, 4, 6]
```


### 🔹 `deep_get(diccionario: Dict[str, Any], busqueda: str, default: Any=None, modo: str='auto', sub_rama: Optional[str]=None, clave_modificar: Optional[str]=None, nuevo_valor: Any=None)`

Accede o modifica claves en diccionarios anidados usando notación de puntos o búsqueda recursiva.

**Parámetros**

- `diccionario` — `Dict[str, Any]`
- `busqueda` — `str`
- `default` — `Any` (por defecto: `None`)
- `modo` — `str` (por defecto: `'auto'`)
- `sub_rama` — `Optional[str]` (por defecto: `None`)
- `clave_modificar` — `Optional[str]` (por defecto: `None`)
- `nuevo_valor` — `Any` (por defecto: `None`)

**Retorno:** `Any`.

**💻 Ejemplo práctico**

```python
from pycondicionals import deep_get
datos = {'usuario': {'nombre': 'Isaac'}}
print(deep_get(datos, 'usuario.nombre'))  # Isaac
```


### 🔹 `flatten_dict(diccionario: Dict[str, Any], clave_padre: str='', separador: str='_')`

Aplana un diccionario con anidaciones complejas a un solo nivel de profundidad utilizando un separador.

**Parámetros**

- `diccionario` — `Dict[str, Any]`
- `clave_padre` — `str` (por defecto: `''`)
- `separador` — `str` (por defecto: `'_'`)

**Retorno:** `Dict[str, Any]`.

**💻 Ejemplo práctico**

```python
from pycondicionals import flatten_dict
datos = {'usuario': {'nombre': 'Isaac', 'edad': 10}}
print(flatten_dict(datos))
```


### 🔹 `merge_dicts(d1: Dict[Any, Any], d2: Dict[Any, Any])`

Combina de forma recursiva y profunda dos diccionarios preservando sus subestructuras.

**Parámetros**

- `d1` — `Dict[Any, Any]`
- `d2` — `Dict[Any, Any]`

**Retorno:** `Dict[Any, Any]`.

**💻 Ejemplo práctico**

```python
from pycondicionals import merge_dicts
print(merge_dicts({'a': {'x': 1}}, {'a': {'y': 2}}))
```


### 🔹 `variable_loop(coleccion: Any)`

Itera de forma segura sobre las llaves de un diccionario o los elementos de una colección iterable.

**Parámetros**

- `coleccion` — `Any`

**Retorno:** `Iterator[Any]`.

**💻 Ejemplo práctico**

```python
from pycondicionals import variable_loop
for elemento in variable_loop([10, 20, 30]):
    print(elemento)
```


### 🔹 `is_any_in(lista_buscar: Any, lista_destino: Any)`

Comprueba si al menos uno de los elementos de la lista de búsqueda se encuentra en la lista destino.

**Parámetros**

- `lista_buscar` — `Any`
- `lista_destino` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_any_in
print(is_any_in(['Python', 'C++'], ['JavaScript', 'Python']))  # True
```


### 🔹 `is_all_in(lista_buscar: Any, lista_destino: Any)`

Comprueba si todos los elementos de la lista de búsqueda se encuentran en la lista destino.

**Parámetros**

- `lista_buscar` — `Any`
- `lista_destino` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_all_in
print(is_all_in([1, 2], [1, 2, 3]))  # True
```


### 🔹 `is_ordered(lista: Any, descendente: bool=False)`

Verifica si los elementos de una lista se encuentran ordenados de forma ascendente o descendente.

**Parámetros**

- `lista` — `Any`
- `descendente` — `bool` (por defecto: `False`)

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_ordered
print(is_ordered([1, 2, 3]))  # True
```


### 🔹 `has_duplicates(lista: Any)`

Determina si una colección contiene elementos duplicados.

**Parámetros**

- `lista` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import has_duplicates
print(has_duplicates([1, 2, 1]))  # True
```


### 🔹 `is_unique_collection(lista: Any)`

Verifica si todos los elementos de una colección son totalmente únicos.

**Parámetros**

- `lista` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_unique_collection
print(is_unique_collection([1, 2, 3]))  # True
```


### 🔹 `is_consecutive(lista: Any)`

Comprueba si los elementos numéricos de una lista forman una secuencia estrictamente consecutiva.

**Parámetros**

- `lista` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_consecutive
print(is_consecutive([4, 5, 6]))  # True
```


### 🔹 `is_empty(coleccion: Any)`

Comprueba si una colección o estructura de datos está vacía.

**Parámetros**

- `coleccion` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_empty
print(is_empty([]))  # True
```


### 🔹 `has_length(coleccion: Any, longitud_requerida: Any)`

Verifica si una colección posee exactamente una longitud específica.

**Parámetros**

- `coleccion` — `Any`
- `longitud_requerida` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import has_length
print(has_length([1, 2, 3], 3))  # True
```


### 🔹 `has_min_length(coleccion: Any, minimo: Any)`

Comprueba si una colección cumple con una longitud mínima requerida.

**Parámetros**

- `coleccion` — `Any`
- `minimo` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import has_min_length
print(has_min_length('Python', 3))  # True
```


### 🔹 `has_max_length(coleccion: Any, maximo: Any)`

Comprueba si una colección no supera una longitud máxima permitida.

**Parámetros**

- `coleccion` — `Any`
- `maximo` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import has_max_length
print(has_max_length([1, 2], 3))  # True
```


### 🔹 `has_element(coleccion: Any, elemento: Any)`

Verifica si un elemento específico se encuentra dentro de la colección.

**Parámetros**

- `coleccion` — `Any`
- `elemento` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import has_element
print(has_element(['espada', 'poción'], 'espada'))  # True
```


### 🔹 `has_keys(diccionario: Any, llaves_requeridas: Any)`

Valida si un diccionario contiene todas las llaves requeridas especificadas.

**Parámetros**

- `diccionario` — `Any`
- `llaves_requeridas` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import has_keys
print(has_keys({'nombre': 'Isaac', 'edad': 10}, ['nombre', 'edad']))  # True
```


### 🔹 `is_matrix(objeto: Any, filas_esperadas: Optional[int]=None, columnas_esperadas: Optional[int]=None)`

Verifica si un objeto es una lista bidimensional (matriz) válida y opcionalmente valida sus dimensiones.

**Parámetros**

- `objeto` — `Any`
- `filas_esperadas` — `Optional[int]` (por defecto: `None`)
- `columnas_esperadas` — `Optional[int]` (por defecto: `None`)

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_matrix
print(is_matrix([[1, 2], [3, 4]], 2, 2))  # True
```


### 🔹 `is_trending_up(lista_numeros: Any)`

Comprueba si el último valor numérico de una lista es mayor que el anterior, indicando una tendencia al alza.

**Parámetros**

- `lista_numeros` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_trending_up
print(is_trending_up([10, 12, 15]))  # True
```


### 🔹 `get_random_element(coleccion: Any)`

Obtiene un elemento aleatorio de cualquier colección iterable de manera segura.

**Parámetros**

- `coleccion` — `Any`

**Retorno:** `Any`.

**💻 Ejemplo práctico**

```python
from pycondicionals import get_random_element
print(get_random_element(['rojo', 'azul', 'verde']))
```


### 🔹 `filter_list(lista: List[Any], condicion_funcion: Callable[[Any], bool])`

Filtra una lista aplicando una función de condición evaluada sobre cada elemento.

**Parámetros**

- `lista` — `List[Any]`
- `condicion_funcion` — `Callable[[Any], bool]`

**Retorno:** `List[Any]`.

**💻 Ejemplo práctico**

```python
from pycondicionals import filter_list
print(filter_list([1, 2, 3, 4], lambda x: x % 2 == 0))  # [2, 4]
```


### 🔹 `count_element(coleccion: Any, elemento_a_contar: Any)`

Cuenta la cantidad de veces que un elemento específico aparece dentro de una colección.

**Parámetros**

- `coleccion` — `Any`
- `elemento_a_contar` — `Any`

**Retorno:** `int`.

**💻 Ejemplo práctico**

```python
from pycondicionals import count_element
print(count_element([1, 2, 1, 3], 1))  # 2
```


### 🔹 `shuffle_list(lista: Any)`

Desordena de forma aleatoria los elementos de una colección devolviendo una nueva lista.

**Parámetros**

- `lista` — `Any`

**Retorno:** `List[Any]`.

**💻 Ejemplo práctico**

```python
from pycondicionals import shuffle_list
lista = [1, 2, 3, 4]
print(shuffle_list(lista))
```


### 🔹 `looks_like(text: str, target: str, threshold: float=0.75)`

Compara la similitud visual y ortográfica entre dos cadenas de texto mediante SequenceMatcher.

**Parámetros**

- `text` — `str`
- `target` — `str`
- `threshold` — `float` (por defecto: `0.75`)

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import looks_like
print(looks_like('pythn', 'python'))
```


### 🔹 `share_file(ruta_archivo: str, puerto: int=8000)`

Inicia un servidor HTTP local en un hilo secundario para compartir un archivo específico en la red.

**Parámetros**

- `ruta_archivo` — `str`
- `puerto` — `int` (por defecto: `8000`)

**Retorno:** `Optional[str]`.

**💻 Ejemplo práctico**

```python
from pycondicionals import share_file
url = share_file('archivo.txt', 8000)
print(url)
```


### 🔹 `send_email(usuario: str, password: str, para: str, asunto: str, mensaje: str, es_html: bool=False)`

Envía un correo electrónico mediante SMTP utilizando una cuenta de autenticación configurada.

**Parámetros**

- `usuario` — `str`
- `password` — `str`
- `para` — `str`
- `asunto` — `str`
- `mensaje` — `str`
- `es_html` — `bool` (por defecto: `False`)

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import send_email
ok = send_email('usuario', 'contraseña', 'destino@example.com', 'Hola', 'Mensaje')
print(ok)
```


### 🔹 `detect_duplicate_values(dictionary, mode='bool')`

Detecta si existen valores duplicados dentro de un diccionario.

**Parámetros**

- `dictionary`
- `mode` (por defecto: `'bool'`)

**Retorno:** `no especificado explícitamente`.

**💻 Ejemplo práctico**

```python
from pycondicionals import detect_duplicate_values
print(detect_duplicate_values({'a': 1, 'b': 1}, mode='bool'))
```


### 🔹 `find_extreme_key(dictionary, type_extreme='max')`

Encuentra la clave que tiene el valor numérico mayor o menor

**Parámetros**

- `dictionary`
- `type_extreme` (por defecto: `'max'`)

**Retorno:** `no especificado explícitamente`.

**💻 Ejemplo práctico**

```python
from pycondicionals import find_extreme_key
print(find_extreme_key({'a': 10, 'b': 30, 'c': 20}, 'max'))  # b
```


### 🔹 `variable_name(var)`

**Uso:** Utiliza esta función según los parámetros indicados en su firma.

**Parámetros**

- `var`

**Retorno:** `no especificado explícitamente`.

**💻 Ejemplo práctico**

```python
from pycondicionals import variable_name
x = 42
print(variable_name(x))
```


## 🌐 Servidores y clientes TCP mediante sockets. — `Connections.py`

## 🧩 Clase `Server`

Servidor TCP basado en eventos que administra conexiones de clientes y distribuye eventos.

### `on_start(self, func)`

Decorador que registra una funcion para ejecutarse al arrancar el servidor.

**Parámetros**

- `self`
- `func`

**Retorno:** `no especificado explícitamente`.

### `on_connect(self, func)`

Decorador que registra una funcion cuando un nuevo cliente se conecta.

**Parámetros**

- `self`
- `func`

**Retorno:** `no especificado explícitamente`.

### `on_disconnect(self, func)`

Decorador que registra una funcion cuando un cliente se desconecta.

**Parámetros**

- `self`
- `func`

**Retorno:** `no especificado explícitamente`.

### `on(self, event_name: str)`

Decorador para asociar una funcion a un evento personalizado especifico.

**Parámetros**

- `self`
- `event_name` — `str`

**Retorno:** `no especificado explícitamente`.

### `start(self, host: str='127.0.0.1')`

Inicia la escucha de sockets, ejecuta el callback inicial y bloquea el programa en el bucle principal.

**Parámetros**

- `self`
- `host` — `str` (por defecto: `'127.0.0.1'`)

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import Server
server = Server()
@server.on('chat')
def chat(client, data):
    print(data)
server.start()
```

### `get_id(self)`

Obtiene el puerto numerico asignado dinamicamente al servidor.

**Parámetros**

- `self`

**Retorno:** `Optional[int]`.

### `get_client_count(self)`

Obtiene la cantidad total de clientes conectados en tiempo real.

**Parámetros**

- `self`

**Retorno:** `int`.

### `emit(self, address: Any, event_name: str, data: Optional[Dict[str, Any]]=None)`

Envia un paquete de datos con nombre de evento a una direccion de cliente especifica.

**Parámetros**

- `self`
- `address` — `Any`
- `event_name` — `str`
- `data` — `Optional[Dict[str, Any]]` (por defecto: `None`)

**Retorno:** `bool`.

### `broadcast(self, event_name: str, data: Optional[Dict[str, Any]]=None)`

Transmite un evento y sus datos asociados a la totalidad de clientes conectados.

**Parámetros**

- `self`
- `event_name` — `str`
- `data` — `Optional[Dict[str, Any]]` (por defecto: `None`)

**Retorno:** `None`.

### `stop(self)`

Detiene las operaciones del servidor y cierra el socket base.

**Parámetros**

- `self`

**Retorno:** `None`.


## 🧩 Clase `Client`

Cliente TCP basado en eventos que se conecta a un servidor para intercambiar informacion.

### `on_connect(self, func)`

Decorador asignado al evento de conexion exitosa con el servidor.

**Parámetros**

- `self`
- `func`

**Retorno:** `no especificado explícitamente`.

### `on_disconnect(self, func)`

Decorador asignado al evento de desconexion del servidor.

**Parámetros**

- `self`
- `func`

**Retorno:** `no especificado explícitamente`.

### `on(self, event_name: str)`

Decorador para escuchar respuestas o eventos emitidos por el servidor.

**Parámetros**

- `self`
- `event_name` — `str`

**Retorno:** `no especificado explícitamente`.

### `connect(self, server_id: int, host: str='127.0.0.1')`

Establece comunicacion con el servidor en el puerto especificado e inicia el hilo de escucha.

**Parámetros**

- `self`
- `server_id` — `int`
- `host` — `str` (por defecto: `'127.0.0.1'`)

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import Client
client = Client()
client.connect(1, '127.0.0.1')
client.emit('chat', {'text': 'Hola'})
```

### `is_connected(self)`

Comprueba el estado activo de la conexion con el servidor.

**Parámetros**

- `self`

**Retorno:** `bool`.

### `emit(self, event_name: str, data: Optional[Dict[str, Any]]=None)`

Envia un evento con informacion al servidor conectado.

**Parámetros**

- `self`
- `event_name` — `str`
- `data` — `Optional[Dict[str, Any]]` (por defecto: `None`)

**Retorno:** `bool`.

### `disconnect(self)`

Cierra de manera limpia los flujos de lectura y el socket del cliente.

**Parámetros**

- `self`

**Retorno:** `None`.


## 🧩 Clase `ClientObject`

Objeto de representacion individual para cada cliente conectado al SimpleServer.


## 🧩 Clase `SimpleServer`

Servidor TCP simplificado disenado para juegos e intercambio directo de mensajes.

### `start(self)`

Inicia el servidor y comienza a aceptar conexiones entrantes en segundo plano.

**Parámetros**

- `self`

**Retorno:** `int`.

**💻 Ejemplo práctico**

```python
from pycondicionals import SimpleServer
server = SimpleServer('127.0.0.1', 8080)
server.start()
```

### `wait_clients(self, count: int=1, timeout: Optional[float]=None)`

Bloquea la ejecucion hasta que se haya conectado un numero especificado de clientes.

**Parámetros**

- `self`
- `count` — `int` (por defecto: `1`)
- `timeout` — `Optional[float]` (por defecto: `None`)

**Retorno:** `List[ClientObject]`.

### `get_clients(self)`

Devuelve la lista actual con los objetos cliente conectados (ej. [cliente_1, cliente_2, cliente_3]).

**Parámetros**

- `self`

**Retorno:** `List[ClientObject]`.

### `send(self, data: Any, client: Optional[ClientObject]=None)`

Envia datos a un cliente especifico o los transmite a todos si no se pasa ningun cliente.

**Parámetros**

- `self`
- `data` — `Any`
- `client` — `Optional[ClientObject]` (por defecto: `None`)

**Retorno:** `bool`.

### `receive(self, client: ClientObject, timeout: Optional[float]=None)`

Recibe informacion o mensajes enviados por un cliente especifico.

**Parámetros**

- `self`
- `client` — `ClientObject`
- `timeout` — `Optional[float]` (por defecto: `None`)

**Retorno:** `Any`.

### `stop(self)`

Cierra el servidor y libera todas las conexiones de clientes activas.

**Parámetros**

- `self`

**Retorno:** `None`.


## 🧩 Clase `SimpleClient`

Cliente TCP simplificado para conectar, enviar y recibir datos en SimpleServer de forma directa.

### `connect(self, host: str='127.0.0.1', port: int=8080)`

Se conecta al servidor mediante IP y puerto e inicia el hilo de recepcion de mensajes.

**Parámetros**

- `self`
- `host` — `str` (por defecto: `'127.0.0.1'`)
- `port` — `int` (por defecto: `8080`)

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import SimpleClient
client = SimpleClient()
client.connect('127.0.0.1', 8080)
client.send({'msg': 'Hola'})
```

### `send(self, data: Any)`

Envia un paquete de datos directamente hacia el servidor.

**Parámetros**

- `self`
- `data` — `Any`

**Retorno:** `bool`.

### `receive(self, timeout: Optional[float]=None)`

Recibe el siguiente mensaje proveniente del servidor guardado en la cola.

**Parámetros**

- `self`
- `timeout` — `Optional[float]` (por defecto: `None`)

**Retorno:** `Any`.

### `disconnect(self)`

Finaliza la sesion de SimpleClient y cierra sus sockets.

**Parámetros**

- `self`

**Retorno:** `None`.


## 📐 Distancias, posiciones, colisiones y objetos de consola. — `Geometry.py`

### 🔹 `draw_at(x: int, y: int, contenido: str)`

Escribe un objeto en coordenadas específicas sin limpiar toda la consola.

**Parámetros**

- `x` — `int`
- `y` — `int`
- `contenido` — `str`

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import draw_at
draw_at(5, 3, '@')
```


## 🧩 Clase `Console_Object`

Un objeto que vive en la consola y recuerda su posición.

### `render(self)`

Dibuja el objeto en la consola usando su posición y símbolo actuales.

**Parámetros**

- `self`

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import Console_Object
obj = Console_Object(5, 3, '@')
obj.render()
obj.move(6, 3)
```

### `clear(self)`

Borra el objeto de su posición actual escribiendo un espacio en blanco.

**Parámetros**

- `self`

**Retorno:** `None`.

### `move(self, nuevo_x: Any, nuevo_y: Any)`

Mueve el objeto a una nueva posición limpiando su rastro anterior y redibujándolo.

**Parámetros**

- `self`
- `nuevo_x` — `Any`
- `nuevo_y` — `Any`

**Retorno:** `None`.


### 🔹 `is_inside_screen(x: Any, y: Any, max_x: Any, max_y: Any)`

Verifica si unas coordenadas dadas se encuentran dentro de los límites de la pantalla o consola.

**Parámetros**

- `x` — `Any`
- `y` — `Any`
- `max_x` — `Any`
- `max_y` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_inside_screen
print(is_inside_screen(5, 5, 80, 25))  # True
```


### 🔹 `is_near(pos1: Any, pos2: Any, distancia_maxima: Any)`

Comprueba si dos posiciones se encuentran a una distancia menor o igual a una distancia máxima permitida.

**Parámetros**

- `pos1` — `Any`
- `pos2` — `Any`
- `distancia_maxima` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_near
print(is_near((0, 0), (2, 2), 3))  # True
```


### 🔹 `is_colliding_rect(rect1: Any, rect2: Any)`

Determina si dos rectángulos bidimensionales colisionan entre sí.

**Parámetros**

- `rect1` — `Any`
- `rect2` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_colliding_rect
print(is_colliding_rect((0, 0, 10, 10), (5, 5, 10, 10)))
```


### 🔹 `is_inside_radius(pos_origen: Any, pos_destino: Any, radio: Any)`

Comprueba si una posición de destino se encuentra dentro del radio circular delimitado desde un origen.

**Parámetros**

- `pos_origen` — `Any`
- `pos_destino` — `Any`
- `radio` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_inside_radius
print(is_inside_radius((0, 0), (2, 2), 3))  # True
```


### 🔹 `get_distance(pos1: Any, pos2: Any)`

Calcula la distancia euclidiana exacta entre dos posiciones bidimensionales.

**Parámetros**

- `pos1` — `Any`
- `pos2` — `Any`

**Retorno:** `float`.

**💻 Ejemplo práctico**

```python
from pycondicionals import get_distance
print(get_distance((0, 0), (3, 4)))  # 5.0
```


## 🤖 Agente de aprendizaje y cliente sencillo para Groq. — `IA.py`

## 🧩 Clase `PyCondicionalsError`

Excepción personalizada del ecosistema pycondicionals. Se dispara automáticamente


## 🧩 Clase `IntelligentAgent`

Agente de Aprendizaje por Refuerzo de Grado Avanzado basado en Q-Learning con

### `predict(self, state_data: Any, force_expert: bool=False)`

Ejecuta el mecanismo de toma de decisiones del agente utilizando la política Epsilon-Greedy.

**Parámetros**

- `self`
- `state_data` — `Any`
- `force_expert` — `bool` (por defecto: `False`)

**Retorno:** `Union[str, int]`.

**💻 Ejemplo práctico**

```python
from pycondicionals import IntelligentAgent
agent = IntelligentAgent(['izquierda', 'derecha'])
action = agent.predict({'enemigo': 'cerca'})
print(action)
```

### `think(self, state_data: Any)`

Realiza una inspección analítica del estado cognitivo del agente para un entorno dado.

**Parámetros**

- `self`
- `state_data` — `Any`

**Retorno:** `Dict[Union[str, int], float]`.

### `reward(self, score: float, next_state_data: Optional[Any]=None)`

Aplica retroalimentación de refuerzo (premio o castigo) mediante la Ecuación de Optimización de Bellman.

**Parámetros**

- `self`
- `score` — `float`
- `next_state_data` — `Optional[Any]` (por defecto: `None`)

**Retorno:** `None`.

### `learn(self, state_data: Any, preferred_action: Union[str, int], score: float=10.0)`

Inyecta conocimiento heurístico determinista de forma directa en la base de conocimientos de la IA.

**Parámetros**

- `self`
- `state_data` — `Any`
- `preferred_action` — `Union[str, int]`
- `score` — `float` (por defecto: `10.0`)

**Retorno:** `None`.

### `reflect(self, batch_size: int=15)`

Ejecuta un ciclo de aprendizaje offline basado en Experience Replay (Repetición de Experiencias).

**Parámetros**

- `self`
- `batch_size` — `int` (por defecto: `15`)

**Retorno:** `None`.

### `forget_unuseful_data(self, threshold: float=0.0)`

Optimiza y poda la memoria del agente eliminando registros estériles o contraproducentes.

**Parámetros**

- `self`
- `threshold` — `float` (por defecto: `0.0`)

**Retorno:** `int`.

### `save(self, filepath: str)`

Serializa, comprime y ofusca el estado cognitivo completo del agente en un archivo binario cifrado .itg.

**Parámetros**

- `self`
- `filepath` — `str`

**Retorno:** `None`.

### `load(self, filepath: str)`

Restaura el intelecto, hiper-parámetros, Q-Table y memorias de la IA a partir de un archivo binario cifrado .itg.

**Parámetros**

- `self`
- `filepath` — `str`

**Retorno:** `None`.


## 🧩 Clase `SimpleGroq`

Usa IA de groq para generar contenido de forma rapida y sencilla

### `generate(self, prompt: str, recordar: bool=True, creatividad: float=0.2)`

Genera una respuesta con la API de Groq.

**Parámetros**

- `self`
- `prompt` — `str`
- `recordar` — `bool` (por defecto: `True`)
- `creatividad` — `float` (por defecto: `0.2`)

**Retorno:** `str`.

**💻 Ejemplo práctico**

```python
from pycondicionals import SimpleGroq
ai = SimpleGroq('TU_API_KEY')
print(ai.generate('Explica Python'))
```

### `restart_memory(self)`

Limpia el historial de la conversación para empezar de cero conservando el rol inicial.

**Parámetros**

- `self`

**Retorno:** `no especificado explícitamente`.


## 🎵 Reproducción de audio mediante pygame. — `Music.py`

## 🧩 Clase `AudioError`

Excepción base personalizada para errores relacionados con la reproducción


### 🔹 `play(archivo: str, loop: bool=False, block: bool=False)`

Reproduce un archivo de audio utilizando pygame.

**Parámetros**

- `archivo` — `str`
- `loop` — `bool` (por defecto: `False`)
- `block` — `bool` (por defecto: `False`)

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import play
play('music.mp3')
```


### 🔹 `stopsound(archivo: str=None)`

Detiene la reproducción de un sonido específico o de todos los sonidos activos.

**Parámetros**

- `archivo` — `str` (por defecto: `None`)

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import stopsound
stopsound()
```


## 📨 Envío de información mediante la función PQRSF del proyecto. — `PQRSF.py`

### 🔹 `send_PQRSF(usuario: str, mensaje: str)`

Envía un reporte de PQRSF al formulario privado del desarrollador.

**Parámetros**

- `usuario` — `str`
- `mensaje` — `str`

**Retorno:** `Dict[str, Union[bool, str]]`.

**💻 Ejemplo práctico**

```python
from pycondicionals import send_PQRSF
print(send_PQRSF('Isaac', 'Mensaje de ejemplo'))
```


## 🛡️ Validadores de JSON, IP, email y contraseñas. — `Verifiers.py`

### 🔹 `is_valid_json(texto: Any)`

Verifica si la cadena de texto proporcionada cumple con un formato JSON valido.

**Parámetros**

- `texto` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_valid_json
print(is_valid_json('{"name": "Isaac"}'))  # True
```


### 🔹 `is_valid_ip(texto: Any)`

Valida si la cadena de texto corresponde a una direccion IP de cuatro bloques en formato estandar.

**Parámetros**

- `texto` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_valid_ip
print(is_valid_ip('192.168.1.1'))  # True
```


### 🔹 `is_valid_email(texto: Any)`

Comprueba si la cadena de texto presenta una estructura basica valida para una direccion de correo electronico.

**Parámetros**

- `texto` — `Any`

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_valid_email
print(is_valid_email('user@example.com'))  # True
```


### 🔹 `is_secure_password(password: Any, min_longitud: int=8)`

Evalua si la contrasena cumple con los requisitos minimos de seguridad incluyendo longitud, mayusculas, minusculas y numeros.

**Parámetros**

- `password` — `Any`
- `min_longitud` — `int` (por defecto: `8`)

**Retorno:** `bool`.

**💻 Ejemplo práctico**

```python
from pycondicionals import is_secure_password
print(is_secure_password('Python123'))  # True
```


## 🎤 Reconocimiento y síntesis de voz. — `Voice.py`

## 🧩 Clase `AudioError`

Excepcion base personalizada para errores relacionados con la reproduccion


### 🔹 `play(archivo: str, loop: bool=False, block: bool=False)`

Reproduce un archivo de audio utilizando pygame de manera flexible.

**Parámetros**

- `archivo` — `str`
- `loop` — `bool` (por defecto: `False`)
- `block` — `bool` (por defecto: `False`)

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import play
play('music.mp3')
```


## 🧩 Clase `VoiceTranscript`

Clase encargada de capturar audio directamente desde el microfono durante un tiempo determinado

### `record_and_transcript(self, time_recording: Union[int, float]=5)`

Graba audio del microfono durante una cantidad de tiempo fija y realiza la transcripcion a texto.

**Parámetros**

- `self`
- `time_recording` — `Union[int, float]` (por defecto: `5`)

**Retorno:** `str`.

**💻 Ejemplo práctico**

```python
from pycondicionals import VoiceTranscript
voice = VoiceTranscript()
texto = voice.record_and_transcript(5)
print(texto)
```


## 🧩 Clase `VoiceSpeaker`

Clase encargada de sintetizar cadenas de texto en voz hablada y reproducirlas localmente mediante archivos temporales o guardados.[cite: 1]

### `set_config(self, gender: Optional[str]=None, lang: str='es')`

Configura los parametros de idioma y caracteristicas para la sintesis de la voz.

**Parámetros**

- `self`
- `gender` — `Optional[str]` (por defecto: `None`)
- `lang` — `str` (por defecto: `'es'`)

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import VoiceSpeaker
speaker = VoiceSpeaker()
speaker.set_config(lang='es')
speaker.speak('Hola mundo')
```

### `speak(self, text: str, blocked: Optional[bool]=True)`

Convierte un texto proporcionado en un archivo de audio hablado, lo reproduce localmente y lo elimina al terminar.

**Parámetros**

- `self`
- `text` — `str`
- `blocked` — `Optional[bool]` (por defecto: `True`)

**Retorno:** `None`.

**💻 Ejemplo práctico**

```python
from pycondicionals import VoiceSpeaker
speaker = VoiceSpeaker()
speaker.set_config(lang='es')
speaker.speak('Hola mundo')
```

### `return_archive(self, text: str, filename: str='output_speech.mp3')`

Convierte un texto dado en un archivo de audio hablado utilizando gTTS y lo guarda en el disco sin eliminarlo.

**Parámetros**

- `self`
- `text` — `str`
- `filename` — `str` (por defecto: `'output_speech.mp3'`)

**Retorno:** `str`.


## ⚠️ Notas de uso

- Algunas funciones necesitan dependencias externas o conexión a Internet, según el módulo utilizado.
- Las funciones de red y correo necesitan una configuración válida del entorno.
- Las funciones de audio/voz necesitan sus dependencias y dispositivos/servicios correspondientes.
- `SimpleGroq` requiere una API key válida para utilizar el servicio.

## ⭐ Resumen

PyCondicionals 9.2.0 ofrece una API amplia para **matemáticas, lógica, validación, datos, tiempo, geometría, networking, IA, audio y voz**.
