F5 Python SDK Documentation¶

f5.bigip module¶

Classes and functions for configuring BIG-IP

resource module¶

This module provides classes that specify how RESTful resources are handled.

THE MOST IMPORTANT THING TO KNOW ABOUT THIS API IS THAT YOU CAN DIRECTLY INFER REST URIs FROM PYTHON EXPRESSIONS, AND VICE VERSA.

Examples:

• Expression: bigip = BigIP(‘a’, ‘b’, ‘c’)
• URI Returned: https://a/mgmt/tm/
• Expression: bigip.ltm
• URI Returned: https://a/mgmt/tm/ltm/
• Expression: pools1 = bigip.ltm.pools
• URI Returned: https://a/mgmt/tm/ltm/pool
• Expression: pool_a = pools1.create(partition=”Common”, name=”foo”)
• URI Returned: https://a/mgmt/tm/ltm/pool/~Common~foo

There are different types of resources published by the BIG-IP® REST Server, they are represented by the classes in this module.

We refer to a server-provided resource as a “service”. Thus far all URI referenced resources are “services” in this sense.

We use methods named Create, Refresh, Update, Load, and Delete to manipulate BIG-IP® device services.

Methods:

• create – uses HTTP POST, creates a new resource and with its own URI on the device

• refresh – uses HTTP GET, obtains the state of a device resource, and sets the representing Python Resource Object tracks device state via its attrs

• update – uses HTTP PUT, submits a new configuration to the device resource

  and sets the Resource attrs to the state the device reports

• load – uses HTTP GET, obtains the state of an existing resource on the device and sets the Resource attrs to that state

• delete – uses HTTP DELETE, removes the resource from the device, and sets self.__dict__ to {‘deleted’: True}

Available Classes:

• ResourceBase – only refresh is generally supported in all resource types, this class provides refresh. ResourceBase objects are usually instantiated via setting lazy attributes. ResourceBase provides a constructor to match its call in LazyAttributeMixin.__getattr__. The expected behavior is that all resource subclasses depend on this constructor to correctly set their self._meta_data[‘uri’]. All ResourceBase objects (except BIG-IPs) have a container (BIG-IPs contain themselves). The container is the object the ResourceBase is an attribute of.

• OrganizingCollection – These resources support lists of “reference” “links”. These are json blobs without a Python class representation.

  Example URI_path: /mgmt/tm/ltm/

• Collection – These resources support lists of ResourceBase Objects.

  Example URI_path: /mgmt/tm/ltm/nat

• Resource – These resources are the only resources that support create, update, and delete operations. Because they support HTTP post (via _create) they uniquely depend on 2 uri’s, a uri that supports the creating post, and the returned uri of the newly created resource.

  Example URI_path: /mgmt/tm/ltm/nat/~Common~testnat1

