Metadata-Version: 2.4
Name: pycondicionals
Version: 7.0.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
Dynamic: license-file

Pycondicionals 7.0.0 
Libreria perfecta para logicas complejas

### 0. Sistemas de Persistencia Avanzada

Esta sección contiene la clase encargada de manejar datos en disco.

* **`Instant_data` (Clase)**: Gestiona el almacenamiento de datos en formato JSON de forma atómica y segura.
* `__init__`: Inicializa la base de datos definiendo el archivo y si el acceso es público o privado.
* `_load`: Lee el archivo JSON del disco; si hay error o no existe, retorna un diccionario vacío.
* `_save`: Guarda los datos usando un archivo temporal (`.tmp`) antes de reemplazar el original para evitar corrupción si el programa se cierra de golpe.
* `_verify_access`: Bloquea la lectura/escritura si el acceso es "private" y el archivo que intenta acceder no es el creador original.
* `__setitem__` / `__getitem__`: Permiten asignar y leer datos como si la clase fuera un diccionario (ej. `db["clave"] = valor`).
* `delete_data`: Borra el archivo del disco y limpia la memoria de la instancia.
* `repair_and_clean`: Elimina todas las claves que tengan valor `None` y vuelve a guardar.
* `exists`: Devuelve `True` si una clave ya está guardada.
* `get_default`: Busca una clave; si no existe, la crea con el valor por defecto que le pases.
* `keys`: Retorna una lista con todas las claves guardadas.
* `update_elements`: Permite actualizar o insertar múltiples variables a la vez usando un diccionario.
* `get_size`: Cuenta cuántos elementos hay almacenados.



---

### Nuevas Utilidades Exclusivas (v7.0.0)

Herramientas avanzadas para estructurar código y evitar anidaciones.

| Función | Explicación |
| --- | --- |
| `create_bar` | Genera un string de texto repetido (emojis) simulando una barra de progreso visual. |
| `variable_exist` | Busca si una variable existe inspeccionando el *frame* local o global del programa. |
| `exists` | Función segura (con bloque try) para revisar si una clave existe en un contenedor (diccionarios, listas, etc.). |
| `apply_to_all` | Ejecuta la función que le pases sobre cada uno de los elementos de una colección, ahorrando bucles *for*. |
| `deep_get` | Extrae valores de diccionarios anidados usando puntos (ej. `"usuario.id"`) sin lanzar errores si falla. |
| `flatten_dict` | Convierte un diccionario con niveles profundos en un diccionario de un solo nivel, conectando las claves con un separador (`_`). |
| `merge_dicts` | Une dos diccionarios conservando sus estructuras internas sin sobrescribir nodos enteros. |

---

### 1. Validaciones Numéricas y Matemáticas

Comprobaciones directas para lógica de datos y probabilidades.

| Función | Explicación |
| --- | --- |
| `between` | Revisa si un valor está entre un mínimo y máximo (con opción de incluir o no los bordes). |
| `chance` | Ingresas un porcentaje y devuelve `True` si se cumple esa probabilidad aleatoria. |
| `is_prime` | Verifica mediante cálculos si un número ingresado es primo. |
| `is_multiple` | Confirma si el primer número es divisible exactamente por el segundo. |
| `is_negative` / `is_positive` / `is_zero` | Valida si un valor convertido a flotante es menor, mayor o exactamente igual a 0. |
| `is_even` / `is_odd` | Determina si un número es par o impar usando el módulo matemático. |
| `is_percent` | Comprueba que el número flotante se encuentre en el rango de 0.0 a 100.0. |
| `is_perfect_square` | Verifica si la raíz cuadrada de un número resulta en un número entero exacto. |
| `is_percentage_drop` | Compara un valor inicial y uno actual, y valida si la caída porcentual igualó o superó un límite. |
| `is_in_tolerance` | Revisa si una medición se encuentra dentro del porcentaje de margen de error esperado. |
| `clamp` | Fuerza a que un número no pueda bajar de un mínimo ni superar un máximo dictado. |
| `lerp` | Realiza una interpolación lineal para encontrar un valor intermedio entre dos puntos usando un factor de 0 a 1. |

