pycondicionals 3.0.0

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

pycondicionals 🚀

¡Bienvenido a pycondicionals 2.0! Una librería creada por Isaac que introduce condicionales lógicos avanzados, puros y limpios para Python.

Esta librería está diseñada para entornos de desarrollo profesionales, desarrollo de videojuegos, backend, automatización y análisis de datos. Te ayuda a deshacerte de bloques complejos de if-elif-else, transformando lógica difusa en condicionales semánticos, seguros y fáciles de mantener.

---

📦 Instalación y Uso Básico

Para instalar o actualizar a la última versión pública desde PyPI, ejecuta en tu terminal:

pip install --upgrade pycondicionals
Para integrarla en tus módulos de Python, impórtala usando el alias estándar pc:Pythonimport pycondicionals as pc
🛠️ Manual de Funciones Explicado (Versión 2.0)Todas las funciones de pycondicionals son condicionales puros. Esto significa que no ejecutan acciones secundarias ni modifican tus variables por detrás; simplemente analizan los datos de entrada y devuelven un valor booleano (True o False). Son ideales para su uso directo dentro de estructuras if.🧮 Condicionales Matemáticos y Numéricos1. pc.between(...)¿Qué hace?: Verifica si un valor numérico se encuentra dentro de un rango específico de tolerancia. Es ideal para procesos de validación de datos financieros, físicas de entornos de juego o parámetros de configuración del sistema.Qué poner en el paréntesis: El valor a evaluar, el límite mínimo aceptable y el límite máximo permitido.Ejemplo real:Python# Validamos si la tasa de interés de un crédito está dentro de los márgenes legales
if pc.between(tasa_interes, 1.5, 24.5):
    print("✅ La tasa de interés se encuentra dentro de los parámetros permitidos.")
2. pc.chance(...) ¡Actualizado Inteligente! ✨¿Qué hace?: Ejecuta una evaluación probabilística basada en un porcentaje estadístico. En la versión 2.0 cuenta con detección inteligente de escala: si ingresas un número entre 0.0 y 1.0, el sistema asume de forma automática que es una tasa decimal ($0.75 = 75\%$). Si ingresas un valor mayor, lo procesa como un entero directo ($75 = 75\%$).Qué poner en el paréntesis: Un número flotante o entero que representa la probabilidad de éxito.Ejemplo real:Python# Soporta tanto formato entero como decimal de forma transparente
if pc.chance(75) or pc.chance(0.75):
    print("🎲 Control de azar exitoso: Evento crítico activado.")
3. pc.is_prime(...)¿Qué hace?: Determina si un número entero es primo. Su aplicación principal radica en algoritmos criptográficos, validación de claves simétricas, hash distribuidos y generación de tokens de seguridad únicos.Qué poner en el paréntesis: El número entero que se desea comprobar.Ejemplo real:Python# Verificación previa de un bloque numérico para criptografía RSA
if pc.is_prime(clave_generada):
    print("🔐 El factor numérico cumple con las propiedades criptográficas iniciales.")
4. pc.is_multiple(...)¿Qué hace?: Comprueba si un número es divisible exactamente por otro sin dejar residuo. Es extremadamente útil para ejecutar scripts periódicos, paginación de bases de datos o para guardar logs de auditoría en bloques de datos específicos.Qué poner en el paréntesis: El contador o valor actual, y el divisor objetivo.Ejemplo real:Python# Guardamos un respaldo del estado del sistema cada 500 transacciones procesadas
if pc.is_multiple(total_transacciones, 500):
    print("💾 Sincronizando checkpoint en la base de datos...")
5. pc.is_negative(...)¿Qué hace?: Valida de forma rápida si un balance o indicador numérico cayó por debajo de cero. Sirve para lanzar alertas de saldos, controlar sobregiros o registrar anomalías de inventario físico.Qué poner en el paréntesis: La variable numérica que se va a inspeccionar.Ejemplo real:Python# Monitoreo de balance en cuentas corporativas
if pc.is_negative(balance_cuenta):
    print("🚨 Alerta: La cuenta presenta un saldo negativo. Bloqueando transacciones de salida.")
