USAGE.rst

Usage

To develop on towerlib:

# The following commands require pipenv as a dependency

# To lint the project
_CI/scripts/lint.py

# To execute the testing
_CI/scripts/test.py

# To create a graph of the package and dependency tree
_CI/scripts/graph.py

# To build a package of the project under the directory "dist/"
_CI/scripts/build.py

# To see the package version
_CI/scipts/tag.py

# To bump semantic versioning [--major|--minor|--patch]
_CI/scipts/tag.py --major|--minor|--patch

# To upload the project to a pypi repo if user and password are properly provided
_CI/scripts/upload.py

# To build the documentation of the project
_CI/scripts/document.py

To use towerlib in a project:

from towerlib import Tower

# using http (pick one)
tower = Tower('ansible.domain.com', 'username', 'password')

# using https with a valid cert (pick one)
tower = Tower('ansible.domain.com', 'username', 'password', secure=True)

# using https with an invalid cert (pick one)
tower = Tower('ansible.domain.com', 'username', 'password', secure=True, ssl_verify=False)

# using https with a custom certificate authority (pick one)
tower = Tower('ansible.domain.com', 'username', 'password', secure=True, ssl_verify='/etc/ssl/certs/example.com.ca.crt')

# using https with an OAUTH2 token (pick one)
tower = Tower('ansible.domain.com', None, None, secure=True, token="token-data-here")

# access hosts
for host in tower.hosts:
    print(host.name)

# access groups
for group in tower.groups:
    print(group.name)

# access inventories
for inventory in tower.inventories:
    print(inventory.name)

# access organizations
for organization in tower.organizations:
    print(organization.name)

# access users
for user in tower.users:
    print(user.username)

# access projects
for project in tower.projects:
    print(project.name)

# access teams
for team in tower.teams:
    print(team.name)

# access jobs
for job in tower.jobs:
    print(job.name)

# all of the above entities also support a dictionary of filters which are provided
# to the api, reducing query time. For filterable terms, see
# https://docs.ansible.com/ansible-tower/latest/html/towerapi/filtering.html

# failed jobs
for job in tower.jobs.filter({"status":"failed"}):
    print(job.name)
# successful jobs
for job in tower.jobs.filter({"status": "successful"}):
    print(job.name)


# all the above entities support creation and deletion either from the core tower object
# or from their respective parent object.
# eg: create a host
tower.create_host_in_inventory('inventory_name','host_name', 'host description', 'variable_json')

# or
inventory = tower.get_inventory_by_name('inventory_name')
inventory.create_host('host_name', 'host description', 'variable_json')