---

### 2. Validaciones de Texto e Hilos / Strings

Manejo seguro de cadenas de texto.

| Función | Explicación |
| --- | --- |
| `is_string` / `is_number` | Verifican los tipos de la variable asegurando si es texto o números (enteros/flotantes descartando booleanos). |
| `is_vowel` | Valida si la variable es una sola letra y pertenece a las vocales (incluyendo acentos). |
| `is_alphabetic` | Confirma que toda la cadena de texto contenga exclusivamente letras. |
| `is_numeric_string` | Revisa si un texto está compuesto únicamente por caracteres numéricos (dígitos). |
| `has_min_words` | Cuenta las palabras separadas por espacio y verifica si alcanza el mínimo solicitado. |
| `has_uppercase` / `has_lowercase` | Buscan si existe al menos una letra en mayúscula o minúscula dentro del texto. |
| `is_binary_string` | Comprueba que el string proporcionado esté formado única y exclusivamente por caracteres '0' y '1'. |
| `content_text` | Revisa si una cadena de texto (búsqueda) se encuentra dentro de otra ignorando diferencias de mayúsculas/minúsculas. |
| `is_palindrome` | Quita los espacios a un texto y verifica si se lee exactamente igual al revés. |

---

### 3. Sistemas Cronológicos y Ciclos Máquina

Ejecuciones controladas por el reloj del sistema.

* `every`: Función que retorna `True` únicamente cuando han pasado los "X" segundos indicados desde su última ejecución.
* `once`: Registra la línea de código donde se llama y devuelve `True` solo la primera vez, ignorando las llamadas posteriores en el programa.
* `is_leap_year`: Aplica la lógica de división por 4, 100 y 400 para saber si un año es bisiesto.
* `get_timestamp`: Devuelve un texto formateado con el año, mes, día, hora, minuto y segundo actual.
* `is_night`: Verifica si la hora local (o una hora dada) está en el rango nocturno entre las 20:00 y antes de las 6:00.

---

### 4. Iteradores y Colecciones Avanzadas

Manipulación de listas, tuplas y diccionarios.

| Función | Explicación |
| --- | --- |
| `variable_loop` | Iterador genérico que devuelve las claves si es diccionario, o los elementos si es otro tipo de iterable. |
| `is_any_in` | Revisa si al menos un elemento de una lista buscada existe dentro de una lista destino. |
| `is_all_in` | Valida que todos los elementos de la primera lista existan en la lista de destino. |
| `is_ordered` | Confirma si los números de una lista están ordenados de menor a mayor (o mayor a menor si se indica). |
| `has_duplicates` | Devuelve `True` si detecta que algún elemento se repite dentro de la lista. |
| `is_unique_collection` | Función inversa a la anterior; verifica que todos los elementos en la colección sean únicos. |
| `is_consecutive` | Ordena una lista internamente y revisa si cada número avanza de 1 en 1 sin saltos. |
| `is_empty` | Chequea rápidamente si la colección tiene longitud 0. |
| `has_length` / `has_min_length` / `has_max_length` | Validadores numéricos sobre el tamaño (`len`) exacto, mínimo o máximo de una lista. |
| `has_element` / `has_keys` | Verifican pertenencias simples de un elemento en listas o validan la existencia de múltiples claves en un diccionario. |
| `is_matrix` | Verifica que una lista contenga otras listas dentro, y que todas las listas internas tengan exactamente el mismo ancho. |
| `choose_weighted` | Selecciona un elemento al azar, pero usando una lista de "pesos" para que algunas opciones salgan más seguido que otras. |
| `is_trending_up` | Compara los últimos dos números de una lista para saber si el final subió. |
| `get_random_element` | Extrae y retorna un objeto al azar de cualquier tipo de colección. |
| `filter_list` | Limpia una lista dejando solo los elementos que cumplen con la función condicional que le pases. |
| `count_element` | Cuenta cuántas veces se repite un objeto específico en una colección. |
| `shuffle_list` | Toma una lista, crea una copia, la mezcla aleatoriamente y devuelve el resultado desordenado. |

