pycondicionals 5.0.1

Librería con condicionales lógicos avanzados y puros para Python

⚙️ pycondicionals v5.0.0

Una librería avanzada, robusta y pura para Python, diseñada para simplificar estructuras lógicas, optimizar flujos en videojuegos y proteger la ejecución de scripts mediante condicionales inteligentes con control de errores integrado.

---

🚀 Instalación

Instala o actualizar a la última versión estable directamente desde PyPI:

pip install --upgrade pycondicionals
📦 Características Principales
64 Funciones y Clases Lógicas: Herramientas organizadas que cubren matemáticas, colecciones, tiempo, seguridad, física 2D y persistencia de datos.

A Prueba de Fallos: Todas las funciones críticas están blindadas con bloques try/except para evitar que tu juego o servidor se caiga por datos corruptos, colecciones vacías o valores None.

Súper Bucles Inteligentes: Motores que adaptan su comportamiento según el tipo de variable de forma automática.

Guardado y Carga Integrados: Herramientas nativas para persistencia de partidas en formato JSON de manera ultra segura.

📖 Documentación Completa de Funciones
A continuación se detallan todas y cada una de las funciones y componentes incluidos en la suite de pycondicionals, organizados por módulos de desarrollo:

🧮 1. Condicionales Numéricos y Matemáticos
between(valor, minimo, maximo, inclusivo=True)
Descripción: Verifica si un número está dentro de un rango numérico.

Retorna: True si está en el rango, False si no o si los datos son inválidos.

chance(porcentaje_exito)
Descripción: Condicional probabilístico inteligente. Si le pasas un decimal entre 0.0 y 1.0, lo convierte automáticamente a porcentaje (ej. 0.85 pasa a 85%).

Retorna: True o False simulando una tirada de dados aleatoria.

is_prime(n)
Descripción: Evalúa matemáticamente si un número entero es primo.

Retorna: True si es primo, False de lo contrario.

is_multiple(valor, divisor)
Descripción: Comprueba si un número es divisible exactamente por otro sin dejar residuo.

Retorna: True si el residuo es cero, False si no o si se intenta dividir por cero.

is_negative(valor)
Descripción: Evalúa si un número es estrictamente menor que cero.

Retorna: True o False.

is_even(valor)
Descripción: Evalúa si un número entero es par.

Retorna: True o False.

is_odd(valor)
Descripción: Evalúa si un número entero es impar.

Retorna: True o False.

is_percent(valor)
Descripción: Revisa si un número se encuentra en el rango estándar de porcentaje (de 0.0 a 100.0 inclusive).

Retorna: True o False.

is_perfect_square(numero)
Descripción: Verifica si un número entero tiene una raíz cuadrada exacta perfecta.

Retorna: True o False.

is_percentage_drop(valor_inicial, valor_actual, porcentaje_limite)
Descripción: Determina si un valor numérico ha caído un porcentaje igual o mayor respecto a su valor de origen original.

Retorna: True si la caída supera el límite, False si no.

is_in_tolerance(valor_medido, valor_esperado, tolerancia_porcentaje)
Descripción: Verifica si un número medido se encuentra dentro del margen de error permitido respecto a un valor objetivo.

Retorna: True o False.

🗂️ 2. Condicionales de Tipo de Dato
is_string(variable)
Descripción: Verifica si el tipo de la variable corresponde a una cadena de texto puro (str).

Retorna: True o False.

is_number(variable)
Descripción: Filtra si la variable es un valor numérico real (int o float), excluyendo booleanos.

Retorna: True o False.

🔠 3. Condicionales de Texto (Strings)
is_vowel(caracter)
Descripción: Revisa si un carácter individual es una vocal (soporta mayúsculas, minúsculas y tildes).

Retorna: True si es vocal, False de lo contrario.

is_alphabetic(texto)
Descripción: Verifica si una cadena contiene única y exclusivamente letras, sin espacios, números ni símbolos.

Retorna: True o False.

is_numeric_string(texto)
Descripción: Determina si un string está compuesto únicamente por caracteres numéricos.

