icontrol package¶

Submodules¶

icontrol.session module¶

A BigIP-RESTServer URI handler. REST-APIs use it on the requests library.

Use this module to make calls to a BigIP-REST server. It will handle:

URI Sanitization uri’s produced by this module are checked to ensure compliance with the BigIP-REST server interface
Session Construction – the iControlRESTSession wraps a requests.Session object.
Logging – pre- and post- request state is logged.
Exception generation – Errors in URL construction generate BigIPInvalidURL subclasses; unexpected HTTP status codes raise iControlUnexpectedHTTPError.

The core functionality of the module is implemented via the iControlRESTSession class. Calls to its’ HTTP-methods are checked, pre-logged, submitted, and post-logged.

There are 2 modes of operation “full_uri”, and “uri_as_parts”, toggled by the uri_as_parts boolean keyword param that can be passed to methods. It defaults to False. Use uri_as_parts when you want to leverage the full functionality of this library, and have it construct your uri for you. Example Use in uri_as_parts mode:

>>> iCRS = iControlRESTSession('jrandomhacker', 'insecure')
>>> iCRS.get('https://192.168.1.1/mgmt/tm/ltm/nat/', partition='Common', name='VALIDNAME', uri_as_parts=True)

In full_uri mode:

>>> iCRS.get('https://192.168.1.1/mgmt/tm/ltm/nat/~Common~VALIDNAME')

NOTE: If used via the f5-common-python library the typical mode is “full_uri” since that library binds uris to Python objects.

Available functions:

iCRS.{get, post, put, delete, patch}: requests.Session.VERB wrappers
decorate_HTTP_verb_method: this function preps, logs, and handles requests

against the BigIP REST Server, by pre- and post- processing the above methods.

exception icontrol.session.BigIPInvalidURL¶: Bases: exceptions.Exception

exception icontrol.session.InvalidBigIP_ICRURI¶: Bases: icontrol.session.BigIPInvalidURL

exception icontrol.session.InvalidInstanceNameOrFolder¶: Bases: icontrol.session.BigIPInvalidURL

exception icontrol.session.InvalidPrefixCollection¶: Bases: icontrol.session.BigIPInvalidURL

exception icontrol.session.InvalidScheme¶: Bases: icontrol.session.BigIPInvalidURL

exception icontrol.session.InvalidSuffixCollection¶: Bases: icontrol.session.BigIPInvalidURL

icontrol.session.decorate_HTTP_verb_method(method)¶

Prepare and Post-Process HTTP VERB method for BigIP-RESTServer request.

This function decorates all of the HTTP VERB methods in the iControlRESTSession class. It provides the core logic for this module. If necessary it validates and assembles a uri from parts with a call to generate_bigip_uri.

Then it:

pre-logs the details of the request
submits the request
logs the response, included expected status codes
raises exceptions for unexpected status codes. (i.e. not doc’d as BigIP RESTServer codes.)

icontrol.session.generate_bigip_uri(base_uri, partition, name, suffix, **kwargs)¶

(str, str, str) –> str

This function checks the supplied elements to see if each conforms to the specifiction for the appropriate part of the URI. These validations are conducted by the helper function _validate_uri_parts. After validation the parts are assembled into a valid BigIP REST URI string which is then submitted with appropriate metadata.

>>> generate_bigip_uri('https://0.0.0.0/mgmt/tm/ltm/nat/',     'CUSTOMER1', 'nat52', params={'a':1})
'https://0.0.0.0/mgmt/tm/ltm/nat/~CUSTOMER1~nat52'
>>> generate_bigip_uri('https://0.0.0.0/mgmt/tm/ltm/nat/',     'CUSTOMER1', 'nat52', params={'a':1}, suffix='/wacky')
'https://0.0.0.0/mgmt/tm/ltm/nat/~CUSTOMER1~nat52/wacky'
>>> generate_bigip_uri('https://0.0.0.0/mgmt/tm/ltm/nat/', '', '',     params={'a':1}, suffix='/thwocky')
'https://0.0.0.0/mgmt/tm/ltm/nat/thwocky'

