biblia-cli-project 0.1.0

CLI para consultar versículos bíblicos desde JSON y APIs

📖 Biblia CLI

Una herramienta de línea de comandos rápida y basada en Python para buscar y recuperar versículos bíblicos desde archivos JSON locales y APIs externas.

¿Qué hace la CLI?

Biblia CLI permite consultar versículos bíblicos de manera eficiente. Soporta búsqueda por referencia (como "Exodo 33:7"), rangos de versículos, búsqueda de texto completo y puede obtener datos desde fuentes locales (archivos JSON) o APIs remotas (como YouVersion).

Características principales:

• Búsqueda por referencia: Encuentra versículos específicos o rangos.
• Búsqueda de texto: Busca palabras o frases en toda la Biblia usando un índice invertido.
• Fuentes múltiples: Soporte para datos locales y APIs externas.
• Interfaz rica: Salida formateada con números de versículo en superíndice.
• Configurable: Selecciona versiones bíblicas y proveedores.

Instalación

Requisitos previos

• Python 3.12+
• uv (gestor de paquetes Python)

Pasos de instalación

1. Clona el repositorio:

git clone https://github.com/yourusername/biblia-cli.git
cd biblia-cli

2. Crea y activa un entorno virtual:

uv venv
# En Windows:
.venv\Scripts\activate
# En Unix/Linux/macOS:
source .venv/bin/activate

3. Instala las dependencias:

uv sync

4. Construye e instala el paquete (opcional para desarrollo):

uv build
uv run pip install --force-reinstall dist/*.whl

Configuración de .env

Para usar la API de YouVersion, necesitas configurar una clave de API:

1. Copia el archivo de ejemplo:

cp .env_example .env

2. Edita .env y agrega tu clave de API de YouVersion:

YVP_APP_KEY="tu_clave_de_api_aqui"

Nota: La clave de API es necesaria solo si planeas usar fuentes remotas. Para uso local, no es requerida.

Comandos principales

Listar versiones disponibles

biblia versions

Lista todas las versiones bíblicas disponibles en español.

Seleccionar versión activa

biblia use RV1960

Configura la versión bíblica activa para consultas con API.

Buscar por referencia

biblia ref "Exodo 33:7"

Busca un versículo específico.

Buscar rangos de versículos

biblia ref "Exodo 33:7,10"

Busca un rango de versículos consecutivos.

Búsqueda de texto

biblia buscar "amor"

Busca una palabra o frase en toda la Biblia.

Limitar resultados de búsqueda

biblia buscar "amor" --limit 5

Limita el número de resultados mostrados.

Mostrar texto completo en búsquedas

biblia buscar "amor" --show

Muestra el texto completo de los versículos en los resultados.

Mostrar versión

biblia --version

Muestra la versión del CLI.

Ejemplo con fuente local

Para usar datos locales (archivos JSON), especifica --source local:

biblia ref "Exodo 33:7" --source local

Esto buscará en los archivos JSON locales en el directorio data/.

Ejemplo con API

Para usar una API externa (requiere configuración previa):

1. Selecciona una versión:

biblia use RV1960

2. Busca con fuente API:

biblia ref "Exodo 33:7" --source api

O usa auto para que el CLI elija automáticamente (local si disponible, API si no):

biblia ref "Exodo 33:7" --source auto

Estructura del proyecto

biblia-cli/
├─ biblia/              # Paquete principal
│   ├─ cli.py          # Interfaz de línea de comandos
│   ├─ bible.py        # Lógica de búsqueda de versículos
│   ├─ search.py       # Búsqueda de texto
│   ├─ indexer.py      # Constructor de índice invertido
│   ├─ refs.py         # Analizador de referencias
│   ├─ loader.py       # Cargador de datos JSON
│   ├─ resolver.py     # Resolución de fuentes
│   ├─ config.py       # Configuración de API
│   ├─ config_store.py # Almacenamiento de configuración
│   ├─ models.py       # Modelos de datos
│   ├─ utils.py        # Utilidades
│   └─ providers/      # Proveedores de datos
│       └─ youversion.py # Cliente de YouVersion API
├─ data/               # Datos bíblicos (archivos JSON)
│   ├─ exodo.json      # Libro de Éxodo
│   └─ index.json      # Índice invertido
├─ tests/              # Pruebas
├─ pyproject.toml      # Configuración del proyecto
├─ .env_example        # Ejemplo de configuración
└─ README.md           # Este archivo

Cómo funciona

1. Almacenamiento de datos: El contenido bíblico se almacena en formato JSON, un archivo por libro.
2. Indexación: Un índice invertido mapea palabras a versículos para búsquedas rápidas.
3. Análisis: Un analizador personalizado maneja nombres de libros con espacios (ej. "1 Corintios").
4. Formateo: Los números de versículo se muestran en superíndice para mejor legibilidad.
5. Proveedores: Soporte para múltiples fuentes de datos (local y APIs).

Agregar más libros

1. Crea un nuevo archivo JSON en data/ siguiendo este formato:

{
  "libro": "Nombre del Libro",
  "capitulos": [
    {
      "capitulo": 1,
      "versiculos": [
        {"versiculo": 1, "texto": "Texto del versículo 1"},
        {"versiculo": 2, "texto": "Texto del versículo 2"}
      ]
    }
  ]
}

2. Actualiza el índice ejecutando el indexador.

Contribuir

¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía un pull request.

Licencia

Este proyecto está bajo la Licencia MIT. "abreviaturas": ["Abr"], "capitulos": { "1": { "1": "Verse text here...", "2": "Another verse..." } } }

2. Rebuild the index to include the new book:
```bash
python -m biblia.indexer

Development

Install development dependencies:

uv add --dev pytest

Run tests:

uv run pytest

Future Improvements

• Full chapter lookup
• Abbreviation support (e.g., Jn 3:16)
• REST API
• Rich terminal output formatting
• PyPI publication

License

MIT

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.