Thin wrapper around OVH's APIs. Handles all the hard work including credential creation and requests signing.
OVH's APIs relies on an OAuth based mechanism for authentication. OAuth is a standard protocol allowing to securely authenticate both an application and a user within an application. It also supports specific access restrictions. This is accomplished using a set of 3 Keys:
application_key
: Uniquely identifies an application. It can be seen as an application "login" and is attached to an account. This key may safely be shared.application_secret
: Authenticates application identified byapplication_key
. It can be seen as an application "password" and should be protected as such !consumer_key
: Each application's user has it's ownconsumer_key
specific to the this application. Aconsumer_key
may only be valid for a subset of the API and a restricted amount of time.
application_key
and application_secret
are defined once for each application (see "Supported APIs" bellow) and consumer_key
are granted once for each application's and-user.
The easiest way to get the latest stable release is to grab it from pypi using pip
.
pip install ovh
Alternatively, you may get latest development version directly from Git.
pip install -e git+https://github.com/ovh/python-ovh.git#egg=ovh
This wrapper uses standard Python tools, so you should feel familiar with it. Here is a quick outline of what it may look like. A good practice is to run this from a virtualenv
.
git clone https://github.com/ovh/python-ovh.git
cd python-ovh
python setup.py develop
pip install -r requirements-dev.txt
nostests # 100% coverage is a hard minimum
You've developed a new cool feature ? Fixed an annoying bug ? We'd be happy to here from you !
Documentation is managed using the excelent Sphinx
system. For example, to build HTML documentation:
cd python-ovh/docs
make html
To communicate with APIs, the SDK uses a token on each request to identify the user. This token is called consumer_key
. Getting a consumer_key
is done in 3 steps:
- application requests a new consumer key and specifies requested access permissions.
- application redirects user to a specific validation URL.
- end-user authenticates himself using his OVH credentials to validate it.
Example:
# -*- encoding: utf-8 -*-
import ovh
# visit https://api.ovh.com/createApp/ to create your application's credentials
APPLICATION_KEY = '<application key>'
APPLICATION_SECRET = '<application secret>'
# create a client without a consumerKey
client = ovh.Client(
endpoint='ovh-eu',
application_key=APPLICATION_KEY,
application_secret=APPLICATION_SECRET,
)
# Request RO, /me API access
access_rules = [
{'method': 'GET', 'path': '/me'},
]
# Request token
validation = client.request_consumerkey(access_rules)
print "Please visit %s to authenticate" % validation['validationUrl']
raw_input("and press Enter to continue...")
# Print nice welcome message
print "Welcome", client.get('/me')['firstname']
print "Btw, your 'consumerKey' is '%s'" % validation['consumerKey']
Returned consumerKey
should then be kept to avoid re-authenticating your end-user on each use.
Note: to request full and unlimited access to the API, you may use wildcards:
access_rules = [
{'method': 'GET', 'path': '/*'},
{'method': 'POST', 'path': '/*'},
{'method': 'PUT', 'path': '/*'},
{'method': 'DELETE', 'path': '/*'}
]
# -*- encoding: utf-8 -*-
import ovh
APPLICATION_KEY = '<application key>'
APPLICATION_SECRET = '<application secret>'
# create a client without a consumerKey
client = ovh.Client(
endpoint='ovh-eu',
application_key=APPLICATION_KEY,
application_secret=APPLICATION_SECRET,
)
# Request RO, /me/bill API access
access_rules = [
{'method': 'GET', 'path': '/me/bill'},
{'method': 'GET', 'path': '/me/bill/*'},
]
# Request token
validation = client.request_consumerkey(access_rules)
print "Please visit", validation['validationUrl'], "to authenticate"
raw_input("and press Enter to continue...")
# Grab bill list
bills = client.get('/me/bill')
for bill in bills:
details = client.get('/me/bill/%s' % bill)
print "%12s (%s): %10s --> %s" % (
bill,
details['date'],
details['priceWithTax']['text'],
details['pdfUrl'],
)
# -*- encoding: utf-8 -*-
import ovh
# visit https://api.ovh.com/createApp/ to create your application's credentials
APPLICATION_KEY = '<application key>'
APPLICATION_SECRET = '<application secret>'
CONSUMER_KEY = '<consumer key (see above)>'
# create a client
client = ovh.Client(
endpoint='ovh-eu',
application_key=APPLICATION_KEY,
application_secret=APPLICATION_SECRET,
consumer_key=CONSUMER_KEY,
)
# get list of all server names
servers = client.get('/dedicated/server/')
# find all servers in SBG-1 datacenter
for server in servers:
details = client.get('/dedicated/server/%s' % server)
if details['datacenter'] == 'sbg1':
# enable burst on server
client.put('/dedicated/server/%s/burst' % server, status='active')
print "Enabled burst for %s server located in SBG-1" % server
# -*- encoding: utf-8 -*-
import ovh
from tabulate import tabulate
# visit https://api.runabove.com/createApp/ to create your application's credentials
APPLICATION_KEY = '<application key>'
APPLICATION_SECRET = '<application secret>'
CONSUMER_KEY = '<consumer key (see above)>'
# create a client
client = ovh.Client(
endpoint='runabove-ca',
application_key=APPLICATION_KEY,
application_secret=APPLICATION_SECRET,
consumer_key=CONSUMER_KEY,
)
# get list of all instances
instances = client.get('/instance')
# pretty print instances status
table = []
for instance in instances:
table.append([
instance['name'],
instance['ip'],
instance['region'],
instance['status'],
])
print tabulate(table, headers=['Name', 'IP', 'Region', 'Status'])
Before running this example, make sure you have the tabulate library installed. It's a pretty cool library to pretty print tabular data.
>>> pip install tabulate
- documentation: https://api.ovh.com/
- community support: api-subscribe@ml.ovh.net
- console: https://api.ovh.com/console
- get application credentials: https://api.ovh.com/createApp/
- console: https://api.runabove.com/console/
- get application credentials: https://api.runabove.com/createApp/
- high level SDK: https://github.com/runabove/python-runabove
- contribute: https://github.com/ovh/python-ovh
- Report bugs: https://github.com/ovh/python-ovh/issues
- Download: http://pypi.python.org/pypi/ovh