Skip to main content

The official Python client library for the Trovebox photo service

Project description

(Previously known as openphoto-python)

Build Status Python Package Index (PyPI)

This library works with any Trovebox server, either self-hosted, or using the hosted service at It provides full access to your photos and metadata, via a simple Pythonic API.


pip install trovebox


See the Trovebox API Documentation for full API documentation, including Python examples.

All development takes place at the openphoto-python GitHub site.


For full access to your photos, you need to create the following config file in ~/.config/trovebox/default:

# ~/.config/trovebox/default
host =
consumerKey = your_consumer_key
consumerSecret = your_consumer_secret
token = your_access_token
tokenSecret = your_access_token_secret

The config_file switch lets you specify a different config file.

To get your credentials:

  • Log into your Trovebox site

  • Click the arrow on the top-right and select ‘Settings’

  • Click the ‘Create a new app’ button

  • Click the ‘View’ link beside the newly created app

Using the library

from trovebox import Trovebox
client = Trovebox()
photos =
photos[0].update(tags=["tag1", "tag2"])

The Trovebox Python class hierarchy mirrors the Trovebox API endpoint layout. For example, the calls in the example above use the following API endpoints:

  • -> /photos/list.json

  • photos[0].update() -> /photo/<id>/update.json

You can also access the API at a lower level using GET/POST methods:

resp = client.get("/photos/list.json")
resp ="/photo/62/update.json", tags=["tag1", "tag2"])

API Versioning

It may be useful to lock your application to a particular version of the Trovebox API. This ensures that future API updates won’t cause unexpected breakages.

To do this, add the optional api_version parameter when creating the client object:

from trovebox import Trovebox
client = Trovebox(api_version=2)

Commandline Tool

You can run commands to the Trovebox API from your shell!

These are the options you can pass to the shell program:

--help         # Display help text
-c config_file # Either the name of a config file in ~/.config/trovebox/ or a full path to a config file
-h hostname    # Overrides config_file for unauthenticated API calls
-e endpoint    # [default=/photos/list.json]
-X method      # [default=GET]
-F params      # e.g. -F 'title=my title' -F 'tags=mytag1,mytag2'
-p             # Pretty print the json
-v             # Verbose output
--version      # Display the current version information

Commandline Examples

Upload a public photo to the host specified in `~/.config/trovebox/default`:

trovebox -p -X POST -e /photo/upload.json -F 'photo=@/path/to/photo/jpg' -F 'permission=1'
    "message":"Photo 1eo uploaded successfully",

Get a thumbnail URL from (unauthenticated access):

trovebox -h -p -e /photo/62/view.json -F 'returnSizes=20x20'
    "message":"Photo 62",

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

trovebox-0.4.tar.gz (12.5 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page