---

### 5. Validaciones Ciberseguridad / Network

Filtros básicos de entradas.

* `is_valid_json`: Verifica que un texto pueda ser analizado correctamente como formato JSON sin que el programa colapse.
* `is_valid_ip`: Revisa que un texto tenga 4 bloques separados por puntos y que los números estén entre 0 y 255.
* `is_valid_email`: Comprobación básica de la existencia del símbolo `@` y un dominio válido.
* `is_secure_password`: Exige una longitud mínima, existencia de al menos una mayúscula, una minúscula y un número.

---

### 6. Geometría, Física y Renderizado de Videojuegos

Lógica para motores en consola.

* **`draw_at`**: Dibuja un carácter en la consola directamente en coordenadas `x,y` usando códigos de escape ANSI, evitando hacer parpadear la pantalla.
* **`Console_Object` (Clase)**: Representa un ente en pantalla.
* `render`: Dibuja el símbolo en su X/Y actuales.
* `clear`: Reemplaza el objeto por un espacio vacío " " para borrarlo.
* `move`: Borra, actualiza posición y vuelve a dibujar en un solo paso.


* `is_inside_screen`: Valida si unas coordenadas X/Y no se salen de un límite máximo de pantalla dictado.
* `is_near` / `is_inside_radius`: Usan la fórmula de distancia (Pitágoras circular) para saber si un punto está cerca de otro.
* `is_colliding_rect`: Detección de colisiones clásicas (AABB) entre dos diccionarios que tienen claves `x`, `y`, `width`, `height`.
* `get_distance`: Retorna la distancia en puntos exactos (flotante) entre dos conjuntos de coordenadas usando la función de hipotenusa.

---

### 7. Entrada y Salida

* `save_data`: Exporta cualquier información a un archivo local (agrega automáticamente la extensión `.json`).
* `load_data`: Lee el archivo JSON local y retorna su contenido o un valor por defecto si falla.

---

### 8. Clases Programáticas y Motores de Control

Sistemas orientados a objetos para regular comportamientos lógicos.

| Clase | Explicación |
| --- | --- |
| `Switch` | Reemplaza estructuras de IFs anidados. Permite registrar `.case(valor, funcion)` y un `.default()`, finalizando con un `.run()` para evaluar todo el bloque. |
| `Cooldown` | Gestiona tiempos de recarga de habilidades o procesos. Posee métodos para iniciar, pausar, ver el porcentaje de progreso (`progress`) o revisar si ya terminó (`is_ready`). |
| `StepTracker` | Controlador numérico para tutoriales o secuencias lineales; tiene métodos para verificar si estás en un paso, avanzar (`advance`) o reiniciar (`reset`). |
| `FrameTimer` | Contador que internamente va sumando ejecuciones; retorna `True` únicamente cuando alcanza la cantidad de cuadros esperada. |
| `AutoResetToggle` | Una variable booleana interruptor que al leerla en estado positivo y activado, se resetea inmediatamente a `False` a sí misma para no repetir acciones. |
| `RetryCounter` | Cuenta los reintentos de una tarea fallida. Falla definitivamente cuando alcanza el número máximo programado. |
| `CircuitBreaker` | Patrón de diseño para red: si detecta demasiados errores (`record_failure`), "abre" el circuito bloqueando ejecuciones un tiempo determinado para no colapsar un sistema; luego intenta restablecerse. |




Desarrollado con pasion por Isaac Tamayo Garcia
