# gracenote2epg - TV Guide Grabber for North America
> **📦 PyPI Status**: Now available on PyPI! Install with `pip install gracenote2epg[full]`
A modern Python implementation for downloading TV guide data from tvlistings.gracenote.com with intelligent caching and TVheadend integration.
[](https://www.python.org/downloads/)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://pypi.org/project/gracenote2epg/)
[](https://github.com/th0ma7/gracenote2epg)
## 🌟 Key Features
- **XMLTV Standard Compliant** - Full DTD compliance for maximum compatibility
- **Intelligent Caching** - 95%+ cache efficiency with smart refresh strategies
- **Multi-language Support** - Automatic French/English/Spanish detection and translations
- **TVheadend Integration** - Seamless channel filtering and matching
- **Unified Cache Management** - Streamlined configuration for all retention policies
- **Platform Agnostic** - Auto-detection for Raspberry Pi, Synology NAS, and Linux
## 🚀 Installation
```bash
# Recommended: Install with all features
pip install gracenote2epg[full]
# Basic installation (core features only)
pip install gracenote2epg
# Alternative: Install from GitHub
pip install "gracenote2epg[full] @ git+https://github.com/th0ma7/gracenote2epg.git@v1.5.4"
```
### 📦 Development Installation
```bash
# Install from GitHub (latest)
pip install "gracenote2epg[dev] @ git+https://github.com/th0ma7/gracenote2epg.git"
# Clone and install for development
git clone https://github.com/th0ma7/gracenote2epg.git
cd gracenote2epg
pip install -e .[dev]
```
## 📋 System Requirements
- **Python**: 3.7 or higher
- **Required**: `requests>=2.25.0`
- **Optional**: `langdetect>=1.0.9` (language detection), `polib>=1.1.0` (translations)
## 🛠️ Quick Examples
### Command Line Examples
```bash
# Show capabilities (XMLTV standard)
tv_grab_gracenote2epg --capabilities
# Download 7 days of guide data
tv_grab_gracenote2epg --days 7 --zip 92101
# Test lineup detection
tv_grab_gracenote2epg --show-lineup --zip 92101
# Canadian postal code with console output
tv_grab_gracenote2epg --days 3 --postal J3B1M4 --console
# Save to custom file with debug info
tv_grab_gracenote2epg --days 7 --zip 92101 --output guide.xml --debug
# Use specific lineup (auto-extracts location)
tv_grab_gracenote2epg --days 7 --lineupid CAN-OTAJ3B1M4
# Disable language detection
tv_grab_gracenote2epg --days 7 --zip 92101 --langdetect false
```
### Configuration
> **💡 TVheadend Users - Easy Setup**: Most users don't need to edit configuration files! Simply use TVheadend's **Extra arguments** box to add your parameters like `--days 7 --zip 92101 --langdetect false` (Configuration → Channel/EPG → EPG Grabber Modules). See **[TVheadend Integration Guide](https://github.com/th0ma7/gracenote2epg/blob/main/docs/tvheadend.md)** for details.
### TVheadend Integration Examples
```bash
# In TVheadend Extra arguments box:
--days 7 --zip 92101
--days 14 --postal J3B1M4 --langdetect false
--days 7 --zip 90210 --lineupid auto
```
> **Important**: Extra arguments override the default configuration file, so you typically don't need to edit `conf/gracenote2epg.xml` manually.
#### Option 2: Edit Configuration File (Advanced Users)
Also note that the gracenote2epg auto-creates a configuration file on first run. You can then modify as needed:
```xml
<?xml version="1.0" encoding="utf-8"?>
<settings version="5">
<setting id="zipcode">92101</setting> <!-- Your ZIP/postal code -->
<setting id="lineupid">auto</setting> <!-- Auto-detect lineup -->
<setting id="days">7</setting> <!-- Guide duration -->
</settings>
```
## 📚 Documentation
- **[Installation Guide](https://github.com/th0ma7/gracenote2epg/blob/main/docs/installation.md)** - Installation instructions and software migration
- **[Configuration](https://github.com/th0ma7/gracenote2epg/blob/main/docs/configuration.md)** - Complete configuration reference
- **[Lineup Configuration](https://github.com/th0ma7/gracenote2epg/blob/main/docs/lineup-configuration.md)** - Finding and configuring your TV lineup
- **[TVheadend Integration](https://github.com/th0ma7/gracenote2epg/blob/main/docs/tvheadend.md)** - TVheadend setup, EPG migration, and troubleshooting
- **[Troubleshooting](https://github.com/th0ma7/gracenote2epg/blob/main/docs/troubleshooting.md)** - General issues and solutions
### Advanced Topics
- **[Cache & Retention Policies](https://github.com/th0ma7/gracenote2epg/blob/main/docs/cache-retention.md)** - Managing cache and log retention
- **[Log Rotation](https://github.com/th0ma7/gracenote2epg/blob/main/docs/log-rotation.md)** - Built-in log rotation system
- **[Development](https://github.com/th0ma7/gracenote2epg/blob/main/docs/development.md)** - Contributing, testing, XMLTV validation, and development setup
- **[Development Scripts](https://github.com/th0ma7/gracenote2epg/blob/main/scripts/README.md)** - Utility scripts for testing and distribution
## 🆘 Need Help?
1. **Check the [troubleshooting guide](https://github.com/th0ma7/gracenote2epg/blob/main/docs/troubleshooting.md)**
2. **Test your lineup**: `tv_grab_gracenote2epg --show-lineup --zip YOUR_CODE`
3. **Enable debug logging**: `tv_grab_gracenote2epg --debug --console`
4. **[Create an issue](https://github.com/th0ma7/gracenote2epg/issues)** with logs
## 📄 License
GPL v3 - Same as original script.module.zap2epg project
## 🙏 Credits
Based on edit4ever's script.module.zap2epg with enhancements and modern Python architecture.
---
**[View Changelog](https://github.com/th0ma7/gracenote2epg/blob/main/docs/changelog.md)** | **[Report Issues](https://github.com/th0ma7/gracenote2epg/issues)** | **[Contribute](https://github.com/th0ma7/gracenote2epg/blob/main/docs/development.md)**
Raw data
{
"_id": null,
"home_page": "https://github.com/th0ma7/gracenote2epg",
"name": "gracenote2epg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "xmltv epg tv guide gracenote tvheadend ota cable",
"author": "th0ma7",
"author_email": "th0ma7@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e2/ce/4058cd19e5bf216852d2999e44e4cb95e35af416b2b23516ae51842f8022/gracenote2epg-1.5.4.tar.gz",
"platform": null,
"description": "# gracenote2epg - TV Guide Grabber for North America\n\n> **\ud83d\udce6 PyPI Status**: Now available on PyPI! Install with `pip install gracenote2epg[full]`\n\nA modern Python implementation for downloading TV guide data from tvlistings.gracenote.com with intelligent caching and TVheadend integration.\n\n[](https://www.python.org/downloads/)\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://pypi.org/project/gracenote2epg/)\n[](https://github.com/th0ma7/gracenote2epg)\n\n## \ud83c\udf1f Key Features\n\n- **XMLTV Standard Compliant** - Full DTD compliance for maximum compatibility\n- **Intelligent Caching** - 95%+ cache efficiency with smart refresh strategies \n- **Multi-language Support** - Automatic French/English/Spanish detection and translations\n- **TVheadend Integration** - Seamless channel filtering and matching\n- **Unified Cache Management** - Streamlined configuration for all retention policies\n- **Platform Agnostic** - Auto-detection for Raspberry Pi, Synology NAS, and Linux\n\n## \ud83d\ude80 Installation\n\n```bash\n# Recommended: Install with all features\npip install gracenote2epg[full]\n\n# Basic installation (core features only)\npip install gracenote2epg\n\n# Alternative: Install from GitHub\npip install \"gracenote2epg[full] @ git+https://github.com/th0ma7/gracenote2epg.git@v1.5.4\"\n```\n\n### \ud83d\udce6 Development Installation\n\n```bash\n# Install from GitHub (latest)\npip install \"gracenote2epg[dev] @ git+https://github.com/th0ma7/gracenote2epg.git\"\n\n# Clone and install for development\ngit clone https://github.com/th0ma7/gracenote2epg.git\ncd gracenote2epg\npip install -e .[dev]\n```\n\n## \ud83d\udccb System Requirements\n\n- **Python**: 3.7 or higher\n- **Required**: `requests>=2.25.0`\n- **Optional**: `langdetect>=1.0.9` (language detection), `polib>=1.1.0` (translations)\n\n## \ud83d\udee0\ufe0f Quick Examples\n\n### Command Line Examples\n```bash\n# Show capabilities (XMLTV standard)\ntv_grab_gracenote2epg --capabilities\n\n# Download 7 days of guide data\ntv_grab_gracenote2epg --days 7 --zip 92101\n\n# Test lineup detection\ntv_grab_gracenote2epg --show-lineup --zip 92101\n\n# Canadian postal code with console output\ntv_grab_gracenote2epg --days 3 --postal J3B1M4 --console\n\n# Save to custom file with debug info\ntv_grab_gracenote2epg --days 7 --zip 92101 --output guide.xml --debug\n\n# Use specific lineup (auto-extracts location)\ntv_grab_gracenote2epg --days 7 --lineupid CAN-OTAJ3B1M4\n\n# Disable language detection\ntv_grab_gracenote2epg --days 7 --zip 92101 --langdetect false\n```\n\n### Configuration\n\n> **\ud83d\udca1 TVheadend Users - Easy Setup**: Most users don't need to edit configuration files! Simply use TVheadend's **Extra arguments** box to add your parameters like `--days 7 --zip 92101 --langdetect false` (Configuration \u2192 Channel/EPG \u2192 EPG Grabber Modules). See **[TVheadend Integration Guide](https://github.com/th0ma7/gracenote2epg/blob/main/docs/tvheadend.md)** for details.\n\n### TVheadend Integration Examples\n\n```bash\n# In TVheadend Extra arguments box:\n--days 7 --zip 92101\n--days 14 --postal J3B1M4 --langdetect false \n--days 7 --zip 90210 --lineupid auto\n```\n\n> **Important**: Extra arguments override the default configuration file, so you typically don't need to edit `conf/gracenote2epg.xml` manually.\n\n#### Option 2: Edit Configuration File (Advanced Users)\n\nAlso note that the gracenote2epg auto-creates a configuration file on first run. You can then modify as needed:\n```xml\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<settings version=\"5\">\n <setting id=\"zipcode\">92101</setting> <!-- Your ZIP/postal code -->\n <setting id=\"lineupid\">auto</setting> <!-- Auto-detect lineup -->\n <setting id=\"days\">7</setting> <!-- Guide duration -->\n</settings>\n```\n\n## \ud83d\udcda Documentation\n\n- **[Installation Guide](https://github.com/th0ma7/gracenote2epg/blob/main/docs/installation.md)** - Installation instructions and software migration\n- **[Configuration](https://github.com/th0ma7/gracenote2epg/blob/main/docs/configuration.md)** - Complete configuration reference\n- **[Lineup Configuration](https://github.com/th0ma7/gracenote2epg/blob/main/docs/lineup-configuration.md)** - Finding and configuring your TV lineup\n- **[TVheadend Integration](https://github.com/th0ma7/gracenote2epg/blob/main/docs/tvheadend.md)** - TVheadend setup, EPG migration, and troubleshooting\n- **[Troubleshooting](https://github.com/th0ma7/gracenote2epg/blob/main/docs/troubleshooting.md)** - General issues and solutions\n\n### Advanced Topics\n\n- **[Cache & Retention Policies](https://github.com/th0ma7/gracenote2epg/blob/main/docs/cache-retention.md)** - Managing cache and log retention\n- **[Log Rotation](https://github.com/th0ma7/gracenote2epg/blob/main/docs/log-rotation.md)** - Built-in log rotation system\n- **[Development](https://github.com/th0ma7/gracenote2epg/blob/main/docs/development.md)** - Contributing, testing, XMLTV validation, and development setup\n- **[Development Scripts](https://github.com/th0ma7/gracenote2epg/blob/main/scripts/README.md)** - Utility scripts for testing and distribution\n\n## \ud83c\udd98 Need Help?\n\n1. **Check the [troubleshooting guide](https://github.com/th0ma7/gracenote2epg/blob/main/docs/troubleshooting.md)**\n2. **Test your lineup**: `tv_grab_gracenote2epg --show-lineup --zip YOUR_CODE`\n3. **Enable debug logging**: `tv_grab_gracenote2epg --debug --console`\n4. **[Create an issue](https://github.com/th0ma7/gracenote2epg/issues)** with logs\n\n## \ud83d\udcc4 License\n\nGPL v3 - Same as original script.module.zap2epg project\n\n## \ud83d\ude4f Credits\n\nBased on edit4ever's script.module.zap2epg with enhancements and modern Python architecture.\n\n---\n\n**[View Changelog](https://github.com/th0ma7/gracenote2epg/blob/main/docs/changelog.md)** | **[Report Issues](https://github.com/th0ma7/gracenote2epg/issues)** | **[Contribute](https://github.com/th0ma7/gracenote2epg/blob/main/docs/development.md)**\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "TV Guide Grabber for North America",
"version": "1.5.4",
"project_urls": {
"Bug Reports": "https://github.com/th0ma7/gracenote2epg/issues",
"Documentation": "https://github.com/th0ma7/gracenote2epg/tree/main/docs",
"Homepage": "https://github.com/th0ma7/gracenote2epg",
"Source": "https://github.com/th0ma7/gracenote2epg",
"TVheadend Guide": "https://github.com/th0ma7/gracenote2epg/blob/main/docs/tvheadend.md"
},
"split_keywords": [
"xmltv",
"epg",
"tv",
"guide",
"gracenote",
"tvheadend",
"ota",
"cable"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c436ce3c2b19a72063d025336170f26d834eac15edf11481f70a72e1aa743bf5",
"md5": "e965a40d356f2e7324b28cf7cabbf0ea",
"sha256": "0f3c090925b4b059d192f9eda44e5d486646f831cc70a16c8ff3ea28462c31d5"
},
"downloads": -1,
"filename": "gracenote2epg-1.5.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e965a40d356f2e7324b28cf7cabbf0ea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 142472,
"upload_time": "2025-08-28T00:33:52",
"upload_time_iso_8601": "2025-08-28T00:33:52.681026Z",
"url": "https://files.pythonhosted.org/packages/c4/36/ce3c2b19a72063d025336170f26d834eac15edf11481f70a72e1aa743bf5/gracenote2epg-1.5.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e2ce4058cd19e5bf216852d2999e44e4cb95e35af416b2b23516ae51842f8022",
"md5": "a689f9e041e32d0f0708f41d2cc8a319",
"sha256": "c5a759859f0a46901e0568b00fa573e48fd5942a8b0209daca4a773759ec68c2"
},
"downloads": -1,
"filename": "gracenote2epg-1.5.4.tar.gz",
"has_sig": false,
"md5_digest": "a689f9e041e32d0f0708f41d2cc8a319",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 115471,
"upload_time": "2025-08-28T00:33:54",
"upload_time_iso_8601": "2025-08-28T00:33:54.430410Z",
"url": "https://files.pythonhosted.org/packages/e2/ce/4058cd19e5bf216852d2999e44e4cb95e35af416b2b23516ae51842f8022/gracenote2epg-1.5.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 00:33:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "th0ma7",
"github_project": "gracenote2epg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gracenote2epg"
}
JSON