Retorna: True o False.

has_min_words(texto, cantidad)
Descripción: Cuenta las palabras de un texto separadas por espacios y comprueba si alcanza el mínimo requerido.

Retorna: True o False.

has_uppercase(texto)
Descripción: Evalúa si una cadena de texto cuenta con al menos una letra en mayúscula.

Retorna: True o False.

is_binary_string(texto)
Descripción: Analiza si un string está escrito única y exclusivamente en código binario (caracteres '0' y '1').

Retorna: True o False.

🕒 4. Condicionales de Tiempo y Sistema
every(segundos, id_evento="defecto", reset=False)
Descripción: Un temporizador de intervalos globales. Ejecuta la condición como verdadera únicamente si ya transcurrió el tiempo configurado desde su última activación.

Retorna: True en el tick correspondiente, False en el tiempo de espera.

once(id_evento, reset=False)
Descripción: Condicional de disparo único. Almacena en memoria el identificador y solo permite que retorne verdadero la primera vez.

Retorna: True la primera vez, False todas las siguientes.

is_expired(tiempo_inicial, duracion_segundos)
Descripción: Compara un timestamp guardado contra el reloj actual para saber si un temporizador dinámico ya caducó.

Retorna: True si expiró, False si sigue activo.

is_weekend()
Descripción: Consulta el reloj del sistema operativo para verificar si el día actual es sábado o domingo.

Retorna: True en fines de semana, False en días laborales.

is_night(hora_inicio_noche=18, hora_fin_noche=6)
Descripción: Evalúa si la hora actual de la computadora se encuentra dentro de un rango nocturno personalizado.

Retorna: True si es de noche, False si es de día.

is_leap_year(anio)
Descripción: Evalúa si un año específico es bisiesto (tiene 366 días).

Retorna: True o False.

📊 5. Condicionales de Listas, Colecciones y Matrices
variable_loop(coleccion)
Descripción: Generador inteligente que emula un ciclo for. Si recibe un diccionario, itera sobre sus llaves. Si recibe una lista, itera sobre sus elementos. Si está vacía o rota, salta el bucle limpiamente sin arrojar errores.

Uso: for elemento in pc.variable_loop(coleccion):

is_any_in(lista_buscar, lista_destino)
Descripción: Comprueba si al menos uno de los elementos de una lista existe dentro de la de destino.

Retorna: True o False.

is_all_in(lista_buscar, lista_destino)
Descripción: Requiere que todos los elementos declarados en la lista de búsqueda existan dentro de la de destino.

Retorna: True o False.

is_ordered(lista, descendente=False)
Descripción: Analiza una lista y valida si se encuentra ordenada de manera perfecta.

Retorna: True o False.

has_duplicates(lista)
Descripción: Detecta la existencia de elementos duplicados o repetidos dentro de un contenedor lineal.

Retorna: True si hay copias, False si todos son únicos.

is_unique_collection(lista)
Descripción: Función complementaria para comprobar si una colección se encuentra 100% limpia de duplicados.

Retorna: True o False.

is_consecutive(lista)
Descripción: Ordena internamente una lista numérica y comprueba si la secuencia de números es consecutiva paso por paso.

Retorna: True o False.

is_empty(coleccion)
Descripción: Condicional de tamaño cero. Funciona con cadenas, diccionarios, listas, sets y tuplas.

Retorna: True si su tamaño es 0, False si contiene elementos.

has_length(coleccion, longitud_requerida)
Descripción: Comprueba si el tamaño (len) de una estructura es exactamente igual al entero indicado.

Retorna: True o False.

has_min_length(coleccion, minimo)
Descripción: Valida que el tamaño de la estructura cumpla con una longitud mínima establecida.

Retorna: True o False.

has_max_length(coleccion, maximo)
Descripción: Valida que el tamaño de la estructura no supere una longitud máxima establecida.

Retorna: True o False.

has_element(coleccion, elemento)
Descripción: Busca la presencia directa de un elemento dentro de un contenedor compatible.

