# Beeminder Client
A powerful Python client library and terminal interface for Beeminder. This package provides both a programmatic API client for building Beeminder applications and a feature-rich terminal interface for managing your Beeminder goals directly from the command line.
## Features
- **Complete API Coverage**: Full implementation of the Beeminder API with type hints
- **Interactive Terminal Interface**: Curses-based UI for managing goals and datapoints
- **Type-Safe**: Built with Pydantic models for reliable data handling
- **Easy to Use**: Simple interface for both programmatic and terminal usage
## Installation
Install from PyPI:
```bash
pip install beeminder_client
```
## Configuration
The client requires a Beeminder API key and optionally your username. These can be set via environment variables:
```bash
export BEEMINDER_API_KEY="your-api-key-here"
export BEEMINDER_USERNAME="your-username" # Optional
```
To get your API key:
1. Log into Beeminder
2. Go to https://www.beeminder.com/api/v1/auth_token.json
## Using the Terminal Interface
Start the terminal interface:
```bash
beeminder-cli
```
### Terminal Controls
- **Navigation**:
- `↑`/`↓`: Navigate through goals
- `i`: View detailed information for selected goal
- `b`: Go back to goal list from detail view
- `r`: Refresh goal data
- `c`: Create new datapoint for selected goal
- `w`: Open goal in web browser
- `q`: Quit application
### Adding Datapoints
1. Select a goal using arrow keys
2. Press `c` to create new datapoint
3. Enter value when prompted
4. Optionally add a comment
5. Press Enter to submit
## Using the API Client
```python
from beeminder_client.beeminder import BeeminderAPI
# Initialize client
client = BeeminderAPI(api_key="your-api-key", default_user="username")
# Get all goals
goals = client.get_all_goals()
# Get specific goal with datapoints
goal = client.get_goal("goal-slug", datapoints=True)
# Create datapoint
client.create_datapoint(
goal_slug="goal-slug",
value=1.0,
comment="Added via API"
)
```
## Program Design
The project is structured into three main components:
### 1. API Client (`beeminder.py`)
- Handles all HTTP communication with Beeminder's API
- Provides type-safe methods for all API endpoints
- Uses requests for HTTP operations
- Implements error handling and response validation
### 2. Data Models (`models.py`)
- Pydantic models for type safety and validation
- Represents Beeminder entities (Goals, Datapoints, etc.)
- Handles data parsing and serialization
- Provides clear structure for API responses
### 3. Terminal Interface (`beeminder_cli.py`)
- Built with Python's curses library
- Implements Model-View pattern:
- `BeeminderCLI`: Main controller class
- `InputWindow`: Helper class for user input
- Features:
- Two-panel interface (list and detail views)
- Efficient navigation and data entry
- Real-time updates and feedback
- Browser integration
### Architecture Decisions
1. **Type Safety**: Using Pydantic models ensures reliable data handling and provides excellent IDE support.
2. **Separation of Concerns**: Clear separation between API client, data models, and UI.
3. **Error Handling**: Comprehensive error handling in both API and UI layers.
4. **User Experience**: Terminal interface designed for efficiency and ease of use.
5. **Extensibility**: Easy to extend with new features or integrate into other applications.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## License
MIT
## Acknowledgments
- Built using the [Beeminder API](https://api.beeminder.com/)
- Inspired by the need for a better command-line interface for Beeminder
Raw data
{
"_id": null,
"home_page": "https://github.com/ianm199/beeminder_api_client",
"name": "beeminder-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Your Name",
"author_email": "your.email@example.com",
"download_url": "https://files.pythonhosted.org/packages/18/86/64940e3ee9c056fb7e28c2559f263634632665d98fb9f40f87ef94733ff2/beeminder_client-0.1.5.tar.gz",
"platform": null,
"description": "# Beeminder Client\n\nA powerful Python client library and terminal interface for Beeminder. This package provides both a programmatic API client for building Beeminder applications and a feature-rich terminal interface for managing your Beeminder goals directly from the command line.\n\n## Features\n\n- **Complete API Coverage**: Full implementation of the Beeminder API with type hints\n- **Interactive Terminal Interface**: Curses-based UI for managing goals and datapoints\n- **Type-Safe**: Built with Pydantic models for reliable data handling\n- **Easy to Use**: Simple interface for both programmatic and terminal usage\n\n## Installation\n\nInstall from PyPI:\n\n```bash\npip install beeminder_client\n```\n\n## Configuration\n\nThe client requires a Beeminder API key and optionally your username. These can be set via environment variables:\n\n```bash\nexport BEEMINDER_API_KEY=\"your-api-key-here\"\nexport BEEMINDER_USERNAME=\"your-username\" # Optional\n```\n\nTo get your API key:\n1. Log into Beeminder\n2. Go to https://www.beeminder.com/api/v1/auth_token.json\n\n## Using the Terminal Interface\n\nStart the terminal interface:\n\n```bash\nbeeminder-cli\n```\n\n### Terminal Controls\n\n- **Navigation**:\n - `\u2191`/`\u2193`: Navigate through goals\n - `i`: View detailed information for selected goal\n - `b`: Go back to goal list from detail view\n - `r`: Refresh goal data\n - `c`: Create new datapoint for selected goal\n - `w`: Open goal in web browser\n - `q`: Quit application\n\n### Adding Datapoints\n\n1. Select a goal using arrow keys\n2. Press `c` to create new datapoint\n3. Enter value when prompted\n4. Optionally add a comment\n5. Press Enter to submit\n\n## Using the API Client\n\n```python\nfrom beeminder_client.beeminder import BeeminderAPI\n\n# Initialize client\nclient = BeeminderAPI(api_key=\"your-api-key\", default_user=\"username\")\n\n# Get all goals\ngoals = client.get_all_goals()\n\n# Get specific goal with datapoints\ngoal = client.get_goal(\"goal-slug\", datapoints=True)\n\n# Create datapoint\nclient.create_datapoint(\n goal_slug=\"goal-slug\",\n value=1.0,\n comment=\"Added via API\"\n)\n```\n\n## Program Design\n\nThe project is structured into three main components:\n\n### 1. API Client (`beeminder.py`)\n- Handles all HTTP communication with Beeminder's API\n- Provides type-safe methods for all API endpoints\n- Uses requests for HTTP operations\n- Implements error handling and response validation\n\n### 2. Data Models (`models.py`)\n- Pydantic models for type safety and validation\n- Represents Beeminder entities (Goals, Datapoints, etc.)\n- Handles data parsing and serialization\n- Provides clear structure for API responses\n\n### 3. Terminal Interface (`beeminder_cli.py`)\n- Built with Python's curses library\n- Implements Model-View pattern:\n - `BeeminderCLI`: Main controller class\n - `InputWindow`: Helper class for user input\n- Features:\n - Two-panel interface (list and detail views)\n - Efficient navigation and data entry\n - Real-time updates and feedback\n - Browser integration\n\n### Architecture Decisions\n\n1. **Type Safety**: Using Pydantic models ensures reliable data handling and provides excellent IDE support.\n2. **Separation of Concerns**: Clear separation between API client, data models, and UI.\n3. **Error Handling**: Comprehensive error handling in both API and UI layers.\n4. **User Experience**: Terminal interface designed for efficiency and ease of use.\n5. **Extensibility**: Easy to extend with new features or integrate into other applications.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\nMIT\n\n## Acknowledgments\n\n- Built using the [Beeminder API](https://api.beeminder.com/)\n- Inspired by the need for a better command-line interface for Beeminder\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python client library and terminal interface for Beeminder",
"version": "0.1.5",
"project_urls": {
"Bug Tracker": "https://github.com/ianm199/beeminder_api_client/issues",
"Homepage": "https://github.com/ianm199/beeminder_api_client"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8ac4dc7cb719f3c820bd1aad00b6c30692e40feef37f40ef2e43bd5825fb68d1",
"md5": "2442d3ab2d02117d6041444f0d86df09",
"sha256": "7508b4dd0486672254c3f8e500b90cb7e11d068ad94a97219a6da85876add835"
},
"downloads": -1,
"filename": "beeminder_client-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2442d3ab2d02117d6041444f0d86df09",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12708,
"upload_time": "2024-10-28T23:02:14",
"upload_time_iso_8601": "2024-10-28T23:02:14.130803Z",
"url": "https://files.pythonhosted.org/packages/8a/c4/dc7cb719f3c820bd1aad00b6c30692e40feef37f40ef2e43bd5825fb68d1/beeminder_client-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "188664940e3ee9c056fb7e28c2559f263634632665d98fb9f40f87ef94733ff2",
"md5": "5aaef4f4059f55092acc0697f8555df7",
"sha256": "a4a38fef8483429e79cf0e3024be824d20c08b080d782f59415b97fc2d405aa3"
},
"downloads": -1,
"filename": "beeminder_client-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "5aaef4f4059f55092acc0697f8555df7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13473,
"upload_time": "2024-10-28T23:02:15",
"upload_time_iso_8601": "2024-10-28T23:02:15.675893Z",
"url": "https://files.pythonhosted.org/packages/18/86/64940e3ee9c056fb7e28c2559f263634632665d98fb9f40f87ef94733ff2/beeminder_client-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-28 23:02:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ianm199",
"github_project": "beeminder_api_client",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "beeminder-client"
}
JSON
