ansible/docs/docsite/rst/dev_guide/developing_api.rst

.. _developing_api:

**********
Python API
**********

.. contents:: Topics

.. 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.

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.

If you would like to use Ansible programmatically from a language other than Python, trigger events asynchronously,
or have access control and logging demands, please see the `AWX project <https://github.com/ansible/awx/>`_.

.. note:: Because Ansible relies on forking processes, this API is not thread safe.

.. _python_api_example:

Python API example
==================

This example is a simple demonstration that shows how to minimally run a couple of tasks:

.. literalinclude:: ../../../../examples/scripts/uptime.py
   :language: python

.. note:: Ansible emits warnings and errors via the display object, which prints directly to stdout, stderr and the Ansible log.

The source code for the ``ansible``
command line tools (``lib/ansible/cli/``) is `available on GitHub <https://github.com/ansible/ansible/tree/devel/lib/ansible/cli>`_.

.. seealso::

   :ref:`developing_inventory`
       Developing dynamic inventory integrations
   :ref:`developing_modules_general`
       Getting started on developing a module
   :ref:`developing_plugins`
       How to develop plugins
   `Development Mailing List <https://groups.google.com/group/ansible-devel>`_
       Mailing list for development topics
   `irc.freenode.net <http://irc.freenode.net>`_
       #ansible IRC chat channel
Doc build warning/broken link clean-a-palooza (#37382) * Doc build warning/broken link clean-a-palooza, WIP commit 1. * Fixed broken anchor * Fixing additional broken links; converting from doc to ref. * Fix anchor 2018-03-14 20:44:21 +01:00			`.. _developing_api:`

rewrite of the developer guide, part 1 (#45179) * rewrite of the developer guide, part 1 2018-09-07 15:57:36 +02:00			`**********`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00			`Python API`
rewrite of the developer guide, part 1 (#45179) * rewrite of the developer guide, part 1 2018-09-07 15:57:36 +02:00			`**********`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
			`.. contents:: Topics`

Guide users to use ansible-runner (#71063) Update the docs to guide users to use `ansible-runner` instead of using Python API directly. In many use cases, executing Ansible playbooks are sufficient. In those use cases, `ansible-runner` is easier and much stable to use comparing with Python API, but there is no mention of it. 2020-08-03 17:15:37 +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.
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
Copy edits and tweaks 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.`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
rewrite of the developer guide, part 1 (#45179) * rewrite of the developer guide, part 1 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,`
Product-related updates. (#74454) 2021-04-27 23:19:57 +02:00			or have access control and logging demands, please see the `AWX project <https://github.com/ansible/awx/>`_.
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
Copy edits and tweaks 2018-03-02 23:51:48 +01:00			`.. note:: Because Ansible relies on forking processes, this API is not thread safe.`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
updated api example - added many more comments - removed very obsolete 1.x refs 2018-03-02 17:34:24 +01:00			`.. _python_api_example:`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
updated api example - added many more comments - removed very obsolete 1.x refs 2018-03-02 17:34:24 +01:00			`Python API example`
rewrite of the developer guide, part 1 (#45179) * rewrite of the developer guide, part 1 2018-09-07 15:57:36 +02:00			`==================`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
Refactor Python API examples and docs PR #70446: it's a follow-up for #70445. It includes a merge of `examples/scripts/uptime.py` and a similar code snippet from `docs/docsite/rst/dev_guide/developing_api.rst`. This patch also changes the docs RST file to include contents of the example file instead of holding a copy of a similar code. 2020-07-23 18:24:02 +02:00			`This example is a simple demonstration that shows how to minimally run a couple of tasks:`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
Refactor Python API examples and docs PR #70446: it's a follow-up for #70445. It includes a merge of `examples/scripts/uptime.py` and a similar code snippet from `docs/docsite/rst/dev_guide/developing_api.rst`. This patch also changes the docs RST file to include contents of the example file instead of holding a copy of a similar code. 2020-07-23 18:24:02 +02:00			`.. literalinclude:: ../../../../examples/scripts/uptime.py`
			`:language: python`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
updated api example - added many more comments - removed very obsolete 1.x refs 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.`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
Copy edits and tweaks 2018-03-02 23:51:48 +01:00			The source code for the ``ansible``
Consistent typesetting of "GitHub" (#50929) 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>`_.
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00
			`.. seealso::`

removes last :doc: links in the dev guide (#58417) 2019-06-26 20:59:33 +02:00			:ref:`developing_inventory`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00			`Developing dynamic inventory integrations`
removes last :doc: links in the dev guide (#58417) 2019-06-26 20:59:33 +02:00			:ref:`developing_modules_general`
			`Getting started on developing a module`
			:ref:`developing_plugins`
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00			`How to develop plugins`
Prefer https:// links in the docs site All the changed urls are availible by way of https://. Most of them already redirect. 2018-07-21 15:48:47 +02:00			`Development Mailing List <https://groups.google.com/group/ansible-devel>`_
Dev guide reorg continues (#17732) 2016-09-23 22:48:37 +02:00			`Mailing list for development topics`
			`irc.freenode.net <http://irc.freenode.net>`_
			`#ansible IRC chat channel`