6. pc.is_even(...) e pc.is_odd(...)¿Qué hace?: Detectan si un número es par (is_even) o impar (is_odd). En entornos backend se aplican para equilibrar cargas de trabajo mediante algoritmos Round-Robin, o para dividir el procesamiento de registros en hilos de ejecución alternos.Qué poner en el paréntesis: El número de ID o índice a evaluar.Ejemplo real:Python# Distribución balanceada de peticiones entre dos servidores esclavos
if pc.is_even(id_peticion):
    enviar_a_servidor_A()
if pc.is_odd(id_peticion):
    enviar_a_servidor_B()
7. pc.is_percent(...)¿Qué hace?: Confirma que un valor numérico sea matemáticamente un porcentaje válido (comprendido de manera estricta entre 0 y 100). Evita errores de desbordamiento en reportes estadísticos o métricas de servidores.Qué poner en el paréntesis: El número flotante o entero a evaluar.Ejemplo real:Python# Validamos el dato recibido desde el sensor de uso de CPU antes de graficarlo
if pc.is_percent(uso_cpu):
    actualizar_dashboard_metrica(uso_cpu)
8. pc.clamp(...) ¡Nuevo! ✨¿Qué hace?: Limita de forma matemática un número para que se mantenga estrictamente atrapado entre un valor mínimo y uno máximo. Si el valor de entrada se desborda, es ajustado automáticamente al límite más cercano para evitar fallos de rango.Qué poner en el paréntesis: El valor numérico actual, el mínimo permitido y el máximo permitido.Ejemplo real:Python# Forzamos que la salud de una entidad o volumen del sistema no supere los límites del buffer
vida_limpia = pc.clamp(vida_actual + pocion_curativa, 0, 100)
🔠 Condicionales de Texto y Tipos de Datos9. pc.is_string(...) e pc.is_number(...)¿Qué hace?: Actúan como capas de defensa en la API o backend. Inspeccionan el tipo de dato original de una variable para prevenir errores de tipo (TypeError) antes de almacenar la información en bases de datos relacionales o hacer operaciones de negocio.Qué poner en el paréntesis: La variable entrante que deseas auditar.Ejemplo real:Python# Sanitización de datos en un formulario de registro antes de procesarlo
if pc.is_string(nombre_cliente) and pc.is_number(monto_ingreso):
    guardar_en_db(nombre_cliente, monto_ingreso)
10. pc.is_vowel(...)¿Qué hace?: Determina si un carácter alfabético individual es una vocal. Se utiliza de forma profesional en motores de búsqueda, análisis lingüístico de textos (NLP), o algoritmos de indexación semántica.Qué poner en el paréntesis: Una cadena de texto con longitud exacta de 1 carácter.Ejemplo real:Python# Procesamiento de texto para filtros de búsqueda fonética
if pc.is_vowel(caracter_actual):
    incrementar_peso_silabico()
11. pc.is_alphabetic(...)¿Qué hace?: Asegura que una cadena de texto contenga única y exclusivamente letras. Rechaza automáticamente caracteres especiales, números y espacios, sirviendo como filtro de seguridad contra inyecciones de código básicas en campos de nombres de usuario o códigos ISO.Qué poner en el paréntesis: La cadena de texto a auditar.Ejemplo real:Pythonif not pc.is_alphabetic(codigo_pais):
    print("❌ Error: El código de país ISO debe contener únicamente letras de la A-Z.")
12. pc.is_numeric_string(...)¿Qué hace?: Verifica si un String está formado puramente por dígitos numéricos (como un número de cuenta, un código de barras o un ID de empleado en formato texto). Te permite asegurar que la conversión mediante int() será exitosa y no tumbará el servidor web.Qué poner en el paréntesis: El string que deseas verificar.Ejemplo real:Python# Validación de una cadena que simula ser un número de identificación fiscal
if pc.is_numeric_string(documento_identidad):
    id_numerico = int(documento_identidad) # Operación completamente segura
13. pc.has_min_words(...) ¡Nuevo! ✨¿Qué hace?: Analiza la densidad de un string de texto y verifica si cuenta con una cantidad mínima requerida de palabras separadas por espacios. Ideal para análisis de respuestas de formularios o validación de cadenas semánticas.Qué poner en el paréntesis: El string de texto y el número entero de palabras mínimas.Ejemplo real:Python# Validamos que el reporte de un fallo de sistema sea lo suficientemente descriptivo
if not pc.has_min_words(descripcion_ticket, 5):
    print("❌ Error: La descripción del ticket debe contener al menos 5 palabras.")
