Update Python documentation from latest openphoto-python README.rst
This commit is contained in:
sneakypete81
parent
b8cd58ca14
commit
80f6c9de89
2 changed files with 142 additions and 131 deletions
|
|
@ -1,131 +0,0 @@
|
||||||
Open Photo API / Python Library
|
|
||||||
=======================
|
|
||||||
#### OpenPhoto, a photo service for the masses
|
|
||||||
[](https://travis-ci.org/photo/openphoto-python)
|
|
||||||
|
|
||||||
----------------------------------------
|
|
||||||
<a name="install"></a>
|
|
||||||
### Installation
|
|
||||||
python setup.py install
|
|
||||||
|
|
||||||
----------------------------------------
|
|
||||||
<a name="credentials"></a>
|
|
||||||
### Credentials
|
|
||||||
|
|
||||||
For full access to your photos, you need to create the following config file in ``~/.config/openphoto/default``
|
|
||||||
|
|
||||||
# ~/.config/openphoto/default
|
|
||||||
host = your.host.com
|
|
||||||
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
|
|
||||||
|
|
||||||
----------------------------------------
|
|
||||||
<a name="python"></a>
|
|
||||||
### How to use the library
|
|
||||||
|
|
||||||
You can use the library in one of two ways:
|
|
||||||
|
|
||||||
* Direct GET/POST calls to the server
|
|
||||||
* Access via Python classes/methods
|
|
||||||
|
|
||||||
<a name="get_post"></a>
|
|
||||||
#### Direct GET/POST:
|
|
||||||
|
|
||||||
from openphoto import OpenPhoto
|
|
||||||
client = OpenPhoto()
|
|
||||||
resp = client.get("/photos/list.json")
|
|
||||||
resp = client.post("/photo/62/update.json", tags=["tag1", "tag2"])
|
|
||||||
|
|
||||||
<a name="python_classes"></a>
|
|
||||||
#### Python classes/methods
|
|
||||||
|
|
||||||
from openphoto import OpenPhoto
|
|
||||||
client = OpenPhoto()
|
|
||||||
photos = client.photos.list()
|
|
||||||
photos[0].update(tags=["tag1", "tag2"])
|
|
||||||
print photos[0].tags
|
|
||||||
|
|
||||||
The OpenPhoto Python class hierarchy mirrors the [OpenPhoto API](http://theopenphotoproject.org/documentation) endpoint layout. For example, the calls in the example above use the following API endpoints:
|
|
||||||
|
|
||||||
* ``client.photos.list() -> /photos/list.json``
|
|
||||||
* ``photos[0].update() -> /photo/<id>/update.json``
|
|
||||||
|
|
||||||
<a name="api_versioning"></a>
|
|
||||||
### API Versioning
|
|
||||||
|
|
||||||
It may be useful to lock your application to a particular version of the OpenPhoto 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 openphoto import OpenPhoto
|
|
||||||
client = OpenPhoto(api_version=2)
|
|
||||||
|
|
||||||
----------------------------------------
|
|
||||||
|
|
||||||
<a name="cli"></a>
|
|
||||||
### Using from the command line
|
|
||||||
|
|
||||||
You can run commands to the OpenPhoto 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/openphoto/ 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
|
|
||||||
|
|
||||||
<a name="cli-examples"></a>
|
|
||||||
#### Command line examples
|
|
||||||
|
|
||||||
# Upload a public photo to the host specified in ~/.config/openphoto/default
|
|
||||||
openphoto -p -X POST -e /photo/upload.json -F 'photo=@/path/to/photo/jpg' -F 'permission=1'
|
|
||||||
{
|
|
||||||
"code":201,
|
|
||||||
"message":"Photo 1eo uploaded successfully",
|
|
||||||
"result":{
|
|
||||||
"actor":"user@example.com",
|
|
||||||
"albums":[],
|
|
||||||
...
|
|
||||||
...
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
# Get a thumbnail URL from current.openphoto.me (unauthenticated access)
|
|
||||||
openphoto -h current.openphoto.me -p -e /photo/62/view.json -F 'returnSizes=20x20'
|
|
||||||
{
|
|
||||||
"code":200,
|
|
||||||
"message":"Photo 62",
|
|
||||||
"result":{
|
|
||||||
"actor":"",
|
|
||||||
"albums":[
|
|
||||||
"1"
|
|
||||||
],
|
|
||||||
...
|
|
||||||
...
|
|
||||||
"path20x20":"http://current.openphoto.me/photo/62/create/36c0a/20x20.jpg",
|
|
||||||
"pathBase":"http://awesomeness.openphoto.me/base/201203/7ae997-Boracay-Philippines-007.jpg",
|
|
||||||
"permission":"1",
|
|
||||||
"photo20x20":[
|
|
||||||
"http://current.openphoto.me/photo/62/create/36c0a/20x20.jpg",
|
|
||||||
13,
|
|
||||||
20
|
|
||||||
],
|
|
||||||
...
|
|
||||||
...
|
|
||||||
}
|
|
||||||
}
|
|
||||||
142
docs/libraries/python.rst
Normal file
142
docs/libraries/python.rst
Normal file
|
|
@ -0,0 +1,142 @@
|
||||||
|
=======================
|
||||||
|
Trovebox Python Library
|
||||||
|
=======================
|
||||||
|
(Previously known as openphoto-python)
|
||||||
|
|
||||||
|
.. image:: https://api.travis-ci.org/photo/openphoto-python.png
|
||||||
|
:alt: Build Status
|
||||||
|
:target: https://travis-ci.org/photo/openphoto-python
|
||||||
|
|
||||||
|
.. image:: https://pypip.in/v/trovebox/badge.png
|
||||||
|
:alt: Python Package Index (PyPI)
|
||||||
|
:target: https://pypi.python.org/pypi/trovebox
|
||||||
|
|
||||||
|
This library works with any Trovebox server, either
|
||||||
|
`self-hosted <https://github.com/photo>`__, or using the hosted service at
|
||||||
|
`trovebox.com <http://trovebox.com>`__.
|
||||||
|
It provides full access to your photos and metadata, via a simple
|
||||||
|
Pythonic API.
|
||||||
|
|
||||||
|
Installation
|
||||||
|
============
|
||||||
|
::
|
||||||
|
|
||||||
|
pip install trovebox
|
||||||
|
|
||||||
|
Documentation
|
||||||
|
=============
|
||||||
|
See the `Trovebox API Documentation <https://trovebox.com/documentation>`__
|
||||||
|
for full API documentation, including Python examples.
|
||||||
|
|
||||||
|
All development takes place at the `openphoto-python GitHub site <https://github.com/photo/openphoto-python>`__.
|
||||||
|
|
||||||
|
Credentials
|
||||||
|
===========
|
||||||
|
For full access to your photos, you need to create the following config
|
||||||
|
file in ``~/.config/trovebox/default``::
|
||||||
|
|
||||||
|
# ~/.config/trovebox/default
|
||||||
|
host = your.host.com
|
||||||
|
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 = client.photos.list()
|
||||||
|
photos[0].update(tags=["tag1", "tag2"])
|
||||||
|
print(photos[0].tags)
|
||||||
|
|
||||||
|
The Trovebox Python class hierarchy mirrors the
|
||||||
|
`Trovebox API <https://trovebox.com/documentation>`__ endpoint layout.
|
||||||
|
For example, the calls in the example above use the following API endpoints:
|
||||||
|
|
||||||
|
* ``client.photos.list() -> /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 = client.post("/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'
|
||||||
|
{
|
||||||
|
"code":201,
|
||||||
|
"message":"Photo 1eo uploaded successfully",
|
||||||
|
"result":{
|
||||||
|
"actor":"user@example.com",
|
||||||
|
"albums":[],
|
||||||
|
...
|
||||||
|
...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Get a thumbnail URL from current.trovebox.com (unauthenticated access)::
|
||||||
|
|
||||||
|
trovebox -h current.trovebox.com -p -e /photo/62/view.json -F 'returnSizes=20x20'
|
||||||
|
{
|
||||||
|
"code":200,
|
||||||
|
"message":"Photo 62",
|
||||||
|
"result":{
|
||||||
|
"actor":"",
|
||||||
|
"albums":[
|
||||||
|
"1"
|
||||||
|
],
|
||||||
|
...
|
||||||
|
...
|
||||||
|
"path20x20":"http://current.trovebox.com/photo/62/create/36c0a/20x20.jpg",
|
||||||
|
"pathBase":"http://awesomeness.trovebox.com/base/201203/7ae997-Boracay-Philippines-007.jpg",
|
||||||
|
"permission":"1",
|
||||||
|
"photo20x20":[
|
||||||
|
"http://current.trovebox.com/photo/62/create/36c0a/20x20.jpg",
|
||||||
|
13,
|
||||||
|
20
|
||||||
|
],
|
||||||
|
...
|
||||||
|
...
|
||||||
|
}
|
||||||
|
}
|
||||||
Loading…
Add table
Add a link
Reference in a new issue