# 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/yourusername/beeminder_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/d3/70/f1141dc922ef21433fb09dbbb235079afdad1c7f29a5f1f6312b3b666732/beeminder_client-0.1.4.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.4",
"project_urls": {
"Bug Tracker": "https://github.com/yourusername/beeminder_client/issues",
"Homepage": "https://github.com/yourusername/beeminder_client"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "123a25c5a2e5b9fbbbab8eb026a5464e63f72b5f6ce30750e47fe328a4cc81e4",
"md5": "0975838083ac3b4c4b21b602415c1ead",
"sha256": "b7d35fe8bc6a54bc16a2ad017c90c6b7c3a6d0867bbfcccab4d2318f0122317a"
},
"downloads": -1,
"filename": "beeminder_client-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0975838083ac3b4c4b21b602415c1ead",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12664,
"upload_time": "2024-10-28T00:52:06",
"upload_time_iso_8601": "2024-10-28T00:52:06.353146Z",
"url": "https://files.pythonhosted.org/packages/12/3a/25c5a2e5b9fbbbab8eb026a5464e63f72b5f6ce30750e47fe328a4cc81e4/beeminder_client-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d370f1141dc922ef21433fb09dbbb235079afdad1c7f29a5f1f6312b3b666732",
"md5": "a4f42aaaac0a96ee99ac1f16d7b6e55c",
"sha256": "319ef22c0ca40062e8ab4563fab7075d2dd3a8ad570a81f6f7c30379d10db18d"
},
"downloads": -1,
"filename": "beeminder_client-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "a4f42aaaac0a96ee99ac1f16d7b6e55c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13383,
"upload_time": "2024-10-28T00:52:07",
"upload_time_iso_8601": "2024-10-28T00:52:07.638619Z",
"url": "https://files.pythonhosted.org/packages/d3/70/f1141dc922ef21433fb09dbbb235079afdad1c7f29a5f1f6312b3b666732/beeminder_client-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-28 00:52:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "beeminder_client",
"github_not_found": true,
"lcname": "beeminder-client"
}
JSON
