Developer Interface¶

class apypie.Api(**kwargs)¶

Apipie API bindings

Parameters:

uri – base URL of the server
username – username to access the API
password – password to access the API
client_cert – client cert to access the API
client_key – client key to access the API
kerberos – use Kerberos/GSSAPI for authentication with the API. Requires either requests-gssapi or requests-kerberos.
oauth1_consumer_key – OAuth1 consumer key. Requires requests-oauthlib.
oauth1_consumer_secret – OAuth1 consumer secret. Requires requests-oauthlib.
api_version – version of the API. Defaults to 1
language – prefered locale for the API description
apidoc_cache_base_dir – base directory for building apidoc_cache_dir. Defaults to ~/.cache/apipie_bindings.
apidoc_cache_dir – where to cache the JSON description of the API. Defaults to apidoc_cache_base_dir/<URI>.
apidoc_cache_name – name of the cache file. If there is cache in the apidoc_cache_dir, it is used. Defaults to default.
verify_ssl – should the SSL certificate be verified. Defaults to True.
session – a requests.Session compatible object. Defaults to requests.Session().

Usage:

>>> import apypie
>>> api = apypie.Api(uri='https://api.example.com', username='admin', password='changeme')

property apidoc: dict¶

The full apidoc.

The apidoc will be fetched from the server, if that didn’t happen yet.

Returns:: The apidoc.

property apidoc_cache_file: str¶: Full local path to the cached apidoc.

property cache_extension: str¶

File extension for the local cache file.

Will include the language if set.

Call an action in the API.

It finds most fitting route based on given parameters with other attributes necessary to do an API call.

Parameters:

resource_name – name of the resource
action_name – action_name name of the action
params – Dict of parameters to be sent in the request
headers – Dict of headers to be sent in the request
options – Dict of options to influence the how the call is processed * skip_validation (Bool) false - skip validation of parameters
data – Binary data to be sent in the request
files – Binary files to be sent in the request

Returns:

dict object

Return type:

dict

Usage:

>>> api.call('users', 'show', {'id': 1})

clean_cache() → None¶: Remove any locally cached apidocs.

Execute an HTTP request.

Parameters:

params – Dict of parameters to be sent in the request
headers – Dict of headers to be sent in the request
data – Binary data to be sent in the request
files – Binary files to be sent in the request

Returns:

dict object

Return type:

dict

resource(name: str) → Resource¶

Get a resource.

Parameters:: name – the name of the resource to load
Returns:: Resource object
Return type:: apypie.Resource

Usage:

>>> api.resource('users')

property resources: Iterable¶

List of available resources.

Usage:

>>> api.resources
['comments', 'users']

validate_cache(cache_name: str | None = None) → None¶

Ensure the cached apidoc matches the one presented by the server.

Parameters:: cache_name – The name of the apidoc on the server.

class apypie.ForemanApi(**kwargs)¶

apypie.Api with default settings and helper functions for Foreman

Usage:

>>> import apypie
>>> api = apypie.ForemanApi(uri='https://foreman.example.com', username='admin', password='changeme')

property apidoc: dict¶

The full apidoc.

The apidoc will be fetched from the server, if that didn’t happen yet.

Returns:: The apidoc.

property apidoc_cache_file: str¶: Full local path to the cached apidoc.

property cache_extension: str¶

File extension for the local cache file.

Will include the language if set.

Call an action in the API.

It finds most fitting route based on given parameters with other attributes necessary to do an API call.

Parameters:

resource_name – name of the resource
action_name – action_name name of the action
params – Dict of parameters to be sent in the request
headers – Dict of headers to be sent in the request
options – Dict of options to influence the how the call is processed * skip_validation (Bool) false - skip validation of parameters
data – Binary data to be sent in the request
files – Binary files to be sent in the request

Returns:

dict object

Return type:

dict

Usage:

>>> api.call('users', 'show', {'id': 1})

clean_cache() → None¶: Remove any locally cached apidocs.

create(resource: str, desired_entity: dict, params: dict | None = None) → dict | None¶

Create entity with given properties

Parameters:

resource – Plural name of the api resource to manipulate
desired_entity – Desired properties of the entity
params – Lookup parameters (i.e. parent_id for nested entities)

Returns:

The new current state of the entity

delete(resource: str, current_entity: dict, params: dict | None = None) → None¶

Delete a given entity

Parameters:

resource – Plural name of the api resource to manipulate
current_entity – Current properties of the entity
params – Lookup parameters (i.e. parent_id for nested entities)

Returns:

The new current state of the entity

Execute an HTTP request.

Parameters:

params – Dict of parameters to be sent in the request
headers – Dict of headers to be sent in the request
data – Binary data to be sent in the request
files – Binary files to be sent in the request

Returns:

dict object

Return type:

dict

list(resource: str, search: str | None = None, params: dict | None = None) → list¶

