trackbear-api 0.0.13

Python library for synchronous HTTP calls to the Trackbear API (https://help.trackbear.app/api)

trackbear-api

• Contributing Guide and Developer Setup Guide
• License: MIT

---

Python library for synchronous HTTP calls to the Trackbear API (https://help.trackbear.app/api)

• TrackBear app
• TrackBear API documentation

Deveploment in progress, expect breaking changes frequently until version 0.1.0

Routes pending implementation:

• Other

Features pending implementation:

• Rate limit exceptions

Installation

python -m pip install trackbear-api

Environment Variables

The following environment variables allow you to configure the TrackBearClient outside of code. All variables listed below can also be set during the initialization of the TrackBearClient as well.

Variable	Description	Has Default	Default
TRACKBEAR_API_TOKEN	Your secret API token	False
TRACKBEAR_API_URL	The URL of the TrackBear API	True	https://trackbear.app/api/v1/
TRACKBEAR_API_AGENT	The User-Agent header sent with requests	True	trackbear-api/0.x.x (https://github.com/Preocts/trackbear-api) (app name: [app_name])
TRACKBEAR_API_TIMEOUT_SECONDS	Seconds before HTTPS reqeusts timeout	True	10

Example Use

The TrackBearClient give you all of the access to the TrackBear API. Various routes of the API, such as Projects, are available through the TrackBearClient from their respective attribute.

Error handling removed for brevity.

from trackbear_api import TrackBearClient
from trackbear_api.enums import Phase

# Assumes TRACKBEAR_API_TOKEN is set in the environment
client = TrackBearClient("my_app")

# Create a new Project
new_project = client.project.save(
    title="My new TrackBear project",
    description="This will be an amazing story!",
    phase=Phase.OUTLINING,  # "outlining" as a string works here too
    starred=True,
    word=1667,
)

print(f"New Project created ({new_project.id}) '{new_project.title}'")

# List all projects
projects = client.project.list()

print(f"| {'Project Id':^12} | {'Title':^30} | {'Word Count':^12} |")
print("-" * 64)
for project in projects:
    print(f"| {project.id:<12} | {project.title:<30} | {project.totals.word:<12} |")

Library API

The library's API is build to match TrackBear's API general structure.

https://help.trackbear.app/api/

Tallies

Provider Method	Description
TrackBearClient.tally	Contains helper methods for all Tally related routes

Method	Description
.list()	Get all tallies, or filter by parameters
.get()	Get a tally by specific id
.save()	Create or update tally
.delete()	Delete a tally by its id

Projects

Provider Method	Description
TrackBearClient.project	Contains helper methods for all Project related routes

Method	Description
.list()	Get all projects
.get()	Get a project by specific id
.save()	Create or update project
.delete()	Delete a project by its id

Goals

Provider Method	Description
TrackBearClient.goal	Contains helper methods for all Goal related routes

Method	Description
.list()	Get all goals
.get()	Get a goal by specific id
.save_target()	Create or update target goal
.save_habit()	Create or update habit goal
.delete()	Delete a goal by its id

Tags

Provider Method	Description
TrackBearClient.tag	Contains helper methods for all Tag related routes

Method	Description
.list()	Get all tags
.get()	Get a tag by specific id
.save()	Create or update tag
.delete()	Delete a tag by its id

Stats

Provider Method	Description
TrackBearClient.stat	Contains helper methods for all Stat related routes

Method	Description
.list()	Get stats. By default returns all stats.

Leaderboards

Provider Method	Description
TrackBearClient.leaderboard	Contains helper methods for all Leaderboard related routes

Method	Description
.list()	Get all leaderboards
.list_participants()	Get a leaderboard's participants
.get()	Get a leaderboard by specific uuid
.get_by_join_code()	Get a leaderboard by specific join code
.save()	Create or update a leaderboard
.star()	Star a Leaderboard
.unstar()	Unstar a Leaderboard
.delete()	Delete a leaderboard by uuid

Leaderboard Teams

Provider Method	Description
TrackBearClient.leaderboard.teams	Contains helper methods for all leaderboard Team related routes

Method	Description
.list()	Get all teams on a leaderboard
.get()	Get a specific team from a leaderboard
.save()	Create or update a team on a leaderboard
.delete()	Delete a team from a leaderboard

Leaderboard Members

Provider Method	Description
TrackBearClient.leaderboard.members	Contains helper methods for all leaderboard Members related routes

Method	Description
.list()	Get all members on a leaderboard
.set_owner()	Set a member as an owner of a leaderboard
.unset_owner()	Remove ownership of a member of a leaderboard
.delete()	Delete a member from a leaderboard

Leaderboard Participation

Provider Method	Description
TrackBearClient.leaderboard.participation	Contains helper methods for all leaderboard participation related routes

Method	Description
.get()	Get your participation of a leaderboard
.join()	Join a leaderboard
.update()	Update your participant details of a leaderboard
.leave()	Leave a leaderboard

Bare Access

Bare access to the API allows you to escape from the structured return models and call routes directly. These methods return a models.TrackBearResponse object.

Provider Method	Description
TrackBearClient.bare	Escape hatch allowing manually defined calls to API

Method	Description
.get()	HTTP GET to the TrackBear API
.post()	HTTP POST to the TrackBear API
.patch()	HTTP PATCH to the TrackBear API
.delete()	HTTP DELETE to the TrackBear API

trackbear_api.models.TrackBearResponse

Attribute	Type	Description
.success	bool	True or False if the request was succesful.
.data	Any	API response if success is True
.error.code	str	Error code if success is False
.error.message	str	Error message if success is False
.status_code	int	The HTTP status code of the response
.remaining_requests	int	Number of requests remaining before rate limits apply
.rate_reset	int	Number of seconds before remaining_requests resets

Exceptions

The library defines a handful of useful custom exceptions.

trackbear_api.exceptions.TrackBearAPIException

Parent class of all exceptions defined in the library. Inherits from Exception.

trackbear_api.exceptions.ModelBuildError

Raised when building a dataclass model from the API response fails. This can indicate the expected response has changed from the observed response. The exception contains the model name that failed and the data the model attempted to build with. Both are vital for bug reports.

Attribute	Type	Description
data_string	str	The data which caused the model build to fail
model_name	str	The name of the model that failed

trackbear_api.exceptions.APIResponseError

Raised by all provider methods when the API returns an unsuccessful response.

Attribute	Type	Description
status_code	int	HTTP status code returned by the API
code	str	Error code provided by the API
message	str	Human readable error message provided by the API

trackbear_api.exceptions.APITimeoutError

Raised when the TrackBear API request, read, or connection times out.

Attribute	Type	Description
exception	Exception	Exception raised by internal HTTP library
method	str	HTTP method
url	str	Target URL
timeout	int	Timeout length in seconds

---

Rate Limiting

Rate limiting is defined by the TrackBear API here: https://help.trackbear.app/api/rate-limits

This library does not presently enforce the rate limits.

Logging

All loggers use the name trackbear-api. No handlers are defined by default in this library.