class icontrol.session.iControlRESTSession(username, password, **kwargs)¶

Bases: object

Represents a requests.Session that communicates with a BigIP.

Instantiate one of these when you want to communicate with a BigIP-REST Server, it will handle BigIP-specific details of the uri’s. In the f5-common-python library, an iControlRESTSession is instantiated during BigIP instantiation and associated with it as an attribute of the BigIP (a compositional vs. inheritable association).

Objects instantiated from this class provide an HTTP 1.1 style session, via the requests.Session object, and HTTP-methods that are specialized to the BigIP-RESTServer interface.

delete(RIC_base_uri, **kwargs)¶

Sends a HTTP DELETE command to the BIGIP REST Server.

Use this method to send a DELETE command to the BIGIP. When calling this method with the optional arguments name and partition as part of **kwargs they will be added to the uri passed in separated by ~ to create a proper BIGIP REST API URL for objects.

All other parameters passed in as **kwargs are passed directly to the requests.Session.delete()

Parameters:	uri (str) – A HTTP URI name (str) – The object name that will be appended to the uri partition (str) – The partition name that will be appened to the uri **kwargs – The `reqeusts.Session.delete()` optional params

get(RIC_base_uri, **kwargs)¶

Sends a HTTP GET command to the BIGIP REST Server.

Use this method to send a GET command to the BIGIP. When calling this method with the optional arguments name and partition as part of **kwargs they will be added to the uri passed in separated by ~ to create a proper BIGIP REST API URL for objects.

All other parameters passed in as **kwargs are passed directly to the requests.Session.get()

Parameters:	uri (str) – A HTTP URI name (str) – The object name that will be appended to the uri partition (str) – The partition name that will be appened to the uri **kwargs – The `reqeusts.Session.get()` optional params

patch(RIC_base_uri, **kwargs)¶

Sends a HTTP PATCH command to the BIGIP REST Server.

Use this method to send a PATCH command to the BIGIP. When calling this method with the optional arguments name and partition as part of **kwargs they will be added to the uri passed in separated by ~ to create a proper BIGIP REST API URL for objects.

All other parameters passed in as **kwargs are passed directly to the requests.Session.patch()

Parameters:	uri (str) – A HTTP URI data (str) – The data to be sent with the PATCH command name (str) – The object name that will be appended to the uri partition (str) – The partition name that will be appened to the uri **kwargs – The `reqeusts.Session.patch()` optional params

post(RIC_base_uri, **kwargs)¶

Sends a HTTP POST command to the BIGIP REST Server.

Use this method to send a POST command to the BIGIP. When calling this method with the optional arguments name and partition as part of **kwargs they will be added to the uri passed in separated by ~ to create a proper BIGIP REST API URL for objects.

All other parameters passed in as **kwargs are passed directly to the requests.Session.post()

Parameters:	uri (str) – A HTTP URI data (str) – The data to be sent with the POST command json (dict) – The JSON data to be sent with the POST command name (str) – The object name that will be appended to the uri partition (str) – The partition name that will be appened to the uri **kwargs – The `reqeusts.Session.post()` optional params

put(RIC_base_uri, **kwargs)¶

Sends a HTTP PUT command to the BIGIP REST Server.

Use this method to send a PUT command to the BIGIP. When calling this method with the optional arguments name and partition as part of **kwargs they will be added to the uri passed in separated by ~ to create a proper BIGIP REST API URL for objects.

All other parameters passed in as **kwargs are passed directly to the requests.Session.put()

Parameters:	uri (str) – A HTTP URI data (str) – The data to be sent with the PUT command json (dict) – The JSON data to be sent with the PUT command name (str) – The object name that will be appended to the uri partition (str) – The partition name that will be appened to the uri **kwargs – The `reqeusts.Session.put()` optional params

exception icontrol.session.iControlUnexpectedHTTPError(*args, **kwargs)¶: Bases: requests.exceptions.HTTPError

icontrol package¶

Submodules¶

icontrol.session module¶

Module contents¶