.. image:: https://github.com/ovh/python-ovh/raw/master/docs/img/logo.png
:alt: Python & OVHcloud APIs
:target: https://pypi.python.org/pypi/ovh
Lightweight wrapper around OVHcloud's APIs. Handles all the hard work including
credential creation and requests signing.
.. image:: https://img.shields.io/pypi/v/ovh.svg
:alt: PyPi Version
:target: https://pypi.python.org/pypi/ovh
.. image:: https://img.shields.io/pypi/status/ovh.svg
:alt: PyPi repository status
:target: https://pypi.python.org/pypi/ovh
.. image:: https://img.shields.io/pypi/pyversions/ovh.svg
:alt: PyPi supported Python versions
:target: https://pypi.python.org/pypi/ovh
.. image:: https://img.shields.io/pypi/wheel/ovh.svg
:alt: PyPi Wheel status
:target: https://pypi.python.org/pypi/ovh
.. image:: https://github.com/ovh/python-ovh/actions/workflows/test.yaml/badge.svg?branch=master
:alt: Build Status
:target: https://github.com/ovh/python-ovh/actions/workflows/test.yaml
.. image:: https://coveralls.io/repos/github/ovh/python-ovh/badge.svg
:alt: Coverage Status
:target: https://coveralls.io/github/ovh/python-ovh
.. code:: python
import ovh
# Instantiate. Visit https://api.ovh.com/createToken/?GET=/me
# to get your credentials
client = ovh.Client(
endpoint='ovh-eu',
application_key='<application key>',
application_secret='<application secret>',
consumer_key='<consumer key>',
)
# Print nice welcome message
print("Welcome", client.get('/me')['firstname'])
Installation
============
The python wrapper works with Python 3.7+.
The easiest way to get the latest stable release is to grab it from `pypi
<https://pypi.python.org/pypi/ovh>`_ using ``pip``.
.. code:: bash
pip install ovh
Alternatively, you may get latest development version directly from Git.
.. code:: bash
pip install -e git+https://github.com/ovh/python-ovh.git#egg=ovh
People looking for Python 2 compatibility should use 0.6.x version.
Example Usage
=============
Use the API on behalf of a user
-------------------------------
1. Create an application
************************
To interact with the APIs, the SDK needs to identify itself using an
``application_key`` and an ``application_secret``. To get them, you need
to register your application. Depending the API you plan to use, visit:
- `OVHcloud Europe <https://eu.api.ovh.com/createApp/>`_
- `OVHcloud US <https://api.us.ovhcloud.com/createApp/>`_
- `OVHcloud North-America <https://ca.api.ovh.com/createApp/>`_
- `So you Start Europe <https://eu.api.soyoustart.com/createApp/>`_
- `So you Start North America <https://ca.api.soyoustart.com/createApp/>`_
- `Kimsufi Europe <https://eu.api.kimsufi.com/createApp/>`_
- `Kimsufi North America <https://ca.api.kimsufi.com/createApp/>`_
Once created, you will obtain an **application key (AK)** and an **application
secret (AS)**.
2. Configure your application
*****************************
The easiest and safest way to use your application's credentials is to create an
``ovh.conf`` configuration file in application's working directory. Here is how
it looks like:
.. code:: ini
[default]
; general configuration: default endpoint
endpoint=ovh-eu
[ovh-eu]
; configuration specific to 'ovh-eu' endpoint
application_key=my_app_key
application_secret=my_application_secret
; uncomment following line when writing a script application
; with a single consumer key.
;consumer_key=my_consumer_key
; uncomment to enable oauth2 authentication
;client_id=my_client_id
;client_secret=my_client_secret
Depending on the API you want to use, you may set the ``endpoint`` to:
* ``ovh-eu`` for OVHcloud Europe API
* ``ovh-us`` for OVHcloud US API
* ``ovh-ca`` for OVHcloud North-America API
* ``soyoustart-eu`` for So you Start Europe API
* ``soyoustart-ca`` for So you Start North America API
* ``kimsufi-eu`` for Kimsufi Europe API
* ``kimsufi-ca`` for Kimsufi North America API
See Configuration_ for more information on available configuration mechanisms.
.. note:: When using a versioning system, make sure to add ``ovh.conf`` to ignored
files. It contains confidential/security-sensitive information!
3. Authorize your application to access a customer account using OAuth2
***********************************************************************
``python-ovh`` supports two forms of authentication:
* OAuth2, using scopped service accounts, and compatible with OVHcloud IAM
* application key & application secret & consumer key (covered in the next chapter)
For OAuth2, first, you need to generate a pair of valid ``client_id`` and ``client_secret``: you
can proceed by [following this documentation](https://help.ovhcloud.com/csm/en-manage-service-account?id=kb_article_view&sysparm_article=KB0059343)
Once you have retrieved your ``client_id`` and ``client_secret``, you can create and edit
a configuration file that will be used by ``python-ovh``.
4. Authorize your application to access a customer account using custom OVHcloud authentication
***********************************************************************************************
To allow your application to access a customer account using the API on your
behalf, you need a **consumer key (CK)**.
Here is a sample code you can use to allow your application to access a
customer's information:
.. code:: python
import ovh
# create a client using configuration
client = ovh.Client()
# Request RO, /me API access
ck = client.new_consumer_key_request()
ck.add_rules(ovh.API_READ_ONLY, "/me")
# Request token
validation = ck.request()
print("Please visit %s to authenticate" % validation['validationUrl'])
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 ``add_recursive_rules``:
.. code:: python
# Allow all GET, POST, PUT, DELETE on /* (full API)
ck.add_recursive_rules(ovh.API_READ_WRITE, '/')
Install a new mail redirection
------------------------------
e-mail redirections may be freely configured on domains and DNS zones hosted by
OVHcloud to an arbitrary destination e-mail using API call
``POST /email/domain/{domain}/redirection``.
For this call, the api specifies that the source address shall be given under the
``from`` keyword. Which is a problem as this is also a reserved Python keyword.
In this case, simply prefix it with a '_', the wrapper will automatically detect
it as being a prefixed reserved keyword and will substitute it. Such aliasing
is only supported with reserved keywords.
.. code:: python
import ovh
DOMAIN = "example.com"
SOURCE = "sales@example.com"
DESTINATION = "contact@example.com"
# create a client
client = ovh.Client()
# Create a new alias
client.post('/email/domain/%s/redirection' % DOMAIN,
_from=SOURCE,
to=DESTINATION,
localCopy=False
)
print("Installed new mail redirection from %s to %s" % (SOURCE, DESTINATION))
Grab bill list
--------------
Let's say you want to integrate OVHcloud bills into your own billing system, you
could just script around the ``/me/bills`` endpoints and even get the details
of each bill lines using ``/me/bill/{billId}/details/{billDetailId}``.
This example assumes an existing Configuration_ with valid ``application_key``,
``application_secret`` and ``consumer_key``.
.. code:: python
import ovh
# create a client
client = ovh.Client()
# 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'],
))
Enable network burst in SBG1
----------------------------
'Network burst' is a free service but is opt-in. What if you have, say, 10
servers in ``SBG-1`` datacenter? You certainly don't want to activate it
manually for each servers. You could take advantage of a code like this.
This example assumes an existing Configuration_ with valid ``application_key``,
``application_secret`` and ``consumer_key``.
.. code:: python
import ovh
# create a client
client = ovh.Client()
# 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)
List application authorized to access your account
--------------------------------------------------
Thanks to the application key / consumer key mechanism, it is possible to
finely track applications having access to your data and revoke this access.
This examples lists validated applications. It could easily be adapted to
manage revocation too.
This example assumes an existing Configuration_ with valid ``application_key``,
``application_secret`` and ``consumer_key``.
.. code:: python
import ovh
from tabulate import tabulate
# create a client
client = ovh.Client()
credentials = client.get('/me/api/credential', status='validated')
# pretty print credentials status
table = []
for credential_id in credentials:
credential_method = '/me/api/credential/'+str(credential_id)
credential = client.get(credential_method)
application = client.get(credential_method+'/application')
table.append([
credential_id,
'[%s] %s' % (application['status'], application['name']),
application['description'],
credential['creation'],
credential['expiration'],
credential['lastUse'],
])
print(tabulate(table, headers=['ID', 'App Name', 'Description',
'Token Creation', 'Token Expiration', 'Token Last Use']))
Before running this example, make sure you have the
`tabulate <https://pypi.python.org/pypi/tabulate>`_ library installed. It's a
pretty cool library to pretty print tabular data in a clean and easy way.
>>> pip install tabulate
Open a KVM (remote screen) on a dedicated server
------------------------------------------------
Recent dedicated servers come with an IPMI interface. A lightweight control board embedded
on the server. Using IPMI, it is possible to get a remote screen on a server. This is
particularly useful to tweak the BIOS or troubleshoot boot issues.
Hopefully, this can easily be automated using a simple script. It assumes Java Web Start is
fully installed on the machine and a consumer key allowed on the server exists.
.. code:: python
import ovh
import sys
import time
import tempfile
import subprocess
# check arguments
if len(sys.argv) != 3:
print("Usage: %s SERVER_NAME ALLOWED_IP_V4" % sys.argv[0])
sys.exit(1)
server_name = sys.argv[1]
allowed_ip = sys.argv[2]
# create a client
client = ovh.Client()
# create a KVM
client.post('/dedicated/server/'+server_name+'/features/ipmi/access', ipToAllow=allowed_ip, ttl=15, type="kvmipJnlp")
# open the KVM, when ready
while True:
try:
# use a named temfile and feed it to java web start
with tempfile.NamedTemporaryFile() as f:
f.write(client.get('/dedicated/server/'+server_name+'/features/ipmi/access?type=kvmipJnlp')['value'])
f.flush()
subprocess.call(["javaws", f.name])
break
except:
time.sleep(1)
Running is only a simple command line:
.. code:: bash
# Basic
python open_kvm.py ns1234567.ip-42-42-42.eu $(curl ifconfig.ovh)
# Use a specific consumer key
OVH_CONSUMER_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA python open_kvm.py ns1234567.ip-42-42-42.eu $(curl -s ifconfig.ovh)
Configuration
=============
You have 3 ways to provide configuration to the client:
- write it directly in the application code
- read environment variables or predefined configuration files
- read it from a custom configuration file
Embed the configuration in the code
-----------------------------------
The straightforward way to use OVHcloud's API keys is to embed them directly in the
application code. While this is very convenient, it lacks of elegance and
flexibility.
Example usage:
.. code:: python
client = ovh.Client(
endpoint='ovh-eu',
application_key='<application key>',
application_secret='<application secret>',
consumer_key='<consumer key>',
)
Environment vars and predefined configuration files
---------------------------------------------------
Alternatively it is suggested to use configuration files or environment
variables so that the same code may run seamlessly in multiple environments.
Production and development for instance.
This wrapper will first look for direct instantiation parameters then
``OVH_ENDPOINT``, ``OVH_APPLICATION_KEY``, ``OVH_APPLICATION_SECRET`` and
``OVH_CONSUMER_KEY`` environment variables. If either of these parameter is not
provided, it will look for a configuration file of the form:
.. code:: ini
[default]
; general configuration: default endpoint
endpoint=ovh-eu
[ovh-eu]
; configuration specific to 'ovh-eu' endpoint
application_key=my_app_key
application_secret=my_application_secret
consumer_key=my_consumer_key
The client will successively attempt to locate this configuration file in
1. Current working directory: ``./ovh.conf``
2. Current user's home directory ``~/.ovh.conf``
3. System wide configuration ``/etc/ovh.conf``
This lookup mechanism makes it easy to overload credentials for a specific
project or user.
Example usage:
.. code:: python
client = ovh.Client()
Use v1 and v2 API versions
--------------------------
When using OVHcloud APIs (not So you Start or Kimsufi ones), you are given the
opportunity to aim for two API versions. For the European API, for example:
- the v1 is reachable through https://eu.api.ovh.com/v1
- the v2 is reachable through https://eu.api.ovh.com/v2
- the legacy URL is https://eu.api.ovh.com/1.0
Calling ``client.get``, you can target the API version you want:
.. code:: python
client = ovh.Client(endpoint="ovh-eu")
# Call to https://eu.api.ovh.com/v1/xdsl/xdsl-yourservice
client.get("/v1/xdsl/xdsl-yourservice")
# Call to https://eu.api.ovh.com/v2/xdsl/xdsl-yourservice
client.get("/v2/xdsl/xdsl-yourservice")
# Legacy call to https://eu.api.ovh.com/1.0/xdsl/xdsl-yourservice
client.get("/xdsl/xdsl-yourservice")
Custom configuration file
-------------------------
You can also specify a custom configuration file. With this method, you won't be able to inherit values from environment.
Example usage:
.. code:: python
client = ovh.Client(config_file='/my/config.conf')
Passing parameters
==================
You can call all the methods of the API with the necessary arguments.
If an API needs an argument colliding with a Python reserved keyword, it
can be prefixed with an underscore. For example, ``from`` argument of
``POST /email/domain/{domain}/redirection`` may be replaced by ``_from``.
With characters invalid in python argument name like a dot, you can:
.. code:: python
import ovh
params = {}
params['date.from'] = '2014-01-01'
params['date.to'] = '2015-01-01'
# create a client
client = ovh.Client()
# pass parameters using **
client.post('/me/bills', **params)
Advanced usage
==============
Un-authenticated calls
----------------------
If the user has not authenticated yet (ie, there is no valid Consumer Key), you
may force ``python-ovh`` to issue the call by passing ``_need_auth=True`` to
the high level ``get()``, ``post()``, ``put()`` and ``delete()`` helpers or
``need_auth=True`` to the low level method ``Client.call()`` and
``Client.raw_call()``.
This is needed when calling ``POST /auth/credential`` and ``GET /auth/time``
which are used internally for authentication and can optionally be done for
most of the ``/order`` calls.
Access the raw requests response objects
----------------------------------------
The high level ``get()``, ``post()``, ``put()`` and ``delete()`` helpers as well
as the lower level ``call()`` will returned a parsed json response or raise in
case of error.
In some rare scenario, advanced setups, you may need to perform customer
processing on the raw request response. It may be accessed via ``raw_call()``.
This is the lowest level call in ``python-ovh``. See the source for more
information.
Hacking
=======
This wrapper uses standard Python tools, so you should feel at home with it.
Here is a quick outline of what it may look like. A good practice is to run
this from a ``virtualenv``.
Get the sources
---------------
.. code:: bash
git clone https://github.com/ovh/python-ovh.git
cd python-ovh
python setup.py develop
You've developed a new cool feature? Fixed an annoying bug? We'd be happy
to hear from you!
Run the tests
-------------
Simply run ``pytest``. It will automatically load its configuration from
``setup.cfg`` and output full coverage status. Since we all love quality, please
note that we do not accept contributions with test coverage under 100%.
.. code:: bash
pip install -e .[dev]
pytest
Build the documentation
-----------------------
Documentation is managed using the excellent ``Sphinx`` system. For example, to
build HTML documentation:
.. code:: bash
cd python-ovh/docs
make html
Supported APIs
==============
OVHcloud Europe
---------------
- **Documentation**: https://eu.api.ovh.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://eu.api.ovh.com/console
- **Create application credentials**: https://eu.api.ovh.com/createApp/
- **Create script credentials** (all keys at once): https://eu.api.ovh.com/createToken/
OVHcloud US
-----------
- **Documentation**: https://api.us.ovhcloud.com/
- **Console**: https://api.us.ovhcloud.com/console/
- **Create application credentials**: https://api.us.ovhcloud.com/createApp/
- **Create script credentials** (all keys at once): https://api.us.ovhcloud.com/createToken/
OVHcloud North America
----------------------
- **Documentation**: https://ca.api.ovh.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://ca.api.ovh.com/console
- **Create application credentials**: https://ca.api.ovh.com/createApp/
- **Create script credentials** (all keys at once): https://ca.api.ovh.com/createToken/
So you Start Europe
-------------------
- **Documentation**: https://eu.api.soyoustart.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://eu.api.soyoustart.com/console/
- **Create application credentials**: https://eu.api.soyoustart.com/createApp/
- **Create script credentials** (all keys at once): https://eu.api.soyoustart.com/createToken/
So you Start North America
--------------------------
- **Documentation**: https://ca.api.soyoustart.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://ca.api.soyoustart.com/console/
- **Create application credentials**: https://ca.api.soyoustart.com/createApp/
- **Create script credentials** (all keys at once): https://ca.api.soyoustart.com/createToken/
Kimsufi Europe
--------------
- **Documentation**: https://eu.api.kimsufi.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://eu.api.kimsufi.com/console/
- **Create application credentials**: https://eu.api.kimsufi.com/createApp/
- **Create script credentials** (all keys at once): https://eu.api.kimsufi.com/createToken/
Kimsufi North America
---------------------
- **Documentation**: https://ca.api.kimsufi.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://ca.api.kimsufi.com/console/
- **Create application credentials**: https://ca.api.kimsufi.com/createApp/
- **Create script credentials** (all keys at once): https://ca.api.kimsufi.com/createToken/
Related links
=============
- **Contribute**: https://github.com/ovh/python-ovh
- **Report bugs**: https://github.com/ovh/python-ovh/issues
- **Download**: http://pypi.python.org/pypi/ovh
License
=======
3-Clause BSD
Raw data
{
"_id": null,
"home_page": "https://api.ovh.com",
"name": "ovh",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "ovh, sdk, rest, ovhcloud",
"author": "OVHcloud team - Romain Beuque",
"author_email": "api@ml.ovh.net",
"download_url": "https://files.pythonhosted.org/packages/83/14/d8a9e302b6de0bb9b807f33f77afbfb32466a6afbbc70163b6e1f1ba8083/ovh-1.2.0.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/ovh/python-ovh/raw/master/docs/img/logo.png\n :alt: Python & OVHcloud APIs\n :target: https://pypi.python.org/pypi/ovh\n\nLightweight wrapper around OVHcloud's APIs. Handles all the hard work including\ncredential creation and requests signing.\n\n.. image:: https://img.shields.io/pypi/v/ovh.svg\n :alt: PyPi Version\n :target: https://pypi.python.org/pypi/ovh\n.. image:: https://img.shields.io/pypi/status/ovh.svg\n :alt: PyPi repository status\n :target: https://pypi.python.org/pypi/ovh\n.. image:: https://img.shields.io/pypi/pyversions/ovh.svg\n :alt: PyPi supported Python versions\n :target: https://pypi.python.org/pypi/ovh\n.. image:: https://img.shields.io/pypi/wheel/ovh.svg\n :alt: PyPi Wheel status\n :target: https://pypi.python.org/pypi/ovh\n.. image:: https://github.com/ovh/python-ovh/actions/workflows/test.yaml/badge.svg?branch=master\n :alt: Build Status\n :target: https://github.com/ovh/python-ovh/actions/workflows/test.yaml\n.. image:: https://coveralls.io/repos/github/ovh/python-ovh/badge.svg\n :alt: Coverage Status\n :target: https://coveralls.io/github/ovh/python-ovh\n\n.. code:: python\n\n import ovh\n\n # Instantiate. Visit https://api.ovh.com/createToken/?GET=/me\n # to get your credentials\n client = ovh.Client(\n endpoint='ovh-eu',\n application_key='<application key>',\n application_secret='<application secret>',\n consumer_key='<consumer key>',\n )\n\n # Print nice welcome message\n print(\"Welcome\", client.get('/me')['firstname'])\n\nInstallation\n============\n\nThe python wrapper works with Python 3.7+.\n\nThe easiest way to get the latest stable release is to grab it from `pypi\n<https://pypi.python.org/pypi/ovh>`_ using ``pip``.\n\n.. code:: bash\n\n pip install ovh\n\nAlternatively, you may get latest development version directly from Git.\n\n.. code:: bash\n\n pip install -e git+https://github.com/ovh/python-ovh.git#egg=ovh\n\nPeople looking for Python 2 compatibility should use 0.6.x version.\n\nExample Usage\n=============\n\nUse the API on behalf of a user\n-------------------------------\n\n1. Create an application\n************************\n\nTo interact with the APIs, the SDK needs to identify itself using an\n``application_key`` and an ``application_secret``. To get them, you need\nto register your application. Depending the API you plan to use, visit:\n\n- `OVHcloud Europe <https://eu.api.ovh.com/createApp/>`_\n- `OVHcloud US <https://api.us.ovhcloud.com/createApp/>`_\n- `OVHcloud North-America <https://ca.api.ovh.com/createApp/>`_\n- `So you Start Europe <https://eu.api.soyoustart.com/createApp/>`_\n- `So you Start North America <https://ca.api.soyoustart.com/createApp/>`_\n- `Kimsufi Europe <https://eu.api.kimsufi.com/createApp/>`_\n- `Kimsufi North America <https://ca.api.kimsufi.com/createApp/>`_\n\nOnce created, you will obtain an **application key (AK)** and an **application\nsecret (AS)**.\n\n2. Configure your application\n*****************************\n\nThe easiest and safest way to use your application's credentials is to create an\n``ovh.conf`` configuration file in application's working directory. Here is how\nit looks like:\n\n.. code:: ini\n\n [default]\n ; general configuration: default endpoint\n endpoint=ovh-eu\n\n [ovh-eu]\n ; configuration specific to 'ovh-eu' endpoint\n application_key=my_app_key\n application_secret=my_application_secret\n ; uncomment following line when writing a script application\n ; with a single consumer key.\n ;consumer_key=my_consumer_key\n ; uncomment to enable oauth2 authentication\n ;client_id=my_client_id\n ;client_secret=my_client_secret\n\nDepending on the API you want to use, you may set the ``endpoint`` to:\n\n* ``ovh-eu`` for OVHcloud Europe API\n* ``ovh-us`` for OVHcloud US API\n* ``ovh-ca`` for OVHcloud North-America API\n* ``soyoustart-eu`` for So you Start Europe API\n* ``soyoustart-ca`` for So you Start North America API\n* ``kimsufi-eu`` for Kimsufi Europe API\n* ``kimsufi-ca`` for Kimsufi North America API\n\nSee Configuration_ for more information on available configuration mechanisms.\n\n.. note:: When using a versioning system, make sure to add ``ovh.conf`` to ignored\n files. It contains confidential/security-sensitive information!\n\n3. Authorize your application to access a customer account using OAuth2\n***********************************************************************\n\n``python-ovh`` supports two forms of authentication:\n* OAuth2, using scopped service accounts, and compatible with OVHcloud IAM\n* application key & application secret & consumer key (covered in the next chapter)\n\nFor OAuth2, first, you need to generate a pair of valid ``client_id`` and ``client_secret``: you\ncan proceed by [following this documentation](https://help.ovhcloud.com/csm/en-manage-service-account?id=kb_article_view&sysparm_article=KB0059343)\n\nOnce you have retrieved your ``client_id`` and ``client_secret``, you can create and edit\na configuration file that will be used by ``python-ovh``.\n\n4. Authorize your application to access a customer account using custom OVHcloud authentication\n***********************************************************************************************\n\nTo allow your application to access a customer account using the API on your\nbehalf, you need a **consumer key (CK)**.\n\nHere is a sample code you can use to allow your application to access a\ncustomer's information:\n\n.. code:: python\n\n import ovh\n\n # create a client using configuration\n client = ovh.Client()\n\n # Request RO, /me API access\n ck = client.new_consumer_key_request()\n ck.add_rules(ovh.API_READ_ONLY, \"/me\")\n\n # Request token\n validation = ck.request()\n\n print(\"Please visit %s to authenticate\" % validation['validationUrl'])\n input(\"and press Enter to continue...\")\n\n # Print nice welcome message\n print(\"Welcome\", client.get('/me')['firstname'])\n print(\"Btw, your 'consumerKey' is '%s'\" % validation['consumerKey'])\n\nReturned ``consumerKey`` should then be kept to avoid re-authenticating your\nend-user on each use.\n\n.. note:: To request full and unlimited access to the API, you may use ``add_recursive_rules``:\n\n.. code:: python\n\n # Allow all GET, POST, PUT, DELETE on /* (full API)\n ck.add_recursive_rules(ovh.API_READ_WRITE, '/')\n\nInstall a new mail redirection\n------------------------------\n\ne-mail redirections may be freely configured on domains and DNS zones hosted by\nOVHcloud to an arbitrary destination e-mail using API call\n``POST /email/domain/{domain}/redirection``.\n\nFor this call, the api specifies that the source address shall be given under the\n``from`` keyword. Which is a problem as this is also a reserved Python keyword.\nIn this case, simply prefix it with a '_', the wrapper will automatically detect\nit as being a prefixed reserved keyword and will substitute it. Such aliasing\nis only supported with reserved keywords.\n\n.. code:: python\n\n import ovh\n\n DOMAIN = \"example.com\"\n SOURCE = \"sales@example.com\"\n DESTINATION = \"contact@example.com\"\n\n # create a client\n client = ovh.Client()\n\n # Create a new alias\n client.post('/email/domain/%s/redirection' % DOMAIN,\n _from=SOURCE,\n to=DESTINATION,\n localCopy=False\n )\n print(\"Installed new mail redirection from %s to %s\" % (SOURCE, DESTINATION))\n\nGrab bill list\n--------------\n\nLet's say you want to integrate OVHcloud bills into your own billing system, you\ncould just script around the ``/me/bills`` endpoints and even get the details\nof each bill lines using ``/me/bill/{billId}/details/{billDetailId}``.\n\nThis example assumes an existing Configuration_ with valid ``application_key``,\n``application_secret`` and ``consumer_key``.\n\n.. code:: python\n\n import ovh\n\n # create a client\n client = ovh.Client()\n\n # Grab bill list\n bills = client.get('/me/bill')\n for bill in bills:\n details = client.get('/me/bill/%s' % bill)\n print(\"%12s (%s): %10s --> %s\" % (\n bill,\n details['date'],\n details['priceWithTax']['text'],\n details['pdfUrl'],\n ))\n\nEnable network burst in SBG1\n----------------------------\n\n'Network burst' is a free service but is opt-in. What if you have, say, 10\nservers in ``SBG-1`` datacenter? You certainly don't want to activate it\nmanually for each servers. You could take advantage of a code like this.\n\nThis example assumes an existing Configuration_ with valid ``application_key``,\n``application_secret`` and ``consumer_key``.\n\n.. code:: python\n\n import ovh\n\n # create a client\n client = ovh.Client()\n\n # get list of all server names\n servers = client.get('/dedicated/server/')\n\n # find all servers in SBG-1 datacenter\n for server in servers:\n details = client.get('/dedicated/server/%s' % server)\n if details['datacenter'] == 'sbg1':\n # enable burst on server\n client.put('/dedicated/server/%s/burst' % server, status='active')\n print(\"Enabled burst for %s server located in SBG-1\" % server)\n\nList application authorized to access your account\n--------------------------------------------------\n\nThanks to the application key / consumer key mechanism, it is possible to\nfinely track applications having access to your data and revoke this access.\nThis examples lists validated applications. It could easily be adapted to\nmanage revocation too.\n\nThis example assumes an existing Configuration_ with valid ``application_key``,\n``application_secret`` and ``consumer_key``.\n\n.. code:: python\n\n import ovh\n from tabulate import tabulate\n\n # create a client\n client = ovh.Client()\n\n credentials = client.get('/me/api/credential', status='validated')\n\n # pretty print credentials status\n table = []\n for credential_id in credentials:\n credential_method = '/me/api/credential/'+str(credential_id)\n credential = client.get(credential_method)\n application = client.get(credential_method+'/application')\n\n table.append([\n credential_id,\n '[%s] %s' % (application['status'], application['name']),\n application['description'],\n credential['creation'],\n credential['expiration'],\n credential['lastUse'],\n ])\n print(tabulate(table, headers=['ID', 'App Name', 'Description',\n 'Token Creation', 'Token Expiration', 'Token Last Use']))\n\nBefore running this example, make sure you have the\n`tabulate <https://pypi.python.org/pypi/tabulate>`_ library installed. It's a\npretty cool library to pretty print tabular data in a clean and easy way.\n\n>>> pip install tabulate\n\n\nOpen a KVM (remote screen) on a dedicated server\n------------------------------------------------\n\nRecent dedicated servers come with an IPMI interface. A lightweight control board embedded\non the server. Using IPMI, it is possible to get a remote screen on a server. This is\nparticularly useful to tweak the BIOS or troubleshoot boot issues.\n\nHopefully, this can easily be automated using a simple script. It assumes Java Web Start is\nfully installed on the machine and a consumer key allowed on the server exists.\n\n.. code:: python\n\n import ovh\n import sys\n import time\n import tempfile\n import subprocess\n\n # check arguments\n if len(sys.argv) != 3:\n print(\"Usage: %s SERVER_NAME ALLOWED_IP_V4\" % sys.argv[0])\n sys.exit(1)\n\n server_name = sys.argv[1]\n allowed_ip = sys.argv[2]\n\n # create a client\n client = ovh.Client()\n\n # create a KVM\n client.post('/dedicated/server/'+server_name+'/features/ipmi/access', ipToAllow=allowed_ip, ttl=15, type=\"kvmipJnlp\")\n\n # open the KVM, when ready\n while True:\n try:\n # use a named temfile and feed it to java web start\n with tempfile.NamedTemporaryFile() as f:\n f.write(client.get('/dedicated/server/'+server_name+'/features/ipmi/access?type=kvmipJnlp')['value'])\n f.flush()\n subprocess.call([\"javaws\", f.name])\n break\n except:\n time.sleep(1)\n\nRunning is only a simple command line:\n\n.. code:: bash\n\n # Basic\n python open_kvm.py ns1234567.ip-42-42-42.eu $(curl ifconfig.ovh)\n\n # Use a specific consumer key\n OVH_CONSUMER_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA python open_kvm.py ns1234567.ip-42-42-42.eu $(curl -s ifconfig.ovh)\n\nConfiguration\n=============\n\nYou have 3 ways to provide configuration to the client:\n - write it directly in the application code\n - read environment variables or predefined configuration files\n - read it from a custom configuration file\n\nEmbed the configuration in the code\n-----------------------------------\n\nThe straightforward way to use OVHcloud's API keys is to embed them directly in the\napplication code. While this is very convenient, it lacks of elegance and\nflexibility.\n\nExample usage:\n\n.. code:: python\n\n client = ovh.Client(\n endpoint='ovh-eu',\n application_key='<application key>',\n application_secret='<application secret>',\n consumer_key='<consumer key>',\n )\n\nEnvironment vars and predefined configuration files\n---------------------------------------------------\n\nAlternatively it is suggested to use configuration files or environment\nvariables so that the same code may run seamlessly in multiple environments.\nProduction and development for instance.\n\nThis wrapper will first look for direct instantiation parameters then\n``OVH_ENDPOINT``, ``OVH_APPLICATION_KEY``, ``OVH_APPLICATION_SECRET`` and\n``OVH_CONSUMER_KEY`` environment variables. If either of these parameter is not\nprovided, it will look for a configuration file of the form:\n\n.. code:: ini\n\n [default]\n ; general configuration: default endpoint\n endpoint=ovh-eu\n\n [ovh-eu]\n ; configuration specific to 'ovh-eu' endpoint\n application_key=my_app_key\n application_secret=my_application_secret\n consumer_key=my_consumer_key\n\nThe client will successively attempt to locate this configuration file in\n\n1. Current working directory: ``./ovh.conf``\n2. Current user's home directory ``~/.ovh.conf``\n3. System wide configuration ``/etc/ovh.conf``\n\nThis lookup mechanism makes it easy to overload credentials for a specific\nproject or user.\n\nExample usage:\n\n.. code:: python\n\n client = ovh.Client()\n\nUse v1 and v2 API versions\n--------------------------\n\nWhen using OVHcloud APIs (not So you Start or Kimsufi ones), you are given the\nopportunity to aim for two API versions. For the European API, for example:\n\n- the v1 is reachable through https://eu.api.ovh.com/v1\n- the v2 is reachable through https://eu.api.ovh.com/v2\n- the legacy URL is https://eu.api.ovh.com/1.0\n\n Calling ``client.get``, you can target the API version you want:\n\n.. code:: python\n\n client = ovh.Client(endpoint=\"ovh-eu\")\n\n # Call to https://eu.api.ovh.com/v1/xdsl/xdsl-yourservice\n client.get(\"/v1/xdsl/xdsl-yourservice\")\n\n # Call to https://eu.api.ovh.com/v2/xdsl/xdsl-yourservice\n client.get(\"/v2/xdsl/xdsl-yourservice\")\n\n # Legacy call to https://eu.api.ovh.com/1.0/xdsl/xdsl-yourservice\n client.get(\"/xdsl/xdsl-yourservice\")\n\nCustom configuration file\n-------------------------\n\nYou can also specify a custom configuration file. With this method, you won't be able to inherit values from environment.\n\nExample usage:\n\n.. code:: python\n\n client = ovh.Client(config_file='/my/config.conf')\n\nPassing parameters\n==================\n\nYou can call all the methods of the API with the necessary arguments.\n\nIf an API needs an argument colliding with a Python reserved keyword, it\ncan be prefixed with an underscore. For example, ``from`` argument of\n``POST /email/domain/{domain}/redirection`` may be replaced by ``_from``.\n\nWith characters invalid in python argument name like a dot, you can:\n\n.. code:: python\n\n import ovh\n\n params = {}\n params['date.from'] = '2014-01-01'\n params['date.to'] = '2015-01-01'\n\n # create a client\n client = ovh.Client()\n\n # pass parameters using **\n client.post('/me/bills', **params)\n\nAdvanced usage\n==============\n\nUn-authenticated calls\n----------------------\n\nIf the user has not authenticated yet (ie, there is no valid Consumer Key), you\nmay force ``python-ovh`` to issue the call by passing ``_need_auth=True`` to\nthe high level ``get()``, ``post()``, ``put()`` and ``delete()`` helpers or\n``need_auth=True`` to the low level method ``Client.call()`` and\n``Client.raw_call()``.\n\nThis is needed when calling ``POST /auth/credential`` and ``GET /auth/time``\nwhich are used internally for authentication and can optionally be done for\nmost of the ``/order`` calls.\n\nAccess the raw requests response objects\n----------------------------------------\n\nThe high level ``get()``, ``post()``, ``put()`` and ``delete()`` helpers as well\nas the lower level ``call()`` will returned a parsed json response or raise in\ncase of error.\n\nIn some rare scenario, advanced setups, you may need to perform customer\nprocessing on the raw request response. It may be accessed via ``raw_call()``.\nThis is the lowest level call in ``python-ovh``. See the source for more\ninformation.\n\nHacking\n=======\n\nThis wrapper uses standard Python tools, so you should feel at home with it.\nHere is a quick outline of what it may look like. A good practice is to run\nthis from a ``virtualenv``.\n\nGet the sources\n---------------\n\n.. code:: bash\n\n git clone https://github.com/ovh/python-ovh.git\n cd python-ovh\n python setup.py develop\n\nYou've developed a new cool feature? Fixed an annoying bug? We'd be happy\nto hear from you!\n\nRun the tests\n-------------\n\nSimply run ``pytest``. It will automatically load its configuration from\n``setup.cfg`` and output full coverage status. Since we all love quality, please\nnote that we do not accept contributions with test coverage under 100%.\n\n.. code:: bash\n\n pip install -e .[dev]\n pytest\n\nBuild the documentation\n-----------------------\n\nDocumentation is managed using the excellent ``Sphinx`` system. For example, to\nbuild HTML documentation:\n\n.. code:: bash\n\n cd python-ovh/docs\n make html\n\nSupported APIs\n==============\n\nOVHcloud Europe\n---------------\n\n- **Documentation**: https://eu.api.ovh.com/\n- **Community support**: api-subscribe@ml.ovh.net\n- **Console**: https://eu.api.ovh.com/console\n- **Create application credentials**: https://eu.api.ovh.com/createApp/\n- **Create script credentials** (all keys at once): https://eu.api.ovh.com/createToken/\n\nOVHcloud US\n-----------\n\n- **Documentation**: https://api.us.ovhcloud.com/\n- **Console**: https://api.us.ovhcloud.com/console/\n- **Create application credentials**: https://api.us.ovhcloud.com/createApp/\n- **Create script credentials** (all keys at once): https://api.us.ovhcloud.com/createToken/\n\nOVHcloud North America\n----------------------\n\n- **Documentation**: https://ca.api.ovh.com/\n- **Community support**: api-subscribe@ml.ovh.net\n- **Console**: https://ca.api.ovh.com/console\n- **Create application credentials**: https://ca.api.ovh.com/createApp/\n- **Create script credentials** (all keys at once): https://ca.api.ovh.com/createToken/\n\nSo you Start Europe\n-------------------\n\n- **Documentation**: https://eu.api.soyoustart.com/\n- **Community support**: api-subscribe@ml.ovh.net\n- **Console**: https://eu.api.soyoustart.com/console/\n- **Create application credentials**: https://eu.api.soyoustart.com/createApp/\n- **Create script credentials** (all keys at once): https://eu.api.soyoustart.com/createToken/\n\nSo you Start North America\n--------------------------\n\n- **Documentation**: https://ca.api.soyoustart.com/\n- **Community support**: api-subscribe@ml.ovh.net\n- **Console**: https://ca.api.soyoustart.com/console/\n- **Create application credentials**: https://ca.api.soyoustart.com/createApp/\n- **Create script credentials** (all keys at once): https://ca.api.soyoustart.com/createToken/\n\nKimsufi Europe\n--------------\n\n- **Documentation**: https://eu.api.kimsufi.com/\n- **Community support**: api-subscribe@ml.ovh.net\n- **Console**: https://eu.api.kimsufi.com/console/\n- **Create application credentials**: https://eu.api.kimsufi.com/createApp/\n- **Create script credentials** (all keys at once): https://eu.api.kimsufi.com/createToken/\n\nKimsufi North America\n---------------------\n\n- **Documentation**: https://ca.api.kimsufi.com/\n- **Community support**: api-subscribe@ml.ovh.net\n- **Console**: https://ca.api.kimsufi.com/console/\n- **Create application credentials**: https://ca.api.kimsufi.com/createApp/\n- **Create script credentials** (all keys at once): https://ca.api.kimsufi.com/createToken/\n\nRelated links\n=============\n\n- **Contribute**: https://github.com/ovh/python-ovh\n- **Report bugs**: https://github.com/ovh/python-ovh/issues\n- **Download**: http://pypi.python.org/pypi/ovh\n\nLicense\n=======\n\n3-Clause BSD\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "\"Official module to perform HTTP requests to the OVHcloud APIs\"",
"version": "1.2.0",
"project_urls": {
"Changelog": "https://github.com/ovh/python-ovh/blob/master/CHANGELOG.md",
"Homepage": "https://api.ovh.com",
"Issues": "https://github.com/ovh/python-ovh/issues",
"Repository": "https://github.com/ovh/python-ovh.git"
},
"split_keywords": [
"ovh",
" sdk",
" rest",
" ovhcloud"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fae15b64ce848fe2a85b0aabad5b883fa00beadbe79d70e6654914a3e831d037",
"md5": "5969878d1195ba4e26c8d784296eccfa",
"sha256": "0e9940bd53fc615dc89d3cfcd80f07282a4ad9f083c3f769b6fb98d501938307"
},
"downloads": -1,
"filename": "ovh-1.2.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5969878d1195ba4e26c8d784296eccfa",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 24899,
"upload_time": "2024-07-23T14:53:24",
"upload_time_iso_8601": "2024-07-23T14:53:24.693972Z",
"url": "https://files.pythonhosted.org/packages/fa/e1/5b64ce848fe2a85b0aabad5b883fa00beadbe79d70e6654914a3e831d037/ovh-1.2.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8314d8a9e302b6de0bb9b807f33f77afbfb32466a6afbbc70163b6e1f1ba8083",
"md5": "eb6bf5e416c3b6aac350e9b3e825ac28",
"sha256": "d311f08ec17b62cc61216b3dacf03ee89f95a1da9036a595dac29fc9d798b827"
},
"downloads": -1,
"filename": "ovh-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "eb6bf5e416c3b6aac350e9b3e825ac28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 119764,
"upload_time": "2024-07-23T14:53:27",
"upload_time_iso_8601": "2024-07-23T14:53:27.044878Z",
"url": "https://files.pythonhosted.org/packages/83/14/d8a9e302b6de0bb9b807f33f77afbfb32466a6afbbc70163b6e1f1ba8083/ovh-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-23 14:53:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ovh",
"github_project": "python-ovh",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "ovh"
}
JSON