⏱️ Condicionales de Tiempo, Fronteras y Eventos14. pc.every(...)¿Qué hace?: Un temporizador lógico no bloqueante de alto rendimiento. Retorna True cada vez que transcurre el intervalo de tiempo especificado en segundos. Al no utilizar funciones bloqueantes como time.sleep(), el servidor o script puede seguir atendiendo miles de peticiones simultáneas sin perder rendimiento.Qué poner en el paréntesis: El intervalo de tiempo en segundos y una clave id_evento exclusiva para el rastreo del evento.Ejemplo real:Pythonwhile servidor_backend_activo:
    # Sincroniza los tokens expirados de la memoria cada 60 segundos de forma asíncrona
    if pc.every(60, id_evento="limpieza_sesiones_tokens"):
        eliminar_tokens_expirados()
15. pc.once(...)¿Qué hace?: Un interruptor de ejecución única con persistencia interna en memoria. Solo devolverá True la primera vez que el flujo del programa pase por la función; las siguientes evaluaciones darán False. Es óptimo para inicializar configuraciones del sistema, abrir sockets de red una sola vez o disparar alertas críticas de inicio.Qué poner en el paréntesis: Un identificador de texto único para el evento.Ejemplo real:Pythondef procesar_peticion_http(request):
    # Dispara el logger de auditoría inicial solo con la primera llamada al servidor
    if pc.once("inicializacion_logs_sistema"):
        print("🚨 Auditoría: Sistema de logs corporativo conectado y escuchando...")
16. pc.is_inside_screen(...) ¡Nuevo! ✨¿Qué hace?: Evalúa si una coordenada bidimensional (x, y) se encuentra contenida de manera segura dentro de una resolución espacial o dimensiones lógicas establecidas. Evita desbordamientos gráficos o coordenadas fuera del mapa físico del motor.Qué poner en el paréntesis: La coordenada x actual, la coordenada y actual, el ancho máximo (max_x) y el alto máximo (max_y).Ejemplo real:Python# Validación perimetral para entidades físicas o elementos interactivos
if not pc.is_inside_screen(pos_x, pos_y, 1920, 1080):
    destruir_entidad_fuera_de_limites()
17. pc.is_near(...) ¡Nuevo! ✨¿Qué hace?: Aplica el teorema de la distancia euclidiana en un plano de dos dimensiones para determinar de forma limpia si dos posiciones en el espacio están a una distancia menor o igual al umbral fijado.Qué poner en el paréntesis: Una tupla o lista con la posición 1 (x, y), una con la posición 2 (x, y) y la distancia máxima de tolerancia.Ejemplo real:Python# Detección automatizada de proximidad entre nodos de red o elementos en un entorno de juego
if pc.is_near(pos_jugador, pos_punto_interaccion, distancia_maxima=45.0):
    print("🔌 Conexión o interacción disponible. Nodo dentro de rango.")
18. pc.is_expired(...) ¡Nuevo! ✨¿Qué hace?: Evalúa si un timestamp inicial ya ha superado una duración específica en segundos en comparación con el tiempo de sistema actual. Reemplaza cálculos manuales complejos de time.time().Qué poner en el paréntesis: El valor de tiempo inicial (time.time()) y los segundos que representan la duración del evento.Ejemplo real:Python# Control de vigencia de sesiones temporales o efectos transitorios en hilos independientes
if pc.is_expired(timestamp_inicio_sesion, duracion_segundos=3600):
    print("🔒 La sesión ha expirado por inactividad. Reautenticando...")
🎒 Condicionales de Listas, Inventarios y Colecciones19. pc.is_any_in(...)¿Qué hace?: Revisa si existe una coincidencia parcial de elementos. Te dice si al menos uno de los componentes de una lista de origen se encuentra dentro de una lista de destino. Muy útil en sistemas de control de acceso basados en roles (RBAC).Qué poner en el paréntesis: La lista de elementos buscados y la lista contenedora donde se ejecutará la búsqueda.Ejemplo real:Pythonpermisos_requeridos = ["ADMIN", "EDITOR"]
# Verifica si el usuario autenticado tiene al menos uno de los permisos del endpoint
if pc.is_any_in(permisos_requeridos, roles_usuario_actual):
    permitir_acceso_al_modulo()
