Welcome to iland-sdk’s documentation!

Contents:

iland-sdk

https://img.shields.io/pypi/v/iland-sdk.svg https://travis-ci.org/ilanddev/python-sdk.svg?branch=master Documentation Status Requirements Status

iland cloud Python SDK

Introduction

This library provides a pure Python interface for the iland cloud API version 1.0. It works with Python versions from 2.7+.

iland cloud provides Enterprise-grade IaaS and this library is intended to make it even easier for Python programmers to use.

Getting the code

The code is hosted at https://github.com/ilanddev/python-sdk

Check out the latest development version anonymously with:

$ git clone https://github.com/ilanddev/python-sdk.git
$ cd python-sdk

Installation

At the command line:

$ pip install iland-sdk

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv iland-sdk
$ pip install iland-sdk

You can also install iland-sdk using the actual source checkout:

$ git clone https://github.com/ilanddev/python-sdk.git

$ cd python-sdk

$ pip install -e .

Running Tests

To run the unit tests:

$ make test

To run the unit tests for all supported Python interpreters:

$ make test-all

To check your changes before submitting a pull request:

$ make lint

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

Usage

To use iland-sdk in a project:

import iland

The API is exposed via the iland.Api class.

To create an instance of the iland.Api:

>>> import iland
>>> api = iland.Api(client_id=CLIENT_ID,
                    client_secret=CLIENT_SECRET,
                    username=USERNAME,
                    password=PASSWORD)

You can then perform GET, PUT, POST and DELETE requests against the iland cloud:

>>> user = api.get('/user/' + USERNAME)
>>> user.get('name'))
USERNAME

>>> user_alert_emails = {'emails': ['test@iland.com', 'test2@iland.com'],
                         'username': USERNAME}
>>> api.post('/user/' + USERNAME + '/alert-emails', user_alert_emails)

To use a proxy you can define a python-requests style proxies dictionary and set the _proxies attribute on the api object:

>>> api = iland.Api(client_id=CLIENT_ID,
                    client_secret=CLIENT_SECRET,
                    username=USERNAME,
                    password=PASSWORD)
>>> api._proxies = {'https': 'https://10.10.1.10:3128'}
>>> user = api.get('/user/' + USERNAME)

iland

iland package

Submodules

iland.api module

A library that provides a Python interface to the iland cloud API.

class iland.api.Api(client_id, client_secret, username, password)[source]

Bases: object

A Python interface into the iland cloud API

delete(rpath, headers=None)[source]

Perform a DELETE request against the iland cloud API given its resource path.

iland.Api will refresh the access token if non valid.

Parameters:
  • rpath – the resource path as a Python builtin String object
  • headers – an optional dictionary of http headers to send with the request
Raises:

ApiException: API requests returns an error

Raises:

UnauthorizedException: credentials / grants invalids

Returns:

a JSON Object or a list of JSON Objects.

get(rpath, headers=None)[source]

Perform a GET request against the iland cloud API given its resource path.

iland.Api will refresh the access token if non valid.

Parameters:
  • rpath – the resource path as a Python builtin String object
  • headers – an optional dictionary of http headers to send with the request
Raises:

ApiException: API requests returns an error

Raises:

UnauthorizedException: credentials / grants invalids

Returns:

a JSON Object or a list of JSON Objects.

get_access_token()[source]

Returns the access token in use for this session.

This method is exposed in case you are interested in managing the token life cycle yourself. iland.Api will refresh the token on your behalf while performing queries.

Raises:UnauthorizedException: credentials / grants invalids
Returns:JSON Object containing the actual access token
login()[source]

Requests an access token.

This method is exposed in case you are interested in managing the token life cycle yourself. iland.Api will refresh the token on your behalf while performing queries.

Raises:UnauthorizedException: credentials / grants invalids
Returns:JSON Object containing the actual access token
post(rpath, form_data=None, headers=None)[source]

Perform a POST request against the iland cloud API given its resource path.

iland.Api will refresh the access token if non valid.

Parameters:
  • rpath – the resource path as a Python builtin String object
  • form_data – a Python builtin dict object
  • headers – an optional dictionary of http headers to send with the request
Raises:

ApiException: API requests returns an error

Raises:

UnauthorizedException: credentials / grants invalids

Returns:

a JSON Object or a list of JSON Objects.

put(rpath, form_data=None, headers=None)[source]

Perform a PUT request against the iland cloud API given its resource path.

iland.Api will refresh the access token if non valid.

