rosary 1.0.0__tar.gz

rosary-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.3
+Name: rosary
+Version: 1.0.0
+Summary: A terminal UI to guide users through the Rosary
+Requires-Dist: textual>=0.74
+Requires-Dist: httpx>=0.27
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# rosary
+
+`rosary` is a terminal application for praying the Holy Rosary step by step. It guides you through the opening prayers, the five decades, and the closing prayers in a clean Textual interface, with mystery descriptions and scripture references included along the way.
+
+## Features
+
+- Guided Rosary flow from beginning to end
+- English and Latin prayer modes
+- Bible translation selection in English mode
+- Automatic mystery recommendation based on the day of the week
+- Intentions prompt before the Rosary begins
+- Scripture lookups for mysteries with direct biblical references
+- Built-in fallback translation list if the live API is unavailable
+
+## Requirements
+
+- Python 3.13 or newer
+- A terminal that supports Textual applications
+- Internet access for live translation and scripture fetching
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install rosary
+```
+
+If you prefer an isolated CLI install:
+
+```bash
+pipx install rosary
+```
+
+## Quick start
+
+Run the app with:
+
+```bash
+rosary
+```
+
+You will then:
+
+1. Choose **English** or **Latin**.
+2. Select a Bible translation in English mode.
+3. Accept the suggested mystery set for the day or choose another one.
+4. Offer your intentions.
+5. Move through the Rosary one step at a time.
+
+## Mystery schedule
+
+The app suggests the traditional mystery set for the current weekday:
+
+| Day | Mysteries |
+| --- | --- |
+| Monday | Joyful |
+| Tuesday | Sorrowful |
+| Wednesday | Glorious |
+| Thursday | Luminous |
+| Friday | Sorrowful |
+| Saturday | Joyful |
+| Sunday | Glorious |
+
+You can always override the suggestion from the selection screen.
+
+## Keyboard controls
+
+### Selection screens
+
+- `q` to quit
+- `escape` to go back when available
+- arrow keys to move through options
+- `enter` to confirm a selection
+
+### Rosary screen
+
+- `space` or `right arrow` for the next step
+- `backspace` or `left arrow` for the previous step
+- `q` to quit
+- `r` to start again after completion
+
+## Included prayer flow
+
+The guided flow includes:
+
+- Sign of the Cross
+- Apostles' Creed
+- Our Father
+- three Hail Marys
+- Glory Be
+- five decades with mystery descriptions
+- Hail Holy Queen
+- Closing Prayer
+- Sign of the Cross
+
+For mysteries such as the Assumption and Coronation, the app shows a doctrinal note when no direct scripture passage is used.
+
+## Development
+
+To work on the project locally:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Or with `uv`:
+
+```bash
+uv sync
+uv run rosary
+```
+
+## Project layout
+
+```text
+src/rosary/
+├── api.py              # bible-api.com client
+├── app.py              # top-level Textual app
+├── main.py             # CLI entry point
+├── mysteries.py        # mystery definitions and weekday suggestion logic
+├── prayers.py          # English and Latin prayer texts
+└── screens/
+    ├── welcome.py
+    ├── mystery_select.py
+    ├── intentions.py
+    └── rosary.py
+```
+
+## License
+
+See `LICENSE`.

rosary-1.0.0/README.md

@@ -0,0 +1,134 @@
+# rosary
+
+`rosary` is a terminal application for praying the Holy Rosary step by step. It guides you through the opening prayers, the five decades, and the closing prayers in a clean Textual interface, with mystery descriptions and scripture references included along the way.
+
+## Features
+
+- Guided Rosary flow from beginning to end
+- English and Latin prayer modes
+- Bible translation selection in English mode
+- Automatic mystery recommendation based on the day of the week
+- Intentions prompt before the Rosary begins
+- Scripture lookups for mysteries with direct biblical references
+- Built-in fallback translation list if the live API is unavailable
+
+## Requirements
+
+- Python 3.13 or newer
+- A terminal that supports Textual applications
+- Internet access for live translation and scripture fetching
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install rosary
+```
+
+If you prefer an isolated CLI install:
+
+```bash
+pipx install rosary
+```
+
+## Quick start
+
+Run the app with:
+
+```bash
+rosary
+```
+
+You will then:
+
+1. Choose **English** or **Latin**.
+2. Select a Bible translation in English mode.
+3. Accept the suggested mystery set for the day or choose another one.
+4. Offer your intentions.
+5. Move through the Rosary one step at a time.
+
+## Mystery schedule
+
+The app suggests the traditional mystery set for the current weekday:
+
+| Day | Mysteries |
+| --- | --- |
+| Monday | Joyful |
+| Tuesday | Sorrowful |
+| Wednesday | Glorious |
+| Thursday | Luminous |
+| Friday | Sorrowful |
+| Saturday | Joyful |
+| Sunday | Glorious |
+
+You can always override the suggestion from the selection screen.
+
+## Keyboard controls
+
+### Selection screens
+
+- `q` to quit
+- `escape` to go back when available
+- arrow keys to move through options
+- `enter` to confirm a selection
+
+### Rosary screen
+
+- `space` or `right arrow` for the next step
+- `backspace` or `left arrow` for the previous step
+- `q` to quit
+- `r` to start again after completion
+
+## Included prayer flow
+
+The guided flow includes:
+
+- Sign of the Cross
+- Apostles' Creed
+- Our Father
+- three Hail Marys
+- Glory Be
+- five decades with mystery descriptions
+- Hail Holy Queen
+- Closing Prayer
+- Sign of the Cross
+
+For mysteries such as the Assumption and Coronation, the app shows a doctrinal note when no direct scripture passage is used.
+
+## Development
+
+To work on the project locally:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Or with `uv`:
+
+```bash
+uv sync
+uv run rosary
+```
+
+## Project layout
+
+```text
+src/rosary/
+├── api.py              # bible-api.com client
+├── app.py              # top-level Textual app
+├── main.py             # CLI entry point
+├── mysteries.py        # mystery definitions and weekday suggestion logic
+├── prayers.py          # English and Latin prayer texts
+└── screens/
+    ├── welcome.py
+    ├── mystery_select.py
+    ├── intentions.py
+    └── rosary.py
+```
+
+## License
+
+See `LICENSE`.