20. pc.is_all_in(...)¿Qué hace?: Validador estricto de cumplimiento de listas. Devuelve True única y exclusivamente si todos los elementos requeridos de la primera lista están presentes en la segunda. Se utiliza habitualmente en validaciones de esquemas de API, listas de comprobación de despliegues y auditoría de infraestructura.Qué poner en el paréntesis: La lista de elementos obligatorios y la lista a evaluar.Ejemplo real:Pythonarchivos_obligatorios = ["config.json", "ssl.key", "database.db"]
# Comprobamos que el servidor tenga todos sus archivos críticos antes de arrancar
if pc.is_all_in(archivos_obligatorios, os.listdir("./app_data")):
    print("✅ Configuración de sistema íntegra. Iniciando entorno de producción.")
21. pc.is_ordered(...)¿Qué hace?: Valida si una estructura iterable (como una lista) conserva un orden secuencial estricto. Permite confirmar si los datos devueltos por una consulta de base de datos SQL o MongoDB se ordenaron correctamente a nivel de infraestructura antes de enviarlos a una aplicación cliente.Qué poner en el paréntesis: La lista a validar y opcionalmente el parámetro descendente=True.Ejemplo real:Python# Verificamos si los logs de marcas de tiempo vienen en estricto orden cronológico
if pc.is_ordered(timestamps_servidor):
    print("📈 Los registros mantienen una línea temporal coherente.")
22. pc.has_duplicates(...)¿Qué hace?: Analiza colecciones de datos y te alerta si existen registros duplicados o filas repetidas. Es crucial para procesos de limpieza de datos en ciencia de datos (Data Wrangling), detección de transacciones clonadas idénticas o validaciones de correos electrónicos únicos en una base de datos.Qué poner en el paréntesis: La lista o tupla de elementos.Ejemplo real:Pythonif pc.has_duplicates(lista_correos_registro):
    print("❌ Proceso denegado: Se detectaron registros duplicados en los correos ingresados.")
23. pc.is_consecutive(...)¿Qué hace?: Evalúa una lista numérica y confirma si constituye una secuencia entera continua sin ningún tipo de interrupción o salto (1, 2, 3...). Se aplica profesionalmente para auditar que no existan saltos en las facturas correlativas emitidas por el sistema o pérdidas de paquetes de datos de red con número de secuencia.Qué poner en el paréntesis: La lista de enteros a auditar.Ejemplo real:Python# Verificación de auditoría fiscal en números de folios de facturas electrónicas
if pc.is_consecutive(folios_facturación_mes):
    print("📄 Secuencia contable correcta: No faltan folios en el lote financiero.")
24. pc.is_empty(...)¿Qué hace?: Determina con precisión si una lista, diccionario, conjunto o string carece por completo de datos. Es mucho más legible y elegante en código corporativo que utilizar if len(objeto) == 0.Qué poner en el paréntesis: El contenedor o elemento de tipo texto que vas a evaluar.Ejemplo real:Python# Validamos el cuerpo de una petición JSON antes de procesarla
if pc.is_empty(request_json_data):
    print("🛑 HTTP 400: El cuerpo del payload de la API está completamente vacío.")
25. pc.has_length(...)¿Qué hace?: Un validador de tamaño explícito. Retorna True si la colección contiene exactamente el número de elementos requeridos. Ideal para validar estructuras estáticas de datos fijos.Qué poner en el paréntesis: La colección o texto, y la longitud numérica exacta deseada.Ejemplo real:Python# Verificación estructural de tramas de datos recibidas por protocolo TCP
if pc.has_length(trama_bytes, 1024):
    print("💾 Bloque de datos del tamaño exacto correcto. Guardando en búfer...")
26. pc.has_element(...)¿Qué hace?: Proporciona un condicional funcional estandarizado para chequear la existencia de un objeto específico dentro de cualquier iterable, sustituyendo el operador nativo por una sintaxis funcional orientada a objetos.Qué poner en el paréntesis: La colección y el ítem buscado.Ejemplo real:Pythonif pc.has_element(direcciones_ip_bloqueadas, ip_cliente):
    print("🚫 Acceso Denegado: La IP del cliente se encuentra en la lista de exclusión corporativa.")