Parameters:
  • rpath – the resource path as a Python builtin String object
  • form_data – a Python builtin dict object
  • headers – an optional dictionary of http headers to send with the request
Raises:

ApiException: API requests returns an error

Raises:

UnauthorizedException: credentials / grants invalids

Returns:

a JSON Object or a list of JSON Objects.

refresh_access_token()[source]

Refresh token if token is not valid: None or expired.

This method is exposed in case you are interested in managing the token life cycle yourself. iland.Api will refresh the token on your behalf while performing queries.

Raises:UnauthorizedException: credentials / grants invalids
Returns:JSON Object containing the actual access token

iland.constant module

A library that provides constants for the iland.Api object.

iland.constant.ACCESS_URL = 'https://console.ilandcloud.com/auth/realms/iland-core/protocol/openid-connect/token'

Access token URL.

iland.constant.BASE_URL = 'https://api.ilandcloud.com/v1'

Base URL to the iland cloud API.

iland.exception module

A library that provides custom exceptions for the iland.Api module.

exception iland.exception.ApiException[source]

Bases: exceptions.Exception

Base class for iland.Api errors.

detail_message

Returns the third argument used to construct this error.

error

Returns the first argument used to construct this error.

message

Returns the second argument used to construct this error.

exception iland.exception.UnauthorizedException[source]

Bases: iland.exception.ApiException

Unauthorized iland.Api exception.

iland.log module

A library that provides a custom logger for the iland.Api object.

iland.log.LOG = <logging.Logger object>

A custom Python logging logger for the iland.Api object.

Module contents

A module that provides a Python interface to the iland cloud API.

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/ilanddev/python-sdk/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation

iland-sdk could always use more documentation, whether as part of the official iland-sdk docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/ilanddev/python-sdk/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up python-sdk for local development.

  1. Fork the python-sdk repo on GitHub.

  2. Clone your fork locally:

    $ git clone https://github.com/ilanddev/python-sdk.git
    
  3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv python-sdk
    $ cd python-sdk/
    $ python setup.py develop
    
  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature
    

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ make lint
    $ make test
    $ make test-all
    

    To get flake8 and tox, just pip install them into your virtualenv.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
    $ git commit -m "Your detailed description of your changes."
    $ git push origin name-of-your-bugfix-or-feature
    
  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
  3. The pull request should work for Python 2.7, 3.4 and 3.5, and for PyPy. Check https://travis-ci.org/ilanddev/python-sdk/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ python -m unittest tests.test_iland

Credits

Development Lead

Contributors

History

1.0.1 (2018-11-15)

  • doc update

1.0.0 (2018-11-15)

  • Support for iland API v1.0
  • Update outdated dependencies

0.9.0 (2018-11-13)

  • iland API v0.9

0.7.5 (2017-06-27)

  • Force iland API v0.8.
  • Update dev requirements.
  • Dependencies definition shared with setup.py
  • Add support for passing additional headers with api requests.

0.7.4 (2017-05-26)

  • Use a requests.Session object for all api calls
  • Remove base_url, access_token_url, and verify_ssl from Api constructor

0.7.3 (2017-05-18)

  • Fix internal use of REFRESH_URL when overriding access_token_url at constructor time.

0.7.2 (2017-05-17)

  • optional access_url_token Api constructor param allowing one to override token exchange URL.
  • update dependencies.
  • lower required version of requests module from ==2.14.2 to >=2.2.1.

0.7.1 (2017-02-08)

  • update outdated dependencies
  • drop Python 3.3 support “just like everybody”
  • update token exchange endpoint. We keeping BBB for old client implementations

0.7.0 (2016-10-13)

  • update token exchange endpoint. We keeping BBB for old client implementations
  • update requests lib
  • update dev dependencies
  • promote to stable

0.6.0 (2016-6-28)

  • update dependencies
  • default resource path update

0.5.0 (2016-3-22)

  • promote to beta status
  • extra verify_ssl Api constructor to allow one to not verify endpoints SSL

0.4.0 (2016-3-08)

  • support 204 no content HTTP return code
  • fix naming of _validate_token method
  • update Sphynx dependency
  • full unit tests coverage
  • fix return on POST, PUT and DELETE operations
  • fix use of custom BASE API URL

0.3.0 (2016-2-18)

  • implement exceptions handling
  • docstrings and documentation
  • Housekeeping and refactoring
  • Better CI setup
  • Sphynx doc and readthedocs.org publishing.

0.2.0 (2016-2-09)

  • Minor fixes.

0.1.0 (2016-2-09)

  • First release on PyPI.

Indices and tables