# widetorah

[![PyPI](https://img.shields.io/pypi/v/widetorah)](https://pypi.org/project/widetorah/)
[![Python](https://img.shields.io/pypi/pyversions/widetorah)](https://pypi.org/project/widetorah/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Python SDK for **[WideTorah](https://widetorah.com)** — access Torah verses, Talmud daf pages, Rashi commentary, weekly parashot, Jewish holidays, biblical figures, and glossary terms through a clean Python API. Built on `httpx` with full type hints and a rich CLI.

WideTorah provides structured access to the Jewish scriptural canon: **24 books** of the Tanakh with **69,616 verses** across 3 translations (Masoretic Hebrew, JPS-1917, Koren), **54 weekly parashot**, **2,121 Talmud daf** pages across 63 tractates, **3,901 Rashi commentary** entries, and **10 Jewish holidays** — all from the [widetorah.com](https://widetorah.com) REST API.

> **Explore the Torah online at [widetorah.com](https://widetorah.com)** — verse-by-verse reading, Talmud daf browser, parashah calendar, and Jewish encyclopedia.

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You'll Find on WideTorah](#what-youll-find-on-widetorah)
  - [Tanakh Structure](#tanakh-structure)
  - [Weekly Parashot](#weekly-parashot)
  - [Talmud & Mishnah](#talmud--mishnah)
  - [Rashi Commentary](#rashi-commentary)
  - [Jewish Holidays & Biblical Figures](#jewish-holidays--biblical-figures)
- [Command-Line Interface](#command-line-interface)
- [API Reference](#api-reference)
- [API Endpoints](#api-endpoints)
- [Learn More About the Torah](#learn-more-about-the-torah)
- [WideHoly Developer Tools](#wideholy-developer-tools)
- [License](#license)

## Install

```bash
# Core SDK (httpx)
pip install widetorah

# With CLI (rich tables in your terminal)
pip install widetorah[cli]

# Everything
pip install widetorah[all]
```

## Quick Start

```python
from widetorah import WideTorah

with WideTorah() as client:
    # Get Genesis 1:1 in JPS-1917 translation
    verse = client.get_verse("genesis", 1, 1)
    print(verse)
    # {'results': [{'reference': 'Genesis 1:1', 'text': 'In the beginning God created...', 'text_hebrew': 'בְּרֵאשִׁית בָּרָא אֱלֹהִים...'}]}

    # Browse weekly Torah portions
    parashot = client.list_parashot(book="genesis")
    print(parashot)
    # {'results': [{'name': 'Bereshit', 'hebrew_name': 'בראשית', 'reference': 'Genesis 1:1–6:8'}, ...]}

    # Study Talmud — Berakhot 2a
    daf = client.get_talmud_daf("berakhot", 2, side="a")
    print(daf)
    # {'results': [{'tractate_slug': 'berakhot', 'number': 2, 'side': 'a', 'text_hebrew': '...', 'text_english': '...'}]}

    # Search for verses about covenant
    results = client.search("covenant", limit=5)
    for v in results.get("results", []):
        print(f"{v['reference']}: {v['text'][:80]}...")
```

## What You'll Find on WideTorah

### Tanakh Structure

The Hebrew Bible (Tanakh) is organized into three divisions containing 24 books:

| Division | Hebrew | Books | Description |
|----------|--------|-------|-------------|
| **Torah** | תורה | 5 | The Five Books of Moses — Genesis through Deuteronomy |
| **Nevi'im** | נביאים | 8 | The Prophets — Joshua, Judges, Samuel, Kings, Isaiah, Jeremiah, Ezekiel, Twelve |
| **Ketuvim** | כתובים | 11 | The Writings — Psalms, Proverbs, Job, Song of Songs, Ruth, Lamentations, Ecclesiastes, Esther, Daniel, Ezra-Nehemiah, Chronicles |

WideTorah serves 69,616 verses across 3 translations:

| Translation | Code | Language | Notes |
|-------------|------|----------|-------|
| **Masoretic Hebrew** | `masoretic` | Hebrew | Original consonantal text with vowel pointing (nikkud) |
| **JPS 1917** | `jps-1917` | English | Jewish Publication Society classic English translation |
| **Koren** | `koren` | English | Modern Koren Publishers Jerusalem translation |

```python
# List all books in the Torah (Pentateuch)
torah_books = client.list_books(section="torah")
for book in torah_books["results"]:
    print(f"{book['name']} ({book['hebrew_name']}) — {book['chapter_count']} chapters, {book['verse_count']} verses")
    # Genesis (בראשית) — 50 chapters, 1533 verses
    # Exodus (שמות) — 40 chapters, 1213 verses
    # ...
```

### Weekly Parashot

The Torah is divided into **54 weekly reading portions** (parashot, singular parashah), completing the entire Torah in an annual cycle. Each Shabbat, a designated portion is read publicly in synagogue from the Torah scroll.

The annual reading cycle begins and ends on Simchat Torah. In leap years all 54 portions are read individually; in regular years some portions are combined (doubled) to fit the shorter calendar.

| Book | Parashot | Example |
|------|----------|---------|
| Genesis | 12 portions | Bereshit, Noach, Lech Lecha, Vayera... |
| Exodus | 11 portions | Shemot, Va'era, Bo, Beshalach... |
| Leviticus | 10 portions | Vayikra, Tzav, Shemini... |
| Numbers | 10 portions | Bamidbar, Naso, Beha'alotcha... |
| Deuteronomy | 11 portions | Devarim, Va'etchanan, Eikev... |

```python
# Get details of the first parashah — Bereshit (Genesis 1:1–6:8)
bereshit = client.get_parashah("bereshit")
print(f"{bereshit['name']} ({bereshit['hebrew_name']})")
print(f"Reference: {bereshit['reference']}")
# Bereshit (בראשית)
# Reference: Genesis 1:1–6:8
```

### Talmud & Mishnah

The **Talmud** (Babylonian Talmud, Talmud Bavli) is the central text of Rabbinic Judaism, consisting of the **Mishnah** (oral law codified c. 200 CE) and the **Gemara** (rabbinical analysis and commentary, c. 500 CE). It is organized into 6 orders (sedarim) containing 63 tractates.

| Seder | Hebrew | Tractates | Subject |
|-------|--------|-----------|---------|
| **Zeraim** | זרעים | 11 | Agriculture, blessings, tithes |
| **Moed** | מועד | 12 | Shabbat, festivals, fast days |
| **Nashim** | נשים | 7 | Marriage, divorce, vows |
| **Nezikin** | נזיקין | 10 | Civil/criminal law, ethics (Avot) |
| **Kodashim** | קדשים | 11 | Temple service, sacrifices, kashrut |
| **Tohorot** | טהרות | 12 | Ritual purity and impurity |

The Talmud is studied page by page — each folio (daf) has two sides (amud aleph/bet, or a/b). The worldwide **Daf Yomi** program completes the entire Talmud in a 7.5-year cycle, studying one daf per day (2,711 pages total).

```python
# Browse tractates in Seder Moed (Festivals)
moed = client.list_tractates(seder="moed")
for t in moed["results"]:
    print(f"{t['name']} ({t['hebrew_name']}) — {t['daf_count']} daf")
    # Shabbat (שבת) — 157 daf
    # Eruvin (עירובין) — 105 daf
    # ...

# Read Talmud Berakhot 2a — the very first page of the Talmud
daf = client.get_talmud_daf("berakhot", 2, side="a")
# Contains text_hebrew, text_english, text_aramaic

# List Mishnah chapters for a tractate
mishnah = client.list_mishnah(tractate="berakhot")
```

### Rashi Commentary

**Rashi** (Rabbi Shlomo Yitzchaki, 1040–1105 CE, Troyes, France) wrote the most widely studied commentary on the Torah and Talmud. His Torah commentary is printed alongside the biblical text in virtually every edition of the Chumash.

Rashi's commentary is known for its conciseness, drawing on Midrash and Talmud to explain the plain meaning (peshat) of the text. WideTorah provides **3,901 Rashi commentary entries** covering the Five Books of Moses, with both the original Hebrew and English translation.

```python
# Get Rashi's commentary on Genesis chapter 1
rashi_gen1 = client.list_rashi(book="genesis", chapter=1)
for entry in rashi_gen1["results"]:
    print(f"  Verses {entry['verse_start']}–{entry['verse_end']}: {entry['text_english'][:100]}...")
```

### Jewish Holidays & Biblical Figures

WideTorah covers the major Jewish holidays with their Torah readings, haftarah portions, and Hebrew calendar dates:

| Holiday | Hebrew | Category | Torah Reading |
|---------|--------|----------|---------------|
| **Rosh Hashanah** | ראש השנה | Biblical | Genesis 21–22 |
| **Yom Kippur** | יום כיפור | Biblical | Leviticus 16 |
| **Sukkot** | סוכות | Biblical | Leviticus 22:26–23:44 |
| **Pesach** | פסח | Biblical | Exodus 12:21–51 |
| **Shavuot** | שבועות | Biblical | Exodus 19–20 |
| **Hanukkah** | חנוכה | Rabbinic | Numbers 7 |
| **Purim** | פורים | Rabbinic | Exodus 17:8–16 |
| **Tisha B'Av** | תשעה באב | Rabbinic | Deuteronomy 4:25–40 |

Biblical figures span the entire narrative from the Patriarchs through the Second Temple period — Abraham, Moses, David, Solomon, Elijah, Isaiah, Esther, Daniel, and more.

```python
# List biblical holidays
holidays = client.list_holidays(category="biblical")

# Explore the patriarchs
patriarchs = client.list_figures(era="patriarchs")
for f in patriarchs["results"]:
    print(f"{f['name']} ({f['hebrew_name']}) — {f['era']}")

# Get details of a specific figure
moses = client.get_figure("moses")
print(f"{moses['name']}: {moses['description']}")
```

## Command-Line Interface

Install with CLI extras: `pip install widetorah[cli]`

```bash
# Look up a specific verse
widetorah verse genesis 1 1
# Genesis 1:1
# בְּרֵאשִׁית בָּרָא אֱלֹהִים אֵת הַשָּׁמַיִם וְאֵת הָאָרֶץ
# In the beginning God created the heaven and the earth.

# Get parashah details
widetorah parashah bereshit

# Read Talmud daf
widetorah daf berakhot 2 a

# Search Torah verses
widetorah search "covenant" --limit 10

# List Tanakh books (filter by section)
widetorah books --section torah

# List Talmud tractates (filter by seder)
widetorah tractates --seder moed

# List Jewish holidays
widetorah holidays --category biblical

# List biblical figures
widetorah figures --era patriarchs
```

## API Reference

### Client Methods

| Method | Description | Returns |
|--------|-------------|---------|
| `list_books(section=)` | List 24 Tanakh books, filter by section | Paginated list |
| `get_book(slug)` | Book details (name, hebrew_name, chapter/verse counts) | Single book |
| `list_translations()` | Available translations (JPS-1917, Koren, Masoretic) | Paginated list |
| `list_chapters(book=)` | Chapters, filter by book slug | Paginated list |
| `get_verse(book, chapter, verse, translation=)` | Specific verse with Hebrew and translation | Verse result |
| `search(query, limit=)` | Full-text search across Torah verses | Paginated list |
| `list_parashot(book=)` | 54 weekly Torah portions, filter by book | Paginated list |
| `get_parashah(slug)` | Parashah details with reference range | Single parashah |
| `list_tractates(seder=)` | 63 Talmud tractates, filter by seder | Paginated list |
| `get_talmud_daf(tractate, daf, side=)` | Talmud folio page (Hebrew, English, Aramaic) | Daf result |
| `list_mishnah(tractate=)` | Mishnah chapters, filter by tractate | Paginated list |
| `list_rashi(book=, chapter=)` | 3,901 Rashi commentaries, filter by book/chapter | Paginated list |
| `list_holidays(category=)` | Jewish holidays, filter by category | Paginated list |
| `list_figures(era=)` | Biblical figures, filter by era | Paginated list |
| `get_figure(slug)` | Figure details (name, hebrew_name, era, is_prophet) | Single figure |
| `list_topics()` | Thematic topics (covenant, creation, law) | Paginated list |
| `list_glossary()` | Hebrew/Aramaic glossary terms | Paginated list |

## API Endpoints

All endpoints are under `https://widetorah.com/api/v1/torah/`:

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/books/` | List Tanakh books (filter: `section`) |
| GET | `/books/{slug}/` | Book details |
| GET | `/translations/` | List translations |
| GET | `/translations/{code}/` | Translation details |
| GET | `/chapters/` | List chapters (filter: `book__slug`) |
| GET | `/verses/` | List/search verses (filter: `chapter__book__slug`, `translation__code`, `search`) |
| GET | `/parashot/` | List parashot (filter: `book__slug`) |
| GET | `/parashot/{slug}/` | Parashah details |
| GET | `/tractates/` | List tractates (filter: `seder`) |
| GET | `/tractates/{slug}/` | Tractate details |
| GET | `/dapim/` | List Talmud daf (filter: `tractate__slug`, `number`, `side`) |
| GET | `/mishnah/` | List Mishnah chapters (filter: `tractate__slug`) |
| GET | `/rashi/` | List Rashi commentary (filter: `book__slug`, `chapter`) |
| GET | `/holidays/` | List holidays (filter: `category`) |
| GET | `/holidays/{slug}/` | Holiday details |
| GET | `/figures/` | List biblical figures (filter: `era`, `is_prophet`) |
| GET | `/figures/{slug}/` | Figure details |
| GET | `/topics/` | List topics |
| GET | `/topics/{slug}/` | Topic details |
| GET | `/glossary/` | List glossary terms |
| GET | `/glossary/{slug}/` | Glossary term details |

### Example

```bash
curl -s "https://widetorah.com/api/v1/torah/books/genesis/"
```

```json
{
  "id": 1,
  "name": "Genesis",
  "slug": "genesis",
  "hebrew_name": "בראשית",
  "number": 1,
  "section": "torah",
  "chapter_count": 50,
  "verse_count": 1533,
  "description": "The first book of the Torah...",
  "url": "/torah/genesis/"
}
```

Full API documentation at [widetorah.com/developers/](https://widetorah.com/developers/).
OpenAPI 3.1.0 spec: [widetorah.com/api/schema/](https://widetorah.com/api/schema/).

## Learn More About the Torah

- **Scripture**: [Torah Books](https://widetorah.com/) · [Parashot](https://widetorah.com/parashot/) · [Translations](https://widetorah.com/translations/)
- **Talmud**: [Tractates](https://widetorah.com/talmud/) · [Rashi Commentary](https://widetorah.com/talmud/)
- **Reference**: [Figures](https://widetorah.com/figures/) · [Holidays](https://widetorah.com/holidays/) · [Glossary](https://widetorah.com/glossary/)
- **Tools**: [Developers](https://widetorah.com/developers/)
- **API**: [OpenAPI Spec](https://widetorah.com/api/schema/)

## WideHoly Developer Tools

| Package | PyPI | Description |
|---------|------|-------------|
| **widetorah** | [PyPI](https://pypi.org/project/widetorah/) | Torah, Talmud, Rashi commentary — [widetorah.com](https://widetorah.com) |
| widebible | [PyPI](https://pypi.org/project/widebible/) | Bible verses, cross-references, study tools — [widebible.com](https://widebible.com) |
| widequran | [PyPI](https://pypi.org/project/widequran/) | Quran, Hadith, Tafsir commentary — [widequran.com](https://widequran.com) |
| widesutra | [PyPI](https://pypi.org/project/widesutra/) | Buddhist sutras, Tipitaka, Pali Canon — [widesutra.com](https://widesutra.com) |
| widegita | [PyPI](https://pypi.org/project/widegita/) | Bhagavad Gita, Vedic philosophy — [widegita.com](https://widegita.com) |
| wideholy | [PyPI](https://pypi.org/project/wideholy/) | Unified multi-religion scripture SDK — [wideholy.com](https://wideholy.com) |

Part of the [WideHoly](https://wideholy.com) open-source scripture tools ecosystem.

## License

MIT License — see [LICENSE](LICENSE) for details.
