Welcome to Python Foreman’s documentation!¶

Client module documentation¶

This module provides access to the API of a foreman server

class foreman.client.Foreman(url, auth=None, version=None, api_version=None, use_cache=True, strict_cache=True, timeout=60, timeout_post=600, timeout_delete=600, timeout_put=None, verify=False)[source]¶

Main client class. It’s methods will be autogenerated, check the API docs for your foreman version here.

do_delete(url, kwargs)[source]¶

Parameters:	url – relative url to resource kwargs – parameters for the api call

do_get(url, kwargs)[source]¶

Parameters:	url – relative url to resource kwargs – parameters for the api call

do_post(url, kwargs)[source]¶

Parameters:	url – relative url to resource kwargs – parameters for the api call

do_put(url, kwargs)[source]¶

Parameters:	url – relative url to resource kwargs – parameters for the api call

get_foreman_version()[source]¶: Even if we have an api method that returns the foreman version, we need the version first to know its path, so instead of that we get the main page and extract the version from the footer.

get_timeout(method=None)[source]¶

Get timeout for given request method

Parameters:	method – Request method (eg. GET, POST, ..). If None, return default timeout.

set_timeout(timeout, method='DEFAULT')[source]¶

Set the timeout for any connection, the timeout is the requests module timeout (for conneciton inactivity rather than request total time)

Parameters:	timeout – Timeout in seconds for the connection inactivity method – Request method (eg. GET, POST, ..). By default, set default timeout.

unset_timeout(method)[source]¶

Ensure timeout for given method is not set.

Parameters:	method – Request method (eg. GET, POST, ..)

exception foreman.client.ForemanException(res, msg)[source]¶

exception foreman.client.ForemanVersionException[source]¶

class foreman.client.MetaForeman[source]¶

static convert_plugin_def(http_method, funcs)[source]¶

This function parses one of the elements of the definitions dict for a plugin and extracts the relevant information

Parameters:	http_method – HTTP method that uses (GET, POST, DELETE, ...) funcs – functions related to that HTTP method

class foreman.client.MethodAPIDescription(resource, method, api)[source]¶

classmethod create_param_doc(param, prefix=None)[source]¶: Generate documentation for single parameter of function :param param: dict contains info about parameter :param sub: prefix string for recursive purposes

exclude_html_reg = <_sre.SRE_Pattern object>¶

generate_func(as_global=False)[source]¶

Generate function for specific method and using specific api

Parameters:	as_global – if set, will use the global function name, instead of the class method (usually {resource}_{class_method}) when defining the function

get_global_method_name()[source]¶

parse_resource_from_url(url)[source]¶

Returns the appropriate resource name for the given URL.

Parameters:	url – API URL stub, like: ‘/api/hosts’
Returns:	Resource name, like ‘hosts’, or None if not found

resource_pattern = <_sre.SRE_Pattern object>¶

exception foreman.client.ObjectNotFound(res, msg)[source]¶

class foreman.client.Resource(foreman)[source]¶: Provides entry point for specific resource.

class foreman.client.ResourceMeta[source]¶: This type composes methods for resource class

exception foreman.client.Unacceptable(res, msg)[source]¶

foreman.client.parse_resource_definition(resource_name, resource_dct)[source]¶

Returns all the info extracted from a resource section of the apipie json

Parameters:	resource_name – Name of the resource that is defined by the section resrouce_dict – Dictionary as generated by apipie of the resource definition

foreman.client.parse_version(version_string)[source]¶

Parameters:	version_string – Version string to parse, like ‘1.2.3’

Passing to int as many of the elements as possible to support comparing ints of different number of chars (2<10 but ‘2’>‘10’). So we just accept that any element with chars will be considered lesser to any int element.

foreman.client.res_to_str(res)[source]¶

Parameters:	res – `requests.Response` object

Parse the given request and generate an informative string from it

foreman.client.set_loglevel(level)[source]¶

Sets the loglevel for the python-foreman module.

Parameters:	loglevel – a loglevel constant from the logging module.

foreman.client.try_int(what)[source]¶

Tutorial¶

Definitions files¶

The Python Foreman can get the methods and it’s definitions from two places the definitions directory or the foreman instance.

This definitions directory contains some apipie json definitions retrieved from different foreman versions and api versions, by default it will try to match the foreman version with the fittest of those files.

It can also get it’s definitions from the live Foreman instance, to do that, you have to make sure that the urls:

FOREMAN_URL/apidoc/v2.json
FOREMAN_URL/apidoc/v1.json

are available, usually that means that you’ll have to set the config.use_cache parameter for the apipie gem to false (normally found under FOREMAN_HOME/config/initializers/apipie.rb)

Basic Tutorial¶

Connect¶

To connect to a foreman server just instantiate a foreman.client.Foreman object with the server’s url and authentication aprameters, like this:

>>> from getpass import getpass
>>> from foreman.client import Foreman
>>> f = Foreman('http://myforeman.server:3000', ('myuser', getpass()))

The available methods are separated in two ways, by resource (apiv2) and by method ($type_$resource_$method).

Take into account that all those methods are autogenerated and they might vary for different versions of Foreman.

index¶

Those are the main methods to get info for groups of objects, for example, to get a sumary of all the hosts you could do:

>>> f.index_hosts()
>>> f.hosts.index()

Take into account that it accepts some parameters to handle the paging and the ammount of elements to get.

show¶

This methods give you all the information for a specific object, for example:

>>> f.show_hosts(id=1)
>>> f.hosts.show(id='myuber.host.com')

Will show all the info for the host with id 1.

create¶

This methods create a new object into foreman. An example:

>>> f.create_hosts(host={'name': 'mynewhost', 'ip': '192.168.1.1', 'mac': '00:00:00:00:00:00'})
>>> f.hosts.create(host={'name': 'mynewhost', 'ip': '192.168.1.1', 'mac': '00:00:00:00:00:00'})

To see the exact parameters look at the `foreman API docs<http://theforeman.org/api.html>`_.

update¶

This methods update the info for the given object, usually called with an id and a hash representating the object.