27. pc.has_min_length(...) y pc.has_max_length(...)¿Qué hace?: Validan que un texto o lista respete longitudes mínimas y máximas operacionales. Son indispensables en el manejo seguro de strings, validación de contraseñas complejas, longitudes de números telefónicos o límites en campos de comentarios para evitar desbordamientos de datos en la base de datos.Qué poner en el paréntesis: La estructura de datos o texto, y el límite numérico.Ejemplo real:Python# Validación de parámetros mínimos de seguridad en credenciales de usuario
if not pc.has_min_length(password_usuario, 12):
    print("❌ Error de seguridad: La credencial debe contener un mínimo de 12 caracteres.")
28. pc.is_unique_collection(...) ¡Nuevo! ✨¿Qué hace?: Analiza la integridad estructural de una lista o colección, garantizando al programador que absolutamente todos los elementos contenidos son únicos y libres de duplicación. Es el condicional inverso a has_duplicates.Qué poner en el paréntesis: La colección o lista iterable a auditar.Ejemplo real:Python# Verificación de un inventario de transacciones o claves primarias limpias
if pc.is_unique_collection(lote_claves_primarias):
    print("💎 Colección íntegra. Todos los identificadores son únicos.")
29. pc.is_trending_up(...) ¡Nuevo! ✨¿Qué hace?: Evalúa analíticamente las variaciones de una lista de métricas numéricas correlativas y determina si la tendencia en el último tramo es alcista o de crecimiento.Qué poner en el paréntesis: Una lista o tupla compuesta por registros numéricos ordenados.Ejemplo real:Python# Analizador de racha financiera o de rendimiento del servidor
if pc.is_trending_up(historico_uso_ram):
    print("📈 Alerta analítica: El uso de memoria RAM presenta una tendencia de crecimiento continuo.")
🏗️ Estructuras Condicionales Avanzadas (Clases)30. Clase pc.Switch¿Qué hace?: Es un motor de toma de decisiones jerárquico que reemplaza arquitecturas anidadas de if-elif-else. Permite mapear variables contra múltiples valores estáticos o colecciones de criterios en una sola llamada encadenada, mejorando drásticamente el mantenimiento del software.Ejemplo real:Python# Enrutamiento de flujos de pago dependiendo de la pasarela seleccionada
codigo_respuesta = (
    pc.Switch(metodo_pago_cliente)
    .case("STRIPE", "Procesando cobro mediante pasarela Stripe internacional.")
    .case(["PAYPAL", "MERCADOPAGO"], "Abriendo pasarela externa de pagos tokenizada.")
    .default("Método de pago no soportado por el sistema.")
    .run()
)
print(codigo_respuesta)
31. Clase pc.Cooldown¿Qué hace?: Implementación del algoritmo Rate Limiting a nivel de código. Este objeto controla la frecuencia de ejecución de un bloque de código, impidiendo abusos por llamadas masivas. Es la herramienta perfecta para limitar reintentos de inicio de sesión de usuarios, restringir el envío masivo de correos electrónicos (spam) o evitar que un script sature una API externa de terceros superando los límites de la suscripción.Qué poner en el paréntesis: Los segundos obligatorios de espera entre ejecuciones.Ejemplo real:Python# Restringimos el envío de correos de restablecimiento de contraseña a uno cada 60 segundos
limite_peticion_email = pc.Cooldown(60)

def solicitar_recuperacion_cuenta():
    if limite_peticion_email.ready():
        enviar_correo_electronico()
        print("📧 Enlace de recuperación enviado con éxito.")
    else:
        print(f"⏳ Petición bloqueada por seguridad. Reintente en {limite_peticion_email.tiempo_restante():.1f} segundos.")
32. Clase pc.Toggle ¡Nuevo! ✨¿Qué hace?: Actúa como una máquina de estados básica de tipo interruptor electrónico. Mantiene un estado booleano persistente en memoria y lo alterna a su opuesto exacto en cada llamada a su método, devolviendo el nuevo valor lógico inmediatamente. Reemplaza la necesidad de declarar banderas booleanas globales.Qué poner en el paréntesis: El valor inicial lógico opcional (True o False).Ejemplo real:Python# Control asíncrono para encender/apagar módulos de auditoría o estados del motor de juego
sistema_pausa = pc.Toggle(estado_inicial=False)

# Cada interacción conmuta el estado de forma limpia
print(sistema_pausa.flip()) # Devuelve: True (Sistema Activado / En Pausa)
print(sistema_pausa.flip()) # Devuelve: False (Sistema Desactivado / Reanudado)
Desarrollado con altos estándares por Isaac. ¡Libre para usar en entornos de producción, desarrollo de videojuegos y software empresarial!