# feastdays 📅
A Python package for querying Catholic feast days celebrated in Opus Dei. This package provides easy access to feast day information including dates, descriptions, liturgical details, and comprehensive search capabilities.
## Features
- 🔍 Search feast days by date, title, tag, or liturgical type
- 📅 Get feast days for specific dates or today
- 🏷️ Rich metadata including liturgical colors, types, and classes
- 🔎 Case-sensitive and case-insensitive search options
- 📊 Statistical functions for calendar analysis
- 🎯 Type-safe API with full type hints
- 📚 Comprehensive docstrings and examples
## Installation
Install using pip:
```bash
pip install feastdays
```
## Quick Start
```python
from feastdays import get_feast_for_date, search_feasts_by_title, get_feast_for_today
from datetime import date
# Get feast days for a specific date (multiple formats supported)
feasts = get_feast_for_date("03-19") # March 19 - St. Joseph
feasts = get_feast_for_date("Jan 9") # January 9
feasts = get_feast_for_date(date(2024, 1, 9)) # Using date object
feasts = get_feast_for_date("9th January 2024") # With year
for feast in feasts:
print(f"{feast.title} - {feast.type}")
# Search by title
mary_feasts = search_feasts_by_title("mary")
print(f"Found {len(mary_feasts)} feasts related to Mary")
# Get today's feast days
today_feasts = get_feast_for_today()
if today_feasts:
print(f"Today's feast: {today_feasts[0].title}")
```
## API Reference
### Core Functions
#### `get_feast_for_date(date_input)`
Get all feasts for a specific date. Supports multiple date formats:
**Parameters:**
- `date_input` (Union[str, date, datetime]): Date in various formats
**Supported Date Formats:**
- `datetime.date` or `datetime.datetime` objects
- `"MM-DD"` format: `"01-09"`, `"12-25"`
- Month name formats: `"Jan 9"`, `"January 9"`, `"January 9th"`
- Day-first formats: `"9 Jan"`, `"9 January"`, `"9th January"`
- With year: `"Jan 9 2024"`, `"9th January 2024"`, `"January 1st 2024"`
**Returns:** List[Feast]
**Examples:**
```python
from datetime import date, datetime
from feastdays import get_feast_for_date
# Using date objects
feasts = get_feast_for_date(date(2024, 1, 9))
feasts = get_feast_for_date(datetime.now())
# Using MM-DD format
feasts = get_feast_for_date("01-09")
feasts = get_feast_for_date("12-25")
# Using month name formats
feasts = get_feast_for_date("Jan 9")
feasts = get_feast_for_date("January 9")
feasts = get_feast_for_date("January 9th")
# Using day-first formats
feasts = get_feast_for_date("9 Jan")
feasts = get_feast_for_date("9 January")
feasts = get_feast_for_date("9th January")
# With year included
feasts = get_feast_for_date("Jan 9 2024")
feasts = get_feast_for_date("9th January 2024")
```
#### `get_feast_for_today()`
Get all feasts for today's date.
**Returns:** List[Feast]
**Example:**
```python
from feastdays import get_feast_for_today
feasts = get_feast_for_today()
for feast in feasts:
print(f"{feast.title} ({feast.type})")
```
#### `search_feasts_by_title(keyword, case_sensitive=False)`
Search for feasts by title keyword.
**Parameters:**
- `keyword` (str): Search term to look for in feast titles
- `case_sensitive` (bool): Whether to perform case-sensitive search (default: False)
**Returns:** List[Feast]
**Example:**
```python
from feastdays import search_feasts_by_title
# Case-insensitive search
mary_feasts = search_feasts_by_title("mary")
print(f"Found {len(mary_feasts)} feasts related to Mary")
# Case-sensitive search
exact_feasts = search_feasts_by_title("Mary", case_sensitive=True)
```
#### `search_feasts_by_tag(tag, case_sensitive=False)`
Search for feasts by tag.
**Parameters:**
- `tag` (str): Tag to search for
- `case_sensitive` (bool): Whether to perform case-sensitive search (default: False)
**Returns:** List[Feast]
**Example:**
```python
from feastdays import search_feasts_by_tag
# Find all feasts of Evangelists
evangelist_feasts = search_feasts_by_tag("evangelist")
print(f"Found {len(evangelist_feasts)} feasts related to Evangelists")
# Find all Opus Dei specific celebrations
opus_dei_feasts = search_feasts_by_tag("opus dei")
for feast in opus_dei_feasts:
print(f"{feast.date}: {feast.title}")
```
#### `search_feasts_by_type(feast_type, case_sensitive=False)`
Search for feasts by liturgical type.
**Parameters:**
- `feast_type` (str): Type to search for (e.g., "Solemnity", "Memorial", "Feast")
- `case_sensitive` (bool): Whether to perform case-sensitive search (default: False)
**Returns:** List[Feast]
**Example:**
```python
from feastdays import search_feasts_by_type
# Find all Solemnities
solemnities = search_feasts_by_type("Solemnity")
# Find all Memorials (case-insensitive)
memorials = search_feasts_by_type("memorial")
```
### Utility Functions
#### `list_all_feasts()`
Get all feasts in the calendar in chronological order.
**Returns:** List[Feast]
**Example:**
```python
from feastdays import list_all_feasts
all_feasts = list_all_feasts()
print(f"Total feasts in calendar: {len(all_feasts)}")
```
#### `get_dates_with_feasts()`
Get all dates that have feast days.
**Returns:** List[str] (MM-DD format)
**Example:**
```python
from feastdays import get_dates_with_feasts
feast_dates = get_dates_with_feasts()
print(f"Calendar has feasts on {len(feast_dates)} days")
```
#### `get_feast_count()`
Get total number of individual feasts in the calendar.
**Returns:** int
**Example:**
```python
from feastdays import get_feast_count
total_feasts = get_feast_count()
print(f"Total feast entries: {total_feasts}")
```
## Data Model
### `Feast` Class
Represents a Catholic feast day with the following attributes:
```python
@dataclass
class Feast:
date: str # Date string (e.g., "January 9")
title: str # Feast title
description: str # Detailed description
color: str # Liturgical color (White, Red, etc.)
type: str # Type (Solemnity, Memorial, etc.)
class_: str # Classification (A, B, C, D, E)
tags: List[str] # Associated tags
```
**Methods:**
- `to_dict()`: Convert to dictionary
- `from_dict(data)`: Create from dictionary (class method)
**Example:**
```python
feast = get_feast_for_date("Jan 9")[0]
print(f"Title: {feast.title}")
print(f"Type: {feast.type}")
print(f"Color: {feast.color}")
print(f"Class: {feast.class_}")
print(f"Tags: {', '.join(feast.tags)}")
```
## Advanced Examples
### Search Combinations
```python
from feastdays import search_feasts_by_tag, search_feasts_by_type
# Find all Marian solemnities
marian_feasts = search_feasts_by_tag("mary")
solemnities = search_feasts_by_type("Solemnity")
marian_solemnities = [f for f in marian_feasts if f in solemnities]
# Get all Opus Dei specific celebrations
opus_dei_feasts = search_feasts_by_tag("opus dei")
for feast in opus_dei_feasts:
print(f"{feast.date}: {feast.title}")
```
### Calendar Statistics
```python
from feastdays import get_feast_count, get_dates_with_feasts, list_all_feasts
# Basic statistics
total_feasts = get_feast_count()
total_dates = len(get_dates_with_feasts())
print(f"Total feasts: {total_feasts}")
print(f"Days with feasts: {total_dates}")
# Feast type distribution
all_feasts = list_all_feasts()
types = {}
for feast in all_feasts:
feast_type = feast.type or "Unspecified"
types[feast_type] = types.get(feast_type, 0) + 1
for feast_type, count in sorted(types.items()):
print(f"{feast_type}: {count}")
```
## Error Handling
The library raises specific exceptions for different error conditions:
```python
from feastdays import get_feast_for_date
try:
feasts = get_feast_for_date("invalid date")
except ValueError as e:
print(f"Date parsing error: {e}")
try:
feasts = get_feast_for_date("Jan 9")
except FileNotFoundError as e:
print(f"Data file not found: {e}")
except json.JSONDecodeError as e:
print(f"Invalid JSON data: {e}")
```
## Date Format Reference
| Format Type | Examples |
|-------------|----------|
| Date Objects | `date(2024, 1, 9)`, `datetime.now()` |
| MM-DD | `"01-09"`, `"12-25"` |
| Month Day | `"Jan 9"`, `"January 9"`, `"January 9th"` |
| Day Month | `"9 Jan"`, `"9 January"`, `"9th January"` |
| With Year | `"Jan 9 2024"`, `"9th January 2024"`, `"January 1st 2024"` |
**Note:** The library automatically handles ordinal suffixes (st, nd, rd, th) and is case-insensitive for month names.
## Data Source
The feast day data is maintained in `feastdays/data/feast_days.json` and includes:
- Universal Catholic feast days
- Opus Dei specific celebrations
- Saints particularly venerated in Opus Dei
- Liturgical seasons and special observances
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": "https://github.com/okonma01/feast-days",
"name": "feastdays",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "feastdays catholic feast days opus dei liturgical calendar saints",
"author": "Daniel Okonma",
"author_email": "danielokonma@yahoo.com",
"download_url": "https://files.pythonhosted.org/packages/00/a5/87ba73cc47d66f26a749aabae075641a48fe19a0065e13414b0845a85d56/feastdays-1.1.0.tar.gz",
"platform": null,
"description": "# feastdays \ud83d\udcc5\n\nA Python package for querying Catholic feast days celebrated in Opus Dei. This package provides easy access to feast day information including dates, descriptions, liturgical details, and comprehensive search capabilities.\n\n## Features\n\n- \ud83d\udd0d Search feast days by date, title, tag, or liturgical type\n- \ud83d\udcc5 Get feast days for specific dates or today\n- \ud83c\udff7\ufe0f Rich metadata including liturgical colors, types, and classes\n- \ud83d\udd0e Case-sensitive and case-insensitive search options\n- \ud83d\udcca Statistical functions for calendar analysis\n- \ud83c\udfaf Type-safe API with full type hints\n- \ud83d\udcda Comprehensive docstrings and examples\n\n## Installation\n\nInstall using pip:\n\n```bash\npip install feastdays\n```\n\n## Quick Start\n\n```python\nfrom feastdays import get_feast_for_date, search_feasts_by_title, get_feast_for_today\nfrom datetime import date\n\n# Get feast days for a specific date (multiple formats supported)\nfeasts = get_feast_for_date(\"03-19\") # March 19 - St. Joseph\nfeasts = get_feast_for_date(\"Jan 9\") # January 9\nfeasts = get_feast_for_date(date(2024, 1, 9)) # Using date object\nfeasts = get_feast_for_date(\"9th January 2024\") # With year\nfor feast in feasts:\n print(f\"{feast.title} - {feast.type}\")\n\n# Search by title\nmary_feasts = search_feasts_by_title(\"mary\")\nprint(f\"Found {len(mary_feasts)} feasts related to Mary\")\n\n# Get today's feast days\ntoday_feasts = get_feast_for_today()\nif today_feasts:\n print(f\"Today's feast: {today_feasts[0].title}\")\n```\n\n## API Reference\n\n### Core Functions\n\n#### `get_feast_for_date(date_input)`\n\nGet all feasts for a specific date. Supports multiple date formats:\n\n**Parameters:**\n- `date_input` (Union[str, date, datetime]): Date in various formats\n\n**Supported Date Formats:**\n- `datetime.date` or `datetime.datetime` objects\n- `\"MM-DD\"` format: `\"01-09\"`, `\"12-25\"`\n- Month name formats: `\"Jan 9\"`, `\"January 9\"`, `\"January 9th\"`\n- Day-first formats: `\"9 Jan\"`, `\"9 January\"`, `\"9th January\"`\n- With year: `\"Jan 9 2024\"`, `\"9th January 2024\"`, `\"January 1st 2024\"`\n\n**Returns:** List[Feast]\n\n**Examples:**\n```python\nfrom datetime import date, datetime\nfrom feastdays import get_feast_for_date\n\n# Using date objects\nfeasts = get_feast_for_date(date(2024, 1, 9))\nfeasts = get_feast_for_date(datetime.now())\n\n# Using MM-DD format\nfeasts = get_feast_for_date(\"01-09\")\nfeasts = get_feast_for_date(\"12-25\")\n\n# Using month name formats\nfeasts = get_feast_for_date(\"Jan 9\")\nfeasts = get_feast_for_date(\"January 9\")\nfeasts = get_feast_for_date(\"January 9th\")\n\n# Using day-first formats\nfeasts = get_feast_for_date(\"9 Jan\")\nfeasts = get_feast_for_date(\"9 January\")\nfeasts = get_feast_for_date(\"9th January\")\n\n# With year included\nfeasts = get_feast_for_date(\"Jan 9 2024\")\nfeasts = get_feast_for_date(\"9th January 2024\")\n```\n\n#### `get_feast_for_today()`\n\nGet all feasts for today's date.\n\n**Returns:** List[Feast]\n\n**Example:**\n```python\nfrom feastdays import get_feast_for_today\n\nfeasts = get_feast_for_today()\nfor feast in feasts:\n print(f\"{feast.title} ({feast.type})\")\n```\n\n#### `search_feasts_by_title(keyword, case_sensitive=False)`\n\nSearch for feasts by title keyword.\n\n**Parameters:**\n- `keyword` (str): Search term to look for in feast titles\n- `case_sensitive` (bool): Whether to perform case-sensitive search (default: False)\n\n**Returns:** List[Feast]\n\n**Example:**\n```python\nfrom feastdays import search_feasts_by_title\n\n# Case-insensitive search\nmary_feasts = search_feasts_by_title(\"mary\")\nprint(f\"Found {len(mary_feasts)} feasts related to Mary\")\n\n# Case-sensitive search\nexact_feasts = search_feasts_by_title(\"Mary\", case_sensitive=True)\n```\n\n#### `search_feasts_by_tag(tag, case_sensitive=False)`\n\nSearch for feasts by tag.\n\n**Parameters:**\n- `tag` (str): Tag to search for\n- `case_sensitive` (bool): Whether to perform case-sensitive search (default: False)\n\n**Returns:** List[Feast]\n\n**Example:**\n```python\nfrom feastdays import search_feasts_by_tag\n\n# Find all feasts of Evangelists\nevangelist_feasts = search_feasts_by_tag(\"evangelist\")\nprint(f\"Found {len(evangelist_feasts)} feasts related to Evangelists\")\n\n# Find all Opus Dei specific celebrations\nopus_dei_feasts = search_feasts_by_tag(\"opus dei\")\nfor feast in opus_dei_feasts:\n print(f\"{feast.date}: {feast.title}\")\n```\n\n#### `search_feasts_by_type(feast_type, case_sensitive=False)`\n\nSearch for feasts by liturgical type.\n\n**Parameters:**\n- `feast_type` (str): Type to search for (e.g., \"Solemnity\", \"Memorial\", \"Feast\")\n- `case_sensitive` (bool): Whether to perform case-sensitive search (default: False)\n\n**Returns:** List[Feast]\n\n**Example:**\n```python\nfrom feastdays import search_feasts_by_type\n\n# Find all Solemnities\nsolemnities = search_feasts_by_type(\"Solemnity\")\n\n# Find all Memorials (case-insensitive)\nmemorials = search_feasts_by_type(\"memorial\")\n```\n\n### Utility Functions\n\n#### `list_all_feasts()`\n\nGet all feasts in the calendar in chronological order.\n\n**Returns:** List[Feast]\n\n**Example:**\n```python\nfrom feastdays import list_all_feasts\n\nall_feasts = list_all_feasts()\nprint(f\"Total feasts in calendar: {len(all_feasts)}\")\n```\n\n#### `get_dates_with_feasts()`\n\nGet all dates that have feast days.\n\n**Returns:** List[str] (MM-DD format)\n\n**Example:**\n```python\nfrom feastdays import get_dates_with_feasts\n\nfeast_dates = get_dates_with_feasts()\nprint(f\"Calendar has feasts on {len(feast_dates)} days\")\n```\n\n#### `get_feast_count()`\n\nGet total number of individual feasts in the calendar.\n\n**Returns:** int\n\n**Example:**\n```python\nfrom feastdays import get_feast_count\n\ntotal_feasts = get_feast_count()\nprint(f\"Total feast entries: {total_feasts}\")\n```\n\n## Data Model\n\n### `Feast` Class\n\nRepresents a Catholic feast day with the following attributes:\n\n```python\n@dataclass\nclass Feast:\n date: str # Date string (e.g., \"January 9\")\n title: str # Feast title\n description: str # Detailed description\n color: str # Liturgical color (White, Red, etc.)\n type: str # Type (Solemnity, Memorial, etc.)\n class_: str # Classification (A, B, C, D, E)\n tags: List[str] # Associated tags\n```\n\n**Methods:**\n- `to_dict()`: Convert to dictionary\n- `from_dict(data)`: Create from dictionary (class method)\n\n**Example:**\n```python\nfeast = get_feast_for_date(\"Jan 9\")[0]\nprint(f\"Title: {feast.title}\")\nprint(f\"Type: {feast.type}\")\nprint(f\"Color: {feast.color}\")\nprint(f\"Class: {feast.class_}\")\nprint(f\"Tags: {', '.join(feast.tags)}\")\n```\n\n## Advanced Examples\n\n### Search Combinations\n\n```python\nfrom feastdays import search_feasts_by_tag, search_feasts_by_type\n\n# Find all Marian solemnities\nmarian_feasts = search_feasts_by_tag(\"mary\")\nsolemnities = search_feasts_by_type(\"Solemnity\")\nmarian_solemnities = [f for f in marian_feasts if f in solemnities]\n\n# Get all Opus Dei specific celebrations\nopus_dei_feasts = search_feasts_by_tag(\"opus dei\")\nfor feast in opus_dei_feasts:\n print(f\"{feast.date}: {feast.title}\")\n```\n\n### Calendar Statistics\n\n```python\nfrom feastdays import get_feast_count, get_dates_with_feasts, list_all_feasts\n\n# Basic statistics\ntotal_feasts = get_feast_count()\ntotal_dates = len(get_dates_with_feasts())\nprint(f\"Total feasts: {total_feasts}\")\nprint(f\"Days with feasts: {total_dates}\")\n\n# Feast type distribution\nall_feasts = list_all_feasts()\ntypes = {}\nfor feast in all_feasts:\n feast_type = feast.type or \"Unspecified\"\n types[feast_type] = types.get(feast_type, 0) + 1\n\nfor feast_type, count in sorted(types.items()):\n print(f\"{feast_type}: {count}\")\n```\n\n## Error Handling\n\nThe library raises specific exceptions for different error conditions:\n\n```python\nfrom feastdays import get_feast_for_date\n\ntry:\n feasts = get_feast_for_date(\"invalid date\")\nexcept ValueError as e:\n print(f\"Date parsing error: {e}\")\n\ntry:\n feasts = get_feast_for_date(\"Jan 9\")\nexcept FileNotFoundError as e:\n print(f\"Data file not found: {e}\")\nexcept json.JSONDecodeError as e:\n print(f\"Invalid JSON data: {e}\")\n```\n\n## Date Format Reference\n\n| Format Type | Examples |\n|-------------|----------|\n| Date Objects | `date(2024, 1, 9)`, `datetime.now()` |\n| MM-DD | `\"01-09\"`, `\"12-25\"` |\n| Month Day | `\"Jan 9\"`, `\"January 9\"`, `\"January 9th\"` |\n| Day Month | `\"9 Jan\"`, `\"9 January\"`, `\"9th January\"` |\n| With Year | `\"Jan 9 2024\"`, `\"9th January 2024\"`, `\"January 1st 2024\"` |\n\n**Note:** The library automatically handles ordinal suffixes (st, nd, rd, th) and is case-insensitive for month names.\n\n## Data Source\n\nThe feast day data is maintained in `feastdays/data/feast_days.json` and includes:\n\n- Universal Catholic feast days\n- Opus Dei specific celebrations\n- Saints particularly venerated in Opus Dei\n- Liturgical seasons and special observances\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python package for feast days celebrated in Opus Dei",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/okonma01/feast-days"
},
"split_keywords": [
"feastdays",
"catholic",
"feast",
"days",
"opus",
"dei",
"liturgical",
"calendar",
"saints"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d6a524bb991925c8547670392879bbc91438deda33042e27887f66b35faca344",
"md5": "019a991ff701ac413f30e6c62e81adc0",
"sha256": "17be2fc9529d24723de4ffa6e7ef6f879a7098467b65fb2626edc409b7fecbcc"
},
"downloads": -1,
"filename": "feastdays-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "019a991ff701ac413f30e6c62e81adc0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 29428,
"upload_time": "2025-07-28T14:42:19",
"upload_time_iso_8601": "2025-07-28T14:42:19.221729Z",
"url": "https://files.pythonhosted.org/packages/d6/a5/24bb991925c8547670392879bbc91438deda33042e27887f66b35faca344/feastdays-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "00a587ba73cc47d66f26a749aabae075641a48fe19a0065e13414b0845a85d56",
"md5": "249682c8a363116a0112709668a25db3",
"sha256": "07b58b2b3fdf476657285959bb6145185c00c4e7932df99883def73a73ec7752"
},
"downloads": -1,
"filename": "feastdays-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "249682c8a363116a0112709668a25db3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 31423,
"upload_time": "2025-07-28T14:42:20",
"upload_time_iso_8601": "2025-07-28T14:42:20.404653Z",
"url": "https://files.pythonhosted.org/packages/00/a5/87ba73cc47d66f26a749aabae075641a48fe19a0065e13414b0845a85d56/feastdays-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 14:42:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "okonma01",
"github_project": "feast-days",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "feastdays"
}
JSON
