pycondicionals 4.0.0

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

⚙️ pycondicionals v4.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 actualiza a la última versión estable directamente desde PyPI:

pip install --upgrade pycondicionals
📦 Características Principales
54 Funciones y Clases Lógicas: Herramientas organizadas para cubrir matemáticas, strings, tiempo, geometría 2D y arquitectura de software.

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 o valores None.

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

📖 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 basada en la probabilidad dada.

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 o iguala 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 o tolerancia porcentual 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 si es consonante o si tiene más de un carácter.

is_alphabetic(texto)
Descripción: Verifica si una cadena contiene única y exclusivamente letras de la A a la Z, 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 (dígitos).

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.

🕒 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. Permite reiniciar el id.

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 en todo el ciclo de ejecución.

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 (soporta el cruce por la medianoche).

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

is_leap_year(anio)
Descripción: Evalúa mediante el algoritmo gregoriano 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 o tupla, itera sobre sus elementos. Si la colección viene vacía o corrupta, salta el bucle de manera limpia sin arrojar valores None o errores de consola.

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 de origen existe dentro de la lista 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 estrictamente dentro del contenedor de destino.

Retorna: True o False.

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

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 los elementos son únicos.

is_unique_collection(lista)
Descripción: Función homóloga complementaria de seguridad 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 sin saltos intermedios.

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 (igual o mayor).

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 (igual o menor).

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 de Python para verificar si contiene todas las palabras o claves indicadas en una lista estructurada.

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. Opcionalmente puede contrastar las dimensiones exactas.

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 de índices.

🌐 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 si es un string común o corrupto.

is_valid_ip(texto)
Descripción: Comprueba a través de segmentación 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 la presencia de un identificador, un símbolo @ y un dominio con extensión válida.

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 requerida, al menos una letra mayúscula, una minúscula y por lo menos un carácter numérico.

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 renderizado dentro de los límites visibles de una pantalla definida por sus resoluciones máximas.

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 en píxeles o unidades 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 en el plano. 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 simplificado 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. Clases y Controladores de Flujo Complejos
Switch
Descripción: Reemplazo elegante de Python 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 (admite valores estáticos, listas o funciones lambda).

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

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

Cooldown
Descripción: Controlador de recarga temporal especializado. Ideal para bloquear ráfagas de disparos, habilidades de personajes o llamadas consecutivas a bases de datos.

Métodos Principales:

ready(): Verifica disponibilidad. Si está listo, consume el cooldown actualizando el marcador interno 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 en hilos de ejecución. Diseñado para orquestar pipelines de datos, misiones secundarias estructuradas o tutoriales por etapas.

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 o paso especificado.

Heartbeat
Descripción: Monitor activo de constancia vital para servicios en segundo plano, subprocesos asíncronos o canales WebSocket abiertos.

Métodos Principales:

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

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

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

Métodos Principales:

fail_and_check(): Registra una ejecución fallida y retorna True si aún quedan intentos de respaldo en el contador.

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

CircuitBreaker
Descripción: Patrón de arquitectura avanzada para sistemas tolerantes a fallos. Evita saturar APIs o servidores externos caídos abriendo el circuito tras acumular errores consecutivos y denegando peticiones de forma instantánea.

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 de manera autónoma si se alcanza el umbral de errores.

record_success(): Restablece el circuito al estado "CERRADO" al detectar que el backend de destino volvió a responder correctamente.

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

Métodos Principales:

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

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