rosary-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "rosary"
+version = "1.0.0"
+description = "A terminal UI to guide users through the Rosary"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "textual>=0.74",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+rosary = "rosary.main:main"
+release = "scripts.release:main"
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "respx>=0.22.0",
+]

rosary-1.0.0/src/rosary/api.py

@@ -0,0 +1,96 @@
+"""Async client for bible-api.com."""
+
+from __future__ import annotations
+
+import httpx
+
+BASE_URL = "https://bible-api.com"
+
+# Translations available on bible-api.com (identifier → display name).
+# This is fetched live; this list is kept as a static fallback.
+_FALLBACK_TRANSLATIONS: list[dict] = [
+    {"identifier": "web", "name": "World English Bible", "language": "English"},
+    {"identifier": "kjv", "name": "King James Version", "language": "English"},
+    {
+        "identifier": "asv",
+        "name": "American Standard Version (1901)",
+        "language": "English",
+    },
+    {"identifier": "bbe", "name": "Bible in Basic English", "language": "English"},
+    {"identifier": "darby", "name": "Darby Bible", "language": "English"},
+    {
+        "identifier": "dra",
+        "name": "Douay-Rheims 1899 American Edition",
+        "language": "English",
+    },
+    {"identifier": "ylt", "name": "Young's Literal Translation", "language": "English"},
+    {
+        "identifier": "oeb-cw",
+        "name": "Open English Bible, Commonwealth Edition",
+        "language": "English (UK)",
+    },
+    {
+        "identifier": "oeb-us",
+        "name": "Open English Bible, US Edition",
+        "language": "English (US)",
+    },
+    {
+        "identifier": "webbe",
+        "name": "World English Bible, British Edition",
+        "language": "English (UK)",
+    },
+    {
+        "identifier": "clementine",
+        "name": "Clementine Latin Vulgate",
+        "language": "Latin",
+    },
+    {
+        "identifier": "almeida",
+        "name": "João Ferreira de Almeida",
+        "language": "Portuguese",
+    },
+    {
+        "identifier": "rccv",
+        "name": "Protestant Romanian Cornilescu Version",
+        "language": "Romanian",
+    },
+    {"identifier": "cuv", "name": "Chinese Union Version", "language": "Chinese"},
+    {"identifier": "bkr", "name": "Bible kralická", "language": "Czech"},
+    {
+        "identifier": "cherokee",
+        "name": "Cherokee New Testament",
+        "language": "Cherokee",
+    },
+]
+
+
+async def fetch_translations() -> tuple[list[dict], bool]:
+    """Return (translations, api_error).
+
+    translations: list of dicts with keys identifier, name, language.
+    api_error: True if the live API could not be reached (fallback used).
+    """
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        try:
+            response = await client.get(f"{BASE_URL}/data")
+            response.raise_for_status()
+            data = response.json()
+            return data.get("translations", _FALLBACK_TRANSLATIONS), False
+        except (httpx.HTTPError, KeyError, ValueError):
+            return _FALLBACK_TRANSLATIONS, True
+
+
+async def fetch_verse(ref: str, translation_id: str) -> str:
+    """Fetch the text for a scripture reference.
+
+    Returns the combined verse text, or an empty string on failure.
+    """
+    url = f"{BASE_URL}/{ref}"
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        try:
+            response = await client.get(url, params={"translation": translation_id})
+            response.raise_for_status()
+            data = response.json()
+            return data.get("text", "").strip()
+        except (httpx.HTTPError, KeyError, ValueError):
+            return ""