Retorna: True si se encuentra en la colección, False si no.

has_keys(diccionario, llaves_requeridas)
Descripción: Examina las llaves de un diccionario para verificar si contiene todas las llaves indicadas.

Retorna: True o False.

is_matrix(objeto, filas_esperadas=None, columnas_esperadas=None)
Descripción: Analiza una estructura bidimensional (lista de listas) y valida que sea una matriz rectangular perfecta.

Retorna: True o False.

choose_weighted(opciones, pesos)
Descripción: Algoritmo de azar con prioridad. Elige una opción aleatoria basándose en una lista paralela de pesos o probabilidades relativas.

Retorna: El elemento seleccionado, o None en caso de error.

is_trending_up(lista_numeros)
Descripción: Devuelve True si el último elemento numérico de una lista es mayor que el penúltimo.

Retorna: True o False.

get_random_element(coleccion)
Descripción: Extrae un objeto aleatorio de cualquier colección (listas, tuplas, conjuntos) evitando por completo errores de índice si la estructura llega a estar vacía o corrupta.

Retorna: El elemento seleccionado o None de forma segura.

filter_list(lista, condicion_funcion)
Descripción: Toma una lista y extrae únicamente los elementos que pasen un filtro condicional de función específico (estilo lambda).

Retorna: Una nueva lista filtrada.

count_element(coleccion, elemento_a_contar)
Descripción: Cuenta el número exacto de apariciones de un objeto dentro de una lista o cadena compatible.

Retorna: Un número entero con el total contado.

🌐 6. Condicionales de Formato, Redes y Seguridad
is_valid_json(texto)
Descripción: Intenta deserializar una cadena de texto para verificar si posee una sintaxis JSON estructuralmente válida.

Retorna: True si parsea con éxito, False de lo contrario.

is_valid_ip(texto)
Descripción: Comprueba si un string cumple con el formato oficial de direcciones IPv4 (desde 0.0.0.0 hasta 255.255.255.255).

Retorna: True o False.

is_valid_email(texto)
Descripción: Validador sintáctico ágil de cadenas de correo electrónico para asegurar un formato correcto.

Retorna: True o False.

is_secure_password(password, min_longitud=8)
Descripción: Filtro de políticas de seguridad. Evalúa si un string cuenta con la longitud mínima, al menos una mayúscula, una minúscula y por lo menos un número.

Retorna: True o False.

📐 7. Condicionales de Geometría y Motores de Videojuegos 2D
is_inside_screen(x, y, max_x, max_y)
Descripción: Comprueba si un juego de coordenadas (x, y) se encuentra dentro de los límites visibles de una pantalla.

Retorna: True si está adentro, False si se salió de los bordes.

is_near(pos1, pos2, distancia_maxima)
Descripción: Calcula la distancia euclidiana entre dos puntos cartesianos de dos dimensiones pos1(x, y) y pos2(x, y).

Retorna: True si la distancia es menor o igual al límite configurado.

is_colliding_rect(rect1, rect2)
Descripción: Algoritmo de colisión de cajas alineadas (AABB). Detecta si dos entidades rectangulares se cruzan o intersectan. Cada rectángulo debe proveer las claves 'x', 'y', 'width' y 'height'.

Retorna: True si hay colisión física, False si están separados.

is_inside_radius(pos_origen, pos_destino, radio)
Descripción: Utiliza el teorema de Pitágoras para evaluar si una posición de destino cae dentro de una zona o campo de acción circular alrededor de un origen.

Retorna: True o False.

clamp(valor, minimo, maximo)
Descripción: Freno matemático estructural. Si un número sobrepasa los límites permitidos, lo recorta y lo fuerza a mantenerse exactamente en los bordes establecidos.

Retorna: El valor estabilizado dentro del rango.

💾 8. Sistema de Datos y Persistencia (Novedad v5.0.0)
content_text(texto_completo, buscar)
Descripción: Busca de forma completamente segura si una palabra, frase o carácter existe dentro de otro texto, ignorando la diferencia entre mayúsculas y minúsculas.

