hebcal-api 0.2.0

Async client for Hebcal API

Hebcal API Client

A comprehensive, production-grade Python client for the Hebcal Jewish Calendar API. Modernized with Pydantic v2, httpx, and strict type safety.

Features

• 🗓️ Functional API - Clean, functional interface for all Hebcal endpoints.
• ✅ Pydantic Validation - Type-safe request models with automatic parameter validation.
• 🇮🇱 Clean Hebrew Output - Specialized formatters that prioritize clean, nikud-free Hebrew text.
• 🕯️ Advanced Shabbat & Zmanim - Precise halachic times for any location worldwide.
• 🌾 Omer Support - Full support for fetching and formatting the daily Omer count.
• ⚡ Async Native - Built on httpx for high-performance asynchronous operations.
• 📍 Flattened Location Support - Direct use of Geonames, coordinates, or city names.

Installation

pip install hebcal-api

Or with uv:

uv add hebcal-api

Quick Start

Basic Calendar Usage

Get Jewish holidays and events for any location.

from hebcal_api import CalendarRequest, fetch_calendar
from hebcal_api.utils.calendar_formatter import format_calendar_events

# Create a request for Jerusalem
request = CalendarRequest(
    location="Jerusalem",
    geonameid=281184,
    maj=True,    # Major holidays
    min=True     # Minor holidays
)

# Fetch data synchronously
response = fetch_calendar(request)

# Format for display (Always clean Hebrew by default)
print(format_calendar_events(response))

Shabbat Times

Fetch candle lighting and Havdalah times.

from hebcal_api import ShabbatRequest, fetch_shabbat

request = ShabbatRequest(
    geonameid=5128581,  # New York City
    c=True,             # Candle lighting
    s=True              # Shabbat info
)

response = fetch_shabbat(request)

for event in response.items:
    print(f"{event.title}: {event.date}")

Omer Count Today

Easily track the daily Omer count.

from hebcal_api import CalendarRequest, fetch_calendar

request = CalendarRequest(o=True)  # Enable Omer count
response = fetch_calendar(request)

# Find the Omer event
omer_event = next((i for i in response.items if i.type == "omer"), None)
if omer_event:
    print(f"Today is: {omer_event.title}")

Async Usage

Full async support for integration into modern web frameworks.

import asyncio
from hebcal_api import CalendarRequest, fetch_calendar_async

async def main():
    request = CalendarRequest(geonameid=281184)
    response = await fetch_calendar_async(request)
    
    for event in response.items:
        print(f"{event.title} - {event.hebrew}")

asyncio.run(main())

API Reference

Functional Interface

The library provides high-level fetch_* functions for both sync and async execution:

Endpoint	Sync Function	Async Function
/hebcal	fetch_calendar	fetch_calendar_async
/shabbat	fetch_shabbat	fetch_shabbat_async
/zmanim	fetch_zmanim	fetch_zmanim_async
/converter	fetch_converter	fetch_converter_async
/yahrzeit	fetch_yahrzeit	fetch_yahrzeit_async
/leyning	fetch_leyning	fetch_leyning_async

Unified Client

For custom network configuration, use the HebcalClient:

from hebcal_api import HebcalClient

# Configure custom timeout or headers
response = HebcalClient.execute(
    endpoint=Endpoint.CALENDAR,
    request=request,
    response_model=CalendarResponse,
    timeout=30
)

Error Handling

The library uses a hierarchy of specific exceptions:

• HebcalError: Base exception for all library errors.
• HebcalNetworkError: Raised for HTTP connection or status code failures.
• HebcalValidationError: Raised when request parameters are invalid (e.g., missing location).
• HebcalParseError: Raised when the API response cannot be parsed into the expected models.

Formatting Utilities

Located in hebcal_api.utils.calendar_formatter, these helper functions turn raw data into professional messages.

• format_calendar_events(response): Returns a beautiful, multi-line string of events.
• remove_hebrew_nikud(text): Manually strip diacritics from any Hebrew string.

Development

Set up the project using uv:

git clone https://github.com/sudo-py-dev/hebcal-api.git
cd hebcal-api
uv sync

Code Quality

We enforce strict linting and type checking:

uv run ruff check      # Linting
uv run ruff format     # Formatting
uv run pyright src/    # Type safety
uv run pytest          # Testing

License

MIT License. See LICENSE for details.

Support

• 📧 Email: [e-mail]
• 🐛 GitHub Issues
• 📖 Official API Documentation