rosary-1.0.0/src/rosary/app.py

@@ -0,0 +1,28 @@
+"""RosaryApp — top-level Textual application."""
+
+from __future__ import annotations
+
+from textual.app import App
+
+from rosary.screens.welcome import WelcomeScreen
+
+
+class RosaryApp(App):
+    """A TUI guide through the Holy Rosary."""
+
+    TITLE = "The Holy Rosary"
+    CSS = """
+    App {
+        background: $surface;
+    }
+    """
+
+    # Shared state written by WelcomeScreen / MysterySelectScreen,
+    # read by RosaryScreen.
+    translation_id: str = "kjv"
+    translation_name: str = "King James Version"
+    mystery_set_key: str = "Joyful"
+    language: str = "English"
+
+    def on_mount(self) -> None:
+        self.push_screen(WelcomeScreen())

rosary-1.0.0/src/rosary/main.py

@@ -0,0 +1,9 @@
+from rosary.app import RosaryApp
+
+
+def main() -> None:
+    RosaryApp().run()
+
+
+if __name__ == "__main__":
+    main()

rosary-1.0.0/src/rosary/mysteries.py

@@ -0,0 +1,179 @@
+"""Rosary mystery sets and day-of-week suggestion logic."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Mystery:
+    name: str
+    description: str
+    scripture_ref: Optional[str]  # None when no direct scriptural citation exists
+    scripture_note: Optional[str] = None  # displayed in place of a verse
+
+
+@dataclass(frozen=True)
+class MysterySet:
+    name: str
+    mysteries: tuple[Mystery, ...]
+
+
+JOYFUL = MysterySet(
+    name="Joyful Mysteries",
+    mysteries=(
+        Mystery(
+            name="The Annunciation",
+            description="The Angel Gabriel announces to Mary that she will conceive the Son of God.",
+            scripture_ref="Luke 1:26-33",
+        ),
+        Mystery(
+            name="The Visitation",
+            description="Mary visits her cousin Elizabeth, who is carrying John the Baptist.",
+            scripture_ref="Luke 1:39-45",
+        ),
+        Mystery(
+            name="The Nativity",
+            description="Jesus is born in Bethlehem.",
+            scripture_ref="Luke 2:6-12",
+        ),
+        Mystery(
+            name="The Presentation",
+            description="Mary and Joseph present Jesus in the Temple.",
+            scripture_ref="Luke 2:22-24",
+        ),
+        Mystery(
+            name="The Finding in the Temple",
+            description="The young Jesus is found teaching in the Temple after being lost for three days.",
+            scripture_ref="Luke 2:46-49",
+        ),
+    ),
+)
+
+SORROWFUL = MysterySet(
+    name="Sorrowful Mysteries",
+    mysteries=(
+        Mystery(
+            name="The Agony in the Garden",
+            description="Jesus prays in the Garden of Gethsemane, sweating blood before his Passion.",
+            scripture_ref="Luke 22:41-44",
+        ),
+        Mystery(
+            name="The Scourging at the Pillar",
+            description="Jesus is bound and brutally scourged by Roman soldiers.",
+            scripture_ref="John 19:1",
+        ),
+        Mystery(
+            name="The Crowning with Thorns",
+            description="The soldiers place a crown of thorns on Jesus and mock him as king.",
+            scripture_ref="John 19:2-3",
+        ),
+        Mystery(
+            name="The Carrying of the Cross",
+            description="Jesus carries his cross to Calvary, falling under its weight.",
+            scripture_ref="John 19:17",
+        ),
+        Mystery(
+            name="The Crucifixion",
+            description="Jesus is nailed to the cross and dies for the sins of all humanity.",
+            scripture_ref="John 19:28-30",
+        ),
+    ),
+)
+
+GLORIOUS = MysterySet(
+    name="Glorious Mysteries",
+    mysteries=(
+        Mystery(
+            name="The Resurrection",
+            description="Jesus rises from the dead on the third day.",
+            scripture_ref="John 20:1-2",
+        ),
+        Mystery(
+            name="The Ascension",
+            description="Jesus ascends into heaven forty days after the Resurrection.",
+            scripture_ref="Acts 1:9-11",
+        ),
+        Mystery(
+            name="The Descent of the Holy Spirit",
+            description="The Holy Spirit descends on the Apostles at Pentecost.",
+            scripture_ref="Acts 2:1-4",
+        ),
+        Mystery(
+            name="The Assumption of Mary",
+            description="At the end of her earthly life, Mary is taken body and soul into heaven.",
+            scripture_ref=None,
+            scripture_note=(
+                "The Assumption is a defined dogma of the Church (Munificentissimus Deus, 1950) "
+                "rather than a direct scriptural event. Revelation 12 is understood by many "
+                "as a typological reference to Mary."
+            ),
+        ),
+        Mystery(
+            name="The Coronation of Mary",
+            description="Mary is crowned Queen of Heaven and Earth.",
+            scripture_ref=None,
+            scripture_note=(
+                "The Coronation is a defined dogma of the Church rooted in Sacred Tradition. "
+                'Revelation 12:1 — "A great sign appeared in heaven: a woman clothed with '
+                'the sun, with the moon under her feet and a crown of twelve stars on her head."'
+            ),
+        ),
+    ),
+)
+
+LUMINOUS = MysterySet(
+    name="Luminous Mysteries",
+    mysteries=(
+        Mystery(
+            name="The Baptism of Jesus",
+            description="Jesus is baptized by John in the Jordan, and the Holy Spirit descends as a dove.",
+            scripture_ref="Matthew 3:16-17",
+        ),
+        Mystery(
+            name="The Wedding at Cana",
+            description="At Mary's intercession, Jesus performs his first miracle — water into wine.",
+            scripture_ref="John 2:3-5",
+        ),
+        Mystery(
+            name="The Proclamation of the Kingdom",
+            description="Jesus preaches repentance and the coming of the Kingdom of God.",
+            scripture_ref="Mark 1:14-15",
+        ),
+        Mystery(
+            name="The Transfiguration",
+            description="Jesus is transfigured on Mount Tabor, revealing his divine glory.",
+            scripture_ref="Matthew 17:1-2",
+        ),
+        Mystery(
+            name="The Institution of the Eucharist",
+            description="At the Last Supper, Jesus institutes the Eucharist.",
+            scripture_ref="Luke 22:19-20",
+        ),
+    ),
+)
+
+ALL_SETS: dict[str, MysterySet] = {
+    "Joyful": JOYFUL,
+    "Sorrowful": SORROWFUL,
+    "Glorious": GLORIOUS,
+    "Luminous": LUMINOUS,
+}
+
+# Traditional day assignments (Luminous added by John Paul II for Thursday)
+_DAY_TO_SET: dict[int, str] = {
+    0: "Joyful",  # Monday
+    1: "Sorrowful",  # Tuesday
+    2: "Glorious",  # Wednesday
+    3: "Luminous",  # Thursday
+    4: "Sorrowful",  # Friday
+    5: "Joyful",  # Saturday
+    6: "Glorious",  # Sunday
+}
+
+
+def suggest_mystery_set() -> str:
+    """Return the key for the traditionally suggested mystery set for today."""
+    return _DAY_TO_SET[date.today().weekday()]