A Python client library and terminal interface for Beeminder
Project description
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:
pip install beeminder_client
Configuration
The client requires a Beeminder API key and optionally your username. These can be set via environment variables:
export BEEMINDER_API_KEY="your-api-key-here"
export BEEMINDER_USERNAME="your-username" # Optional
To get your API key:
- Log into Beeminder
- Go to https://www.beeminder.com/api/v1/auth_token.json
Using the Terminal Interface
Start the terminal interface:
beeminder-cli
Terminal Controls
- Navigation:
↑
/↓
: Navigate through goalsi
: View detailed information for selected goalb
: Go back to goal list from detail viewr
: Refresh goal datac
: Create new datapoint for selected goalw
: Open goal in web browserq
: Quit application
Adding Datapoints
- Select a goal using arrow keys
- Press
c
to create new datapoint - Enter value when prompted
- Optionally add a comment
- Press Enter to submit
Using the API Client
from src.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 classInputWindow
: 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
- Type Safety: Using Pydantic models ensures reliable data handling and provides excellent IDE support.
- Separation of Concerns: Clear separation between API client, data models, and UI.
- Error Handling: Comprehensive error handling in both API and UI layers.
- User Experience: Terminal interface designed for efficiency and ease of use.
- 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
- Inspired by the need for a better command-line interface for Beeminder
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for beeminder_client-0.1.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 161bef5ea8b8f47694d1d46108943c6a9267d5e41c1cc67e941279719670b3d2 |
|
MD5 | c7a16af451bca0d1ec710456d79e25d1 |
|
BLAKE2b-256 | a58a0a771b1f81c13918824d2762fac6a46a1c36fc1c48d845e91f92b589a038 |