# Tigo Python API Wrapper
A modern, open-source Python library for interacting with the [Tigo Energy API](https://support.tigoenergy.com/hc/en-us/article_attachments/360041622173).
## Features
- 🔑 **Automatic authentication** with credentials from environment
- 📊 **Raw API access** and convenient DataFrame helpers
- ⚡ **Built-in rate limiting** and error handling
- 🧪 **Well-tested** with comprehensive test suite
- 📈 **Advanced analytics** including system efficiency and panel performance
- 🛡️ **Type hints** for better development experience
## Installation
### From PyPI (when published)
```bash
pip install tigo_python
```
### From GitHub
```bash
pip install git+https://github.com/matt-dreyer/tigo_python.git
```
### Development Installation
```bash
git clone https://github.com/matt-dreyer/tigo_python.git
cd tigo-python
pip install -e ".[dev]"
```
## Quick Start
### 1. Set up credentials
Create a `.env` file in your project root:
```env
TIGO_USERNAME=your_username
TIGO_PASSWORD=your_password
```
Or set environment variables:
```bash
export TIGO_USERNAME=your_username
export TIGO_PASSWORD=your_password
```
### 2. Basic usage
```python
from tigo_python import TigoClient
# Credentials loaded automatically from environment
with TigoClient() as client:
# Get your systems
systems = client.list_systems()
system_id = systems["systems"][0]["system_id"]
# Get current performance
summary = client.get_summary(system_id)
print(f"Current power: {summary['summary']['last_power_dc']} W")
# Get historical data as DataFrame
df = client.get_today_data(system_id)
print(df.head())
```
### 3. Advanced analytics
```python
# System efficiency analysis
efficiency = client.calculate_system_efficiency(system_id, days_back=30)
print(f"System efficiency: {efficiency['average_efficiency_percent']:.1f}%")
# Panel performance comparison
panel_perf = client.get_panel_performance(system_id)
print(panel_perf.head())
# Find underperforming panels
problems = client.find_underperforming_panels(system_id, threshold_percent=85)
for panel in problems:
print(f"Panel {panel['panel_id']}: {panel['efficiency_percent']:.1f}% efficiency")
```
## API Coverage
### Core Endpoints
- ✅ **Authentication** - Login/logout with token management
- ✅ **Users** - User information and preferences
- ✅ **Systems** - List systems, get details and layouts
- ✅ **Sources** - Hardware sources and configurations
- ✅ **Objects** - System components and hierarchy
- ✅ **Data** - Combined and aggregate data endpoints
- ✅ **Alerts** - System alerts and notifications
### Data Formats
- **Raw API responses** - Direct JSON from Tigo API
- **CSV strings** - For integration with other tools
- **Pandas DataFrames** - For data analysis and visualization
## Error Handling
The library provides specific exceptions for different error scenarios:
```python
from tigo_python.exceptions import TigoAPIError, TigoAuthenticationError
try:
client = TigoClient("wrong_user", "wrong_pass")
except TigoAuthenticationError as e:
print(f"Login failed: {e}")
except TigoAPIError as e:
print(f"API error: {e}")
```
## Rate Limiting
The library automatically handles API rate limits by:
- Limiting data requests to safe time ranges (≤20,150 minutes)
- Using appropriate data resolution (minute/hour/day) based on time span
- Providing helpful warnings when requests are adjusted
## Development
### Setup
```bash
git clone https://github.com/matt-dreyer/tigo_python.git
cd tigo-python
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest tests/ -v
```
### Code Quality
```bash
# Linting
ruff check tigo_python/
# Type checking
mypy tigo_python/
# Formatting
ruff format tigo_python/
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes with tests
4. Ensure code quality checks pass
5. Submit a pull request
## Requirements
- Python ≥ 3.8
- httpx ≥ 0.27.0
- pandas ≥ 2.0.0
- numpy ≥ 1.24.0
## Acknowledgments
This project is inspired by the [Rust tigo client](https://github.com/mrustl/tigo) by [@mrustl](https://github.com/mrustl).
## License
MIT License - see [LICENSE](LICENSE.txt) for details.
---
_This library is not affiliated with or endorsed by Tigo Energy._
Raw data
{
"_id": null,
"home_page": null,
"name": "tigo-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "tigo, energy, solar, api, monitoring",
"author": null,
"author_email": "Matt Dreyer <matt_dreyer@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/56/15/e1aa5e2159ea2d013e4fec5edad205233b093ef40825d598f0f5b43e2655/tigo_python-0.2.0.tar.gz",
"platform": null,
"description": "# Tigo Python API Wrapper\r\n\r\nA modern, open-source Python library for interacting with the [Tigo Energy API](https://support.tigoenergy.com/hc/en-us/article_attachments/360041622173). \r\n\r\n## Features\r\n\r\n- \ud83d\udd11 **Automatic authentication** with credentials from environment \r\n- \ud83d\udcca **Raw API access** and convenient DataFrame helpers \r\n- \u26a1 **Built-in rate limiting** and error handling\r\n- \ud83e\uddea **Well-tested** with comprehensive test suite\r\n- \ud83d\udcc8 **Advanced analytics** including system efficiency and panel performance\r\n- \ud83d\udee1\ufe0f **Type hints** for better development experience\r\n\r\n## Installation\r\n\r\n### From PyPI (when published)\r\n```bash\r\npip install tigo_python\r\n```\r\n\r\n### From GitHub\r\n```bash\r\npip install git+https://github.com/matt-dreyer/tigo_python.git\r\n```\r\n\r\n### Development Installation\r\n```bash\r\ngit clone https://github.com/matt-dreyer/tigo_python.git\r\ncd tigo-python\r\npip install -e \".[dev]\"\r\n```\r\n\r\n## Quick Start\r\n\r\n### 1. Set up credentials\r\n\r\nCreate a `.env` file in your project root:\r\n```env\r\nTIGO_USERNAME=your_username\r\nTIGO_PASSWORD=your_password\r\n```\r\n\r\nOr set environment variables:\r\n```bash\r\nexport TIGO_USERNAME=your_username\r\nexport TIGO_PASSWORD=your_password\r\n```\r\n\r\n### 2. Basic usage\r\n\r\n```python\r\nfrom tigo_python import TigoClient\r\n\r\n# Credentials loaded automatically from environment\r\nwith TigoClient() as client:\r\n # Get your systems\r\n systems = client.list_systems()\r\n system_id = systems[\"systems\"][0][\"system_id\"]\r\n \r\n # Get current performance\r\n summary = client.get_summary(system_id)\r\n print(f\"Current power: {summary['summary']['last_power_dc']} W\")\r\n \r\n # Get historical data as DataFrame\r\n df = client.get_today_data(system_id)\r\n print(df.head())\r\n```\r\n\r\n### 3. Advanced analytics\r\n\r\n```python\r\n# System efficiency analysis\r\nefficiency = client.calculate_system_efficiency(system_id, days_back=30)\r\nprint(f\"System efficiency: {efficiency['average_efficiency_percent']:.1f}%\")\r\n\r\n# Panel performance comparison\r\npanel_perf = client.get_panel_performance(system_id)\r\nprint(panel_perf.head())\r\n\r\n# Find underperforming panels\r\nproblems = client.find_underperforming_panels(system_id, threshold_percent=85)\r\nfor panel in problems:\r\n print(f\"Panel {panel['panel_id']}: {panel['efficiency_percent']:.1f}% efficiency\")\r\n```\r\n\r\n## API Coverage\r\n\r\n### Core Endpoints\r\n- \u2705 **Authentication** - Login/logout with token management\r\n- \u2705 **Users** - User information and preferences \r\n- \u2705 **Systems** - List systems, get details and layouts\r\n- \u2705 **Sources** - Hardware sources and configurations\r\n- \u2705 **Objects** - System components and hierarchy\r\n- \u2705 **Data** - Combined and aggregate data endpoints\r\n- \u2705 **Alerts** - System alerts and notifications\r\n\r\n### Data Formats\r\n- **Raw API responses** - Direct JSON from Tigo API\r\n- **CSV strings** - For integration with other tools\r\n- **Pandas DataFrames** - For data analysis and visualization\r\n\r\n## Error Handling\r\n\r\nThe library provides specific exceptions for different error scenarios:\r\n\r\n```python\r\nfrom tigo_python.exceptions import TigoAPIError, TigoAuthenticationError\r\n\r\ntry:\r\n client = TigoClient(\"wrong_user\", \"wrong_pass\")\r\nexcept TigoAuthenticationError as e:\r\n print(f\"Login failed: {e}\")\r\nexcept TigoAPIError as e:\r\n print(f\"API error: {e}\")\r\n```\r\n\r\n## Rate Limiting\r\n\r\nThe library automatically handles API rate limits by:\r\n- Limiting data requests to safe time ranges (\u226420,150 minutes)\r\n- Using appropriate data resolution (minute/hour/day) based on time span\r\n- Providing helpful warnings when requests are adjusted\r\n\r\n## Development\r\n\r\n### Setup\r\n```bash\r\ngit clone https://github.com/matt-dreyer/tigo_python.git\r\ncd tigo-python\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Running Tests\r\n```bash\r\npytest tests/ -v\r\n```\r\n\r\n### Code Quality\r\n```bash\r\n# Linting\r\nruff check tigo_python/\r\n\r\n# Type checking \r\nmypy tigo_python/\r\n\r\n# Formatting\r\nruff format tigo_python/\r\n```\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Make your changes with tests\r\n4. Ensure code quality checks pass\r\n5. Submit a pull request\r\n\r\n## Requirements\r\n\r\n- Python \u2265 3.8\r\n- httpx \u2265 0.27.0\r\n- pandas \u2265 2.0.0\r\n- numpy \u2265 1.24.0\r\n\r\n## Acknowledgments\r\n\r\nThis project is inspired by the [Rust tigo client](https://github.com/mrustl/tigo) by [@mrustl](https://github.com/mrustl).\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](LICENSE.txt) for details.\r\n\r\n---\r\n\r\n_This library is not affiliated with or endorsed by Tigo Energy._\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern Python library for interacting with the Tigo Energy API",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/matt-dreyer/tigo_python/issues",
"Documentation": "https://github.com/matt-dreyer/tigo_python",
"Homepage": "https://github.com/matt-dreyer/tigo_python",
"Repository": "https://github.com/matt-dreyer/tigo_python"
},
"split_keywords": [
"tigo",
" energy",
" solar",
" api",
" monitoring"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9aa88f49bb81b8fe1b9d76fafdd643763151abe169f813f81a5b101c1b4ffe4c",
"md5": "05a0ea78ea5c7fc4d9bec64b3dfaab2a",
"sha256": "d87f12738306815d119da1a014ac9bab33de7c165d0df5942e58a135ecce749a"
},
"downloads": -1,
"filename": "tigo_python-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "05a0ea78ea5c7fc4d9bec64b3dfaab2a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11388,
"upload_time": "2025-07-16T03:10:44",
"upload_time_iso_8601": "2025-07-16T03:10:44.867481Z",
"url": "https://files.pythonhosted.org/packages/9a/a8/8f49bb81b8fe1b9d76fafdd643763151abe169f813f81a5b101c1b4ffe4c/tigo_python-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5615e1aa5e2159ea2d013e4fec5edad205233b093ef40825d598f0f5b43e2655",
"md5": "9eb7671c7466d1037625ccd2bbf4ce11",
"sha256": "e77e9ee2208fbccbe5ab6e0811c250829ada84a360c9696a8fc22291c2ac0a19"
},
"downloads": -1,
"filename": "tigo_python-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "9eb7671c7466d1037625ccd2bbf4ce11",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12482,
"upload_time": "2025-07-16T03:10:46",
"upload_time_iso_8601": "2025-07-16T03:10:46.019539Z",
"url": "https://files.pythonhosted.org/packages/56/15/e1aa5e2159ea2d013e4fec5edad205233b093ef40825d598f0f5b43e2655/tigo_python-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 03:10:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matt-dreyer",
"github_project": "tigo_python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "httpx",
"specs": [
[
">=",
"0.25.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.24.0"
]
]
},
{
"name": "pytz",
"specs": [
[
">=",
"2023.3"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
">=",
"2.8.2"
]
]
}
],
"lcname": "tigo-python"
}
JSON