exception f5.bigip.resource.KindTypeMismatch(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

Raise this when server JSON keys are incorrect for the Resource type.

exception f5.bigip.resource.DeviceProvidesIncompatibleKey(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

Raise this when server JSON keys are incompatible with Python.

exception f5.bigip.resource.InvalidResource(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

Raise this when a caller tries to invoke an unsupported CRUDL op.

All resources support refresh and raw. Only Resource‘s support load, create, update, and delete.

exception f5.bigip.resource.MissingRequiredCreationParameter(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

Various values MUST be provided to create different Resources.

exception f5.bigip.resource.MissingRequiredReadParameter(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

Various values MUST be provided to refresh some Resources.

exception f5.bigip.resource.UnregisteredKind(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

The returned server JSON kind key wasn’t expected by this Resource.

exception f5.bigip.resource.GenerationMismatch(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

The server reported BIG-IP® is not the expacted value.

exception f5.bigip.resource.InvalidForceType[source]¶

Bases: exceptions.ValueError

Must be of type bool.

exception f5.bigip.resource.URICreationCollision(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

self._meta_data[‘uri’] can only be assigned once. In create or load.

exception f5.bigip.resource.UnsupportedOperation(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

Object does not support the method that was called.

class f5.bigip.resource.PathElement(container)[source]¶

Bases: f5.bigip.mixins.LazyAttributeMixin

Base class to represent a URI path element that does not contain data.

The BIG-IP® iControl REST API has URIs that are made up of path components that do not return data when they are queried. This class represents those elements and does not support any of the CURDLE methods that the other objects do.

raw¶

Display the attributes that the current object has and their values.

Returns:	A dictionary of attributes and their values

class f5.bigip.resource.ResourceBase(container)[source]¶

Bases: f5.bigip.resource.PathElement, f5.bigip.mixins.ToDictMixin

Base class for all BIG-IP® iControl REST API endpoints.

The BIG-IP® is represented by an object that converts device-published uri’s into Python objects. Each uri maps to a Python object. The mechanism for instantiating these objects is the __getattr__ Special Function in the LazyAttributeMixin. When a registered attribute is dot referenced, on the device object (e.g. bigip.ltm or simply bigip), an appropriate object is instantiated and attributed to the referencing object:

bigip.ltm = LTM(bigip)
bigip.ltm.nats
nat1 = bigip.ltm.nats.nat.create('Foo', 'Bar', '0.1.2.3', '1.2.3.4')

This can be shortened to just the last line:

nat1 = bigip.ltm.nats.nat.create('Foo', 'Bar', '0.1.2.3', '1.2.3.4')

Critically this enforces a convention relating device published uris to API objects, in a hierarchy similar to the uri paths. I.E. the uri corresponding to a Nats object is mgmt/tm/ltm/nat/. If you query the BIG-IP’s uri (e.g. print(bigip._meta_data[‘uri’]) ), you’ll see that it ends in: /mgmt/tm/, if you query the ltm object’s uri (e.g. print(bigip.ltm._meta_data[‘uri’]) ) you’ll see it ends in /mgmt/tm/ltm/.

In general the objects build a required self._meta_data[‘uri’] attribute by: 1. Inheriting this class. 2. calling super(Subclass, self).__init__(container) 3. self.uri = self.container_uri[‘uri’] + ‘/’ + self.__class__.__name__

The net result is a succinct mapping between uri’s and objects, that represents objects in a hierarchical relationship similar to the device’s uri path hierarchy.

update(**kwargs)[source]¶

Update the configuration of the resource on the BIG-IP®.

This method uses HTTP PUT alter the resource state on the BIG-IP®.

The attributes of the instance will be packaged as a dictionary. That dictionary will be updated with kwargs. It is then submitted as JSON to the device.

Various edge cases are handled: * read-only attributes that are unchangeable are removed

Parameters:	kwargs – keys and associated values to alter on the device

NOTE: If kwargs has a ‘requests_params’ key the corresponding dict will be passed to the underlying requests.session.put method where it will be handled according to that API. THIS IS HOW TO PASS QUERY-ARGS!

refresh(**kwargs)[source]¶

Use this to make the device resource be represented by self.

This method makes an HTTP GET query against the device service. This method is run for its side-effects on self. If successful the instance attribute __dict__ is replaced with the dict representing the device state. To figure out what that state is, run a subsequest query of the object like this: As with all CURDLE methods use a “requests_params” dict to pass parameters to requests.session.HTTPMETHOD. See test_requests_params.py for an example. >>> resource_obj.refresh() >>> print(resource_obj.raw)

create(**kwargs)[source]¶

Implement this by overriding it in a subclass of Resource

Raises:	InvalidResource

delete(**kwargs)[source]¶

Implement this by overriding it in a subclass of Resource

Raises:	InvalidResource

raw¶

Display the attributes that the current object has and their values.

Returns:	A dictionary of attributes and their values

class f5.bigip.resource.OrganizingCollection(container)[source]¶

Bases: f5.bigip.resource.ResourceBase

Base class for objects that collect resources under them.

OrganizingCollection objects fulfill the following functions:

• represent a uri path fragment immediately ‘below’ /mgmt/tm
• provide a list of dictionaries that contain uri’s to other resources on the device.

get_collection(**kwargs)[source]¶

Call to obtain a list of the reference dicts in the instance items

Returns:	List of self.items

create(**kwargs)¶

Implement this by overriding it in a subclass of Resource

Raises:	InvalidResource

delete(**kwargs)¶

Implement this by overriding it in a subclass of Resource

Raises:	InvalidResource

raw¶

Display the attributes that the current object has and their values.

Returns:	A dictionary of attributes and their values

refresh(**kwargs)¶

Use this to make the device resource be represented by self.

This method makes an HTTP GET query against the device service. This method is run for its side-effects on self. If successful the instance attribute __dict__ is replaced with the dict representing the device state. To figure out what that state is, run a subsequest query of the object like this: As with all CURDLE methods use a “requests_params” dict to pass parameters to requests.session.HTTPMETHOD. See test_requests_params.py for an example. >>> resource_obj.refresh() >>> print(resource_obj.raw)

update(**kwargs)¶

Update the configuration of the resource on the BIG-IP®.

This method uses HTTP PUT alter the resource state on the BIG-IP®.

The attributes of the instance will be packaged as a dictionary. That dictionary will be updated with kwargs. It is then submitted as JSON to the device.

Various edge cases are handled: * read-only attributes that are unchangeable are removed

Parameters:	kwargs – keys and associated values to alter on the device

NOTE: If kwargs has a ‘requests_params’ key the corresponding dict will be passed to the underlying requests.session.put method where it will be handled according to that API. THIS IS HOW TO PASS QUERY-ARGS!

class f5.bigip.resource.Collection(container)[source]¶

Bases: f5.bigip.resource.ResourceBase

Base class for objects that collect a list of Resources

The Collection Resource is responsible for providing a list of Python objects, where each object represents a unique URI, the URI contains the URI of the Collection at the front of its path, and the ‘kind’ of the URI-associated-JSON has been registered with the attribute registry of the Collection subclass.

Note

Any subclass of this base class must have s at the end of its name unless it ends in s then it must have _s.

get_collection(**kwargs)[source]¶

Get an iterator of Python Resource objects that represent URIs.

The returned objects are Pythonic Resource`s that map to the most recently `refreshed state of uris-resources published by the device. In order to instantiate the correct types, the concrete subclass must populate its registry with acceptable types, based on the kind field returned by the REST server.

Note

This method implies a single REST transaction with the Collection subclass URI.

Raises:	UnregisteredKind
Returns:	list of reference dicts and Python Resource objects

create(**kwargs)¶

Implement this by overriding it in a subclass of Resource

Raises:	InvalidResource

delete(**kwargs)¶

Implement this by overriding it in a subclass of Resource

Raises:	InvalidResource

raw¶

Display the attributes that the current object has and their values.

Returns:	A dictionary of attributes and their values

refresh(**kwargs)¶

Use this to make the device resource be represented by self.

This method makes an HTTP GET query against the device service. This method is run for its side-effects on self. If successful the instance attribute __dict__ is replaced with the dict representing the device state. To figure out what that state is, run a subsequest query of the object like this: As with all CURDLE methods use a “requests_params” dict to pass parameters to requests.session.HTTPMETHOD. See test_requests_params.py for an example. >>> resource_obj.refresh() >>> print(resource_obj.raw)

update(**kwargs)¶

Update the configuration of the resource on the BIG-IP®.

This method uses HTTP PUT alter the resource state on the BIG-IP®.

The attributes of the instance will be packaged as a dictionary. That dictionary will be updated with kwargs. It is then submitted as JSON to the device.

Various edge cases are handled: * read-only attributes that are unchangeable are removed

Parameters:	kwargs – keys and associated values to alter on the device

NOTE: If kwargs has a ‘requests_params’ key the corresponding dict will be passed to the underlying requests.session.put method where it will be handled according to that API. THIS IS HOW TO PASS QUERY-ARGS!

class f5.bigip.resource.Resource(container)[source]¶

Bases: f5.bigip.resource.ResourceBase

Base class to represent a Configurable Resource on the device.

Warning

Objects instantiated from subclasses of Resource do NOT contain a URI (self._meta_data[‘uri’]) at instantiation!

Resource objects provide the interface for the Creation of new services on the device. Once a new service has been created, (via self.create or self.load), the instance constructs its URI and stores it as self._meta_data['uri'].

It is an error to attempt to call create() or load() on an instance more than once. self._meta_data['uri'] MUST not be changed after creation or load.

Note

creation query args, and creation hash fragments are stored as separate _meta_data values.

By “Configurable” we mean that submitting JSON via the PUT method to the URI managed by subclasses of Resource, changes the state of the corresponding service on the device.

It also means that the URI supports DELETE.

create(**kwargs)[source]¶

Create the resource on the BIG-IP®.

Uses HTTP POST to the collection URI to create a resource associated with a new unique URI on the device.

Parameters:	kwargs – All the key-values needed to create the resource

NOTE: If kwargs has a ‘requests_params’ key the corresponding dict will be passed to the underlying requests.session.post method where it will be handled according to that API. THIS IS HOW TO PASS QUERY-ARGS! :returns: self - A python object that represents the object’s

configuration and state on the BIG-IP®.

load(**kwargs)[source]¶

Load an already configured service into this instance.

This method uses HTTP GET to obtain a resource from the BIG-IP®.

Parameters:	kwargs – typically contains “name” and “partition”

NOTE: If kwargs has a ‘requests_params’ key the corresponding dict will be passed to the underlying requests.session.get method where it will be handled according to that API. THIS IS HOW TO PASS QUERY-ARGS! :returns: a Resource Instance (with a populated _meta_data[‘uri’])

delete(**kwargs)[source]¶

Delete the resource on the BIG-IP®.

Uses HTTP DELETE to delete the resource on the BIG-IP®.

After this method is called, and status_code 200 response is received instance.__dict__ is replace with {'deleted': True}

Parameters:	kwargs – The only current use is to pass kwargs to the requests

API. If kwargs has a ‘requests_params’ key the corresponding dict will be passed to the underlying requests.session.delete method where it will be handled according to that API. THIS IS HOW TO PASS QUERY-ARGS!

exists(**kwargs)[source]¶

Check for the existence of the named object on the BIG-IP

Sends an HTTP GET to the URI of the named object and if it fails with a :exc:~requests.HTTPError` exception it checks the exception for status code of 404 and returns False in that case.

If the GET is successful it returns True.

For any other errors are raised as-is.

Parameters:	kwargs – Keyword arguments required to get objects

NOTE: If kwargs has a ‘requests_params’ key the corresponding dict will be passed to the underlying requests.session.get method where it will be handled according to that API. THIS IS HOW TO PASS QUERY-ARGS! :returns: bool – The objects exists on BIG-IP® or not. :raises: requests.HTTPError, Any HTTP error that was not status

code 404.

raw¶

Display the attributes that the current object has and their values.

Returns:	A dictionary of attributes and their values

refresh(**kwargs)¶

Use this to make the device resource be represented by self.

This method makes an HTTP GET query against the device service. This method is run for its side-effects on self. If successful the instance attribute __dict__ is replaced with the dict representing the device state. To figure out what that state is, run a subsequest query of the object like this: As with all CURDLE methods use a “requests_params” dict to pass parameters to requests.session.HTTPMETHOD. See test_requests_params.py for an example. >>> resource_obj.refresh() >>> print(resource_obj.raw)

update(**kwargs)¶

Update the configuration of the resource on the BIG-IP®.

This method uses HTTP PUT alter the resource state on the BIG-IP®.

The attributes of the instance will be packaged as a dictionary. That dictionary will be updated with kwargs. It is then submitted as JSON to the device.

Various edge cases are handled: * read-only attributes that are unchangeable are removed

Parameters:	kwargs – keys and associated values to alter on the device

NOTE: If kwargs has a ‘requests_params’ key the corresponding dict will be passed to the underlying requests.session.put method where it will be handled according to that API. THIS IS HOW TO PASS QUERY-ARGS!

mixins module¶

exception f5.bigip.mixins.InvalidCommand(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

Raise this if command argument supplied is invalid.

exception f5.bigip.mixins.UnsupportedMethod(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

Raise this if a method supplied is unsupported.

exception f5.bigip.mixins.LazyAttributesRequired(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

Raised when a object accesses a lazy attribute that is not listed

class f5.bigip.mixins.ToDictMixin[source]¶

Bases: object

Convert an object’s attributes to a dictionary

class f5.bigip.mixins.LazyAttributeMixin[source]¶

Bases: object

Allow attributes to be created lazily based on the allowed values

class f5.bigip.mixins.ExclusiveAttributesMixin[source]¶

Bases: object

Overrides __setattr__ to remove exclusive attrs from the object.

class f5.bigip.mixins.UnnamedResourceMixin[source]¶

Bases: object

This makes a resource object work if there is no name.

These objects do not support create or delete and are often found as Resources that are under an organizing collection. For example the mgmt/tm/sys/global-settings is one of these and has a kind of tm:sys:global-settings:global-settingsstate and the URI does not match the kind.

create(**kwargs)[source]¶

Create is not supported for unnamed resources

Raises:	UnsupportedOperation

delete(**kwargs)[source]¶

Delete is not supported for unnamed resources

Raises:	UnsupportedOperation

class f5.bigip.mixins.CommandExecutionMixin[source]¶

Bases: object

This adds command execution option on the objects.

These objects do not support create, delete, load, and require a separate method of execution. Commands do not have direct mapping to an HTTP method so usage of POST and an absolute URI is required.

create(**kwargs)[source]¶

Create is not supported for command execution

Raises:	UnsupportedOperation

delete(**kwargs)[source]¶

Delete is not supported for command execution

Raises:	UnsupportedOperation

load(**kwargs)[source]¶

Load is not supported for command execution

Raises:	UnsupportedOperation

Subpackages¶

Submodules¶

f5.common.constants module¶

f5.common.iapp_parser module¶

class f5.common.iapp_parser.IappParser(template_str)[source]¶

Bases: object

template_sections = [u'presentation', u'implementation', u'html-help', u'role-acl']¶

tcl_list_for_attr_re = '{(\\s*\\w+\\s*)+}'¶

tcl_list_for_section_re = '(\\s*\\w+\\s*)+'¶

section_map = {u'html-help': u'htmlHelp', u'role-acl': u'roleAcl'}¶

attr_map = {u'requires-modules': u'requiresModules'}¶

sections_not_required = [u'html-help', u'role-acl']¶

tcl_list_patterns = {u'requires-modules': '{(\\s*\\w+\\s*)+}', u'role-acl': '(\\s*\\w+\\s*)+'}¶

template_attrs = [u'description', u'partition', u'requires-modules']¶

parse_template()[source]¶

Parse the template string into a dict.

Find the (large) inner sections first, save them, and remove them from a modified string. Then find the template attributes in the modified string.

Returns:	dictionary of parsed template

exception f5.common.iapp_parser.EmptyTemplateException(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

args¶

message¶

exception f5.common.iapp_parser.CurlyBraceMismatchException(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

args¶

message¶

exception f5.common.iapp_parser.NonextantSectionException(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

args¶

message¶

exception f5.common.iapp_parser.NonextantTemplateNameException(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

args¶

message¶

exception f5.common.iapp_parser.MalformedTCLListException(*args, **kwargs)[source]¶

Bases: f5.sdk_exception.F5SDKError

args¶

message¶

f5.common.logger module¶

Module contents¶