2018-03-14 20:44:21 +01:00
.. _developing_api:
2018-09-07 15:57:36 +02:00
***** *****
2016-09-23 22:48:37 +02:00
Python API
2018-09-07 15:57:36 +02:00
***** *****
2016-09-23 22:48:37 +02:00
.. contents :: Topics
2020-08-07 23:04:19 +02:00
.. note :: This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible. If you want to use Python API only for executing playbooks or modules, consider `ansible-runner <https://ansible-runner.readthedocs.io/en/latest/> `_ first.
2016-09-23 22:48:37 +02:00
2018-03-02 23:51:48 +01:00
There are several ways to use Ansible from an API perspective. You can use
the Ansible Python API to control nodes, you can extend Ansible to respond to various Python events, you can
write plugins, and you can plug in inventory data from external data sources. This document
gives a basic overview and examples of the Ansible execution and playbook API.
2016-09-23 22:48:37 +02:00
2018-09-07 15:57:36 +02:00
If you would like to use Ansible programmatically from a language other than Python, trigger events asynchronously,
2018-04-22 09:15:16 +02:00
or have access control and logging demands, please see the `Ansible Tower documentation <https://docs.ansible.com/ansible-tower/> `_ .
2016-09-23 22:48:37 +02:00
2018-03-02 23:51:48 +01:00
.. note :: Because Ansible relies on forking processes, this API is not thread safe.
2016-09-23 22:48:37 +02:00
2018-03-02 17:34:24 +01:00
.. _python_api_example:
2016-09-23 22:48:37 +02:00
2018-03-02 17:34:24 +01:00
Python API example
2018-09-07 15:57:36 +02:00
==================
2016-09-23 22:48:37 +02:00
2020-07-29 22:51:21 +02:00
This example is a simple demonstration that shows how to minimally run a couple of tasks:
2016-09-23 22:48:37 +02:00
2020-07-29 22:51:21 +02:00
.. literalinclude :: ../../../../examples/scripts/uptime.py
:language: python
2016-09-23 22:48:37 +02:00
2018-03-02 17:34:24 +01:00
.. note :: Ansible emits warnings and errors via the display object, which prints directly to stdout, stderr and the Ansible log.
2016-09-23 22:48:37 +02:00
2018-03-02 23:51:48 +01:00
The source code for the `` ansible ``
2019-01-15 14:53:04 +01:00
command line tools (`` lib/ansible/cli/ `` ) is `available on GitHub <https://github.com/ansible/ansible/tree/devel/lib/ansible/cli> `_ .
2016-09-23 22:48:37 +02:00
.. seealso ::
2019-06-26 20:59:33 +02:00
:ref: `developing_inventory`
2016-09-23 22:48:37 +02:00
Developing dynamic inventory integrations
2019-06-26 20:59:33 +02:00
:ref: `developing_modules_general`
Getting started on developing a module
:ref: `developing_plugins`
2016-09-23 22:48:37 +02:00
How to develop plugins
2018-07-21 15:48:47 +02:00
`Development Mailing List <https://groups.google.com/group/ansible-devel> `_
2016-09-23 22:48:37 +02:00
Mailing list for development topics
`irc.freenode.net <http://irc.freenode.net> `_
#ansible IRC chat channel