Retorna: True si lo encuentra, False si no o si los valores son inválidos.

save_data(filename, datos)
Descripción: Almacena diccionarios, listas o variables estructuradas en un archivo físico serializado en formato JSON. Agrega la extensión .json de forma automática si hace falta.

Retorna: True si la escritura fue exitosa, False si falló el acceso.

load_data(filename, valor_defecto=None)
Descripción: Recupera la información de un archivo JSON. Si el archivo no existe o está dañado, evita el cierre abrupto del programa retornando de forma segura el valor de respaldo.

Retorna: Los datos cargados o el valor_defecto.

🏗️ 9. Clases y Controladores de Flujo Complejos
Switch
Descripción: Reemplazo elegante para emular estructuras condicionales switch/case jerárquicas y encadenadas.

Métodos Principales:

case(condicion, resultado_o_funcion): Agrega una opción de validación.

default(resultado_o_funcion): Define el retorno seguro si ningún caso coincide.

run(): Procesa la lógica secuencial y ejecuta el resultado asociado.

Cooldown
Descripción: Controlador de recarga temporal especializado. Ideal para bloquear ráfagas de disparos o habilidades en videojuegos.

Métodos Principales:

ready(): Verifica disponibilidad. Si está listo, consume el cooldown actualizando el marcador de tiempo y retorna True.

reset(): Fuerza la recarga inmediata del contador a cero.

tiempo_restante(): Retorna un flotante indicando los segundos que faltan antes de poder reactivarse.

StepTracker
Descripción: Gestor secuencial de pasos lógicos. Diseñado para misiones, tutoriales por etapas o pipelines de datos ordenados.

Métodos Principales:

is_current_step(paso): Evalúa si corresponde ejecutar la etapa consultada.

advance(): Avanza el contador interno estrictamente al siguiente paso numérico.

reset(paso_destino=1): Revierte la secuencia al origen especificado.

Heartbeat
Descripción: Monitor activo de constancia vital para servicios en segundo plano o conexiones abiertas.

Métodos Principales:

pulse(): Envía una señal de vida actualizando el timestamp interno.

is_alive(): Retorna False si el tiempo transcurrido desde el último pulso excede la tolerancia máxima.

RetryCounter
Descripción: Controlador para la gestión y mitigación de fallos en llamadas inestables de red o archivos físicos.

Métodos Principales:

fail_and_check(): Registra un fallo y retorna True si aún quedan intentos de respaldo.

reset(): Restablece los intentos consumidos tras una operación exitosa.

CircuitBreaker
Descripción: Patrón de arquitectura avanzada para sistemas tolerantes a fallos. Evita saturar APIs o servidores caídos abriendo el circuito tras acumular errores consecutivos.

Métodos Principales:

is_allowed(): Condicional principal de paso. Bloquea peticiones automáticamente si el estado es "ABIERTO".

record_failure(): Registra fallos y salta al estado de protección si se alcanza el umbral de errores.

record_success(): Restablece el circuito al estado "CERRADO".

Toggle
Descripción: Interruptor lógico elemental para conmutar estados booleanos de forma limpia.

Métodos Principales:

flip(): Cambia dinámicamente el estado interno al opuesto directo (True a False o viceversa) y devuelve el nuevo valor.

FrameTimer
Descripción: Temporizador mecánico basado en ciclos o ticks. Útil para coordinar animaciones internas o lógicas fijas en bucles estables de videojuegos.

Métodos Principales:

check(): Incrementa el contador de fotogramas y da True únicamente al alcanzar el valor límite programado, reiniciándose solo.

AutoResetToggle
Descripción: Interruptor condicional inteligente. Una vez se activa, permite una única lectura verdadera y se resetea a falso automáticamente de inmediato.

Métodos Principales:

trigger(): Enciende el interruptor directamente a True.

check_and_reset(): Lee el estado actual y lo apaga automáticamente si estaba encendido.

👨‍💻 Autor
Desarrollado, estructurado y mantenido con pasión por Isaac.