Execute the index action on an resource.

Parameters:

resource – Plural name of the api resource to show
search – Search string as accepted by the API to limit the results
params – Lookup parameters (i.e. parent_id for nested entities)

Returns:

List of results

resource(name: str) → Resource¶

Get a resource.

Parameters:: name – the name of the resource to load
Returns:: Resource object
Return type:: apypie.Resource

Usage:

>>> api.resource('users')

resource_action(resource: str, action: str, params: dict, options=None, data=None, files=None, ignore_task_errors: bool = False) → dict | None¶

Perform a generic action on a resource

Will wait for tasks if the action returns one

property resources: Iterable¶

List of available resources.

Usage:

>>> api.resources
['comments', 'users']

show(resource: str, resource_id: int, params: dict | None = None) → dict | None¶

Execute the show action on an entity.

Parameters:

resource – Plural name of the api resource to show
resource_id – The ID of the entity to show
params – Lookup parameters (i.e. parent_id for nested entities)

Returns:

The entity

update(resource: str, desired_entity: dict, params: dict | None = None) → dict | None¶

Update entity with given properties

Parameters:

resource – Plural name of the api resource to manipulate
desired_entity – Desired properties of the entity
params – Lookup parameters (i.e. parent_id for nested entities)

Returns:

The new current state of the entity

validate_cache(cache_name: str | None = None) → None¶

Ensure the cached apidoc matches the one presented by the server.

Parameters:: cache_name – The name of the apidoc on the server.

validate_payload(resource: str, action: str, payload: dict) → Tuple[dict, Set[str]]¶

Check whether the payload only contains supported keys.

Parameters:

resource – Plural name of the api resource to check
action – Name of the action to check payload against
payload – API paylod to be checked

Returns:

The payload as it can be submitted to the API and set of unssuported parameters

wait_for_task(task: dict, ignore_errors: bool = False) → dict¶

Wait for a foreman-tasks task, polling it every self.task_poll seconds.

Will raise a ForemanApiException when task has not finished in self.task_timeout seconds.

class apypie.Resource(api: Api, name: str)¶

Apipie Resource

action(name: str) → Action¶

Get an Action for this resource.

Parameters:: name – The name of the action.

property actions: List¶

Actions available for this resource.

Returns:: The actions.

Call the API to execute an action for this resource.

Parameters:

action – The action to call.
params – The params that should be passed to the API.
headers – Additional headers to be passed to the API.
options – Options
data – Binary data to be submitted to the API.
files – Files to be submitted to the API.

Returns:

The API response.

has_action(name: str) → bool¶

Check whether the resource has a given action.

Parameters:: name – The name of the action.

class apypie.Action(name: str, resource: str, api: Api)¶

Apipie Action

property apidoc: dict¶

The apidoc of this action.

Returns:: The apidoc.

Call the API to execute the action.

Parameters:

params – The params that should be passed to the API.
headers – Additional headers to be passed to the API.
options – Options
data – Binary data to be submitted to the API.
files – Files to be submitted to the API.

Returns:

The API response.

property examples: List[Example]¶

The examples of this action.

Returns:: The examples.

static filter_empty_params(params: dict | None = None) → dict¶

Filter out any params that have no value.

Parameters:: params – The params to filter.
Returns:: The filtered params.

find_route(params: dict | None = None) → Route¶

Find the best matching route for a given set of params.

Parameters:: params – Params that should be submitted to the API.
Returns:: The best route.

property params: List[Param]¶

The params accepted by this action.

Returns:: The params.

prepare_params(input_dict: dict) → dict¶

Transform a dict with data into one that can be accepted as params for calling the action.

This will ignore any keys that are not accepted as params when calling the action. It also allows generating nested params without forcing the user to care about them.

Parameters:: input_dict – a dict with data that should be used to fill in the params
Returns:: dict object
Return type:: dict

Usage:

>>> action.prepare_params({'id': 1})
{'user': {'id': 1}}

property routes: List[Route]¶

The routes this action can be invoked by.

Returns:: The routes

validate(values: dict, data: Any | None = None, files: dict | None = None) → None¶

Validate a given set of parameter values against the required set of parameters.

Parameters:

values – The values to validate.
data – Additional binary data to validate.
files – Additional files to validate.

class apypie.Param(**kwargs)¶: Apipie Param

class apypie.Route(path: str, method: str, description: str = '')¶

Apipie Route

property params_in_path: List¶

Params that can be passed in the path (URL) of the route.

Returns:: The params.

path_with_params(params: dict | None = None) → str¶

Fill in the params into the path.

Returns:: The path with params.

class apypie.Example(http_method: str, path: str, args: str, status: str, response: str)¶

Apipie Example

classmethod parse(example)¶

Parse an example from an apidoc string

Returns:: The parsed Example

Developer Interface¶

apypie

Navigation

Related Topics