Project¶
Description¶
This resource is used for managing and executing projects via Tower. Note project updates are triggered
via update
method.
Fields Table¶
name | type | help_text | read_only | unique | filterable | required |
---|---|---|---|---|---|---|
name | String | The name field. | False | True | True | True |
description | String | The description field. | False | False | True | False |
organization | Resource organization | The organization field. | False | False | True | False |
scm_type | mapped_choice | The scm_type field. | False | False | True | True |
scm_url | String | The scm_url field. | False | False | True | False |
local_path | String | For manual projects, the server playbook directory name. | False | False | True | False |
scm_branch | String | The scm_branch field. | False | False | True | False |
scm_credential | Resource credential | The scm_credential field. | False | False | True | False |
scm_clean | bool | The scm_clean field. | False | False | True | False |
scm_delete_on_update | bool | The scm_delete_on_update field. | False | False | True | False |
scm_update_on_launch | bool | The scm_update_on_launch field. | False | False | True | False |
scm_update_cache_timeout | int | The scm_update_cache_timeout field. | False | False | True | False |
job_timeout | int | The timeout field (in seconds). | False | False | True | False |
API Specification¶
-
class
tower_cli.resources.project.
Resource
(*args, **kwargs)[source]¶ A resource for projects.
-
copy
(pk=None, new_name=None, **kwargs)[source]¶ Copy an object.
Parameters: - pk (int) – Primary key of the resource object to be copied
- new_name – The new name to give the resource if deep copying via the API
- **kwargs – Keyword arguments of fields whose given value will override the original value.
Returns: loaded JSON of the copied new resource object.
Return type:
-
create
(organization=None, monitor=False, wait=False, timeout=None, fail_on_found=False, force_on_exists=False, **kwargs)[source]¶ Create a project and, if related flags are set, monitor or wait the triggered initial project update.
Parameters: - monitor (bool) – Flag that if set, immediately calls
monitor
on the newly triggered project update rather than exiting with a success. - wait (bool) – Flag that if set, monitor the status of the triggered project update, but do not print while it is in progress.
- timeout (bool) – If provided with
monitor
flag set, this attempt will time out after the given number of seconds. - fail_on_found (bool) – Flag that if set, the operation fails if an object matching the unique criteria already exists.
- force_on_exists (bool) – Flag that if set, then if a match is found on unique fields, other fields will be updated to the provided values.; If unset, a match causes the request to be a no-op.
- **kwargs – Keyword arguments which, all together, will be used as POST body to create the resource object.
Returns: A dictionary combining the JSON output of the created resource, as well as two extra fields: “changed”, a flag indicating if the resource is created successfully; “id”, an integer which is the primary key of the created object.
Return type: - monitor (bool) – Flag that if set, immediately calls
-
delete
(pk=None, fail_on_missing=False, **kwargs)¶ Remove the given object.
Parameters: Returns: dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type:
-
get
(pk=None, **kwargs)¶ Retrieve one and exactly one object.
Parameters: - pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object
if
pk
is provided (notNone
). - **kwargs – Keyword arguments used to look up resource object to retrieve if
pk
is not provided.
Returns: loaded JSON of the retrieved resource object.
Return type: - pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object
if
-
list
(all_pages=False, **kwargs)¶ Retrieve a list of objects.
Parameters: - all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
- page (int) – The page to show. Ignored if all_pages is set.
- query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
- **kwargs – Keyword arguments list of available fields used for searching resource objects.
Returns: A JSON object containing details of all resource objects returned by Tower backend.
Return type:
-
modify
(pk=None, create_on_missing=False, **kwargs)[source]¶ Modify an already existing project.
Parameters: - pk (int) – Primary key of the resource to be modified.
- create_on_missing (bool) – Flag that if set, a new object is created if
pk
is not set and objects matching the appropriate unique criteria is not found. - **kwargs – Keyword arguments which, all together, will be used as PATCH body to modify the
resource object. if
pk
is not set, key-value pairs of**kwargs
which are also in resource’s identity will be used to lookup existing reosource.
Returns: A dictionary combining the JSON output of the modified resource, as well as two extra fields: “changed”, a flag indicating if the resource is successfully updated; “id”, an integer which is the primary key of the updated object.
Return type:
-
monitor
(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<open file '<stdout>', mode 'w'>, **kwargs)¶ Stream the standard output from a job run to stdout.
Parameters: - pk (int) – Primary key of the job resource object to be monitored.
- parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be
monitored if
pk
is not set. - timeout (float) – Number in seconds after which this method will time out.
- interval (float) – Polling interval to refresh content from Tower.
- outfile (file) – Alternative file than stdout to write job stdout to.
- **kwargs – Keyword arguments used to look up job resource object to monitor if
pk
is not provided.
Returns: A dictionary combining the JSON output of the finished job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is finished as expected; “id”, an integer which is the primary key of the job resource object being monitored.
Return type: Raises: - tower_cli.exceptions.Timeout – When monitor time reaches time out.
- tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.
-
status
(pk=None, detail=False, **kwargs)[source]¶ Print the status of the most recent update.
Parameters: Returns: full loaded JSON of the specified unified job if
detail
flag is on; trimed JSON containing only “elapsed”, “failed” and “status” fields of the unified job ifdetail
flag is off.Return type:
-
stdout
(pk, start_line=None, end_line=None, outfile=<open file '<stdout>', mode 'w'>, **kwargs)¶ Print out the standard out of a unified job to the command line or output file. For Projects, print the standard out of most recent update. For Inventory Sources, print standard out of most recent sync. For Jobs, print the job’s standard out. For Workflow Jobs, print a status table of its jobs.
Parameters: - pk (int) – Primary key of the job resource object to be monitored.
- start_line – Line at which to start printing job output
- end_line – Line at which to end printing job output
- outfile (file) – Alternative file than stdout to write job stdout to.
- **kwargs – Keyword arguments used to look up job resource object to monitor if
pk
is not provided.
Returns: A dictionary containing changed=False
Return type:
-
update
(pk=None, create_on_missing=False, monitor=False, wait=False, timeout=None, name=None, organization=None)[source]¶ Update the given project.
Parameters: - pk (int) – Primary key of the project to be updated.
- monitor (bool) – Flag that if set, immediately calls
monitor
on the newly launched project update rather than exiting with a success. - wait (bool) – Flag that if set, monitor the status of the project update, but do not print while it is in progress.
- timeout (int) – If provided with
monitor
flag set, this attempt will time out after the given number of seconds. - name (str) – Name of the project to be updated if
pk
is not set. - organization (str) – Primary key or name of the organization the project to be updated belonging to if
pk
is not set.
Returns: Result of subsequent
monitor
call ifmonitor
flag is on; Result of subsequentwait
call ifwait
flag is on; dictionary of “status” if none of the two flags are on.Return type: Raises: tower_cli.exceptions.CannotStartJob – When the project cannot be updated.
-
wait
(pk, parent_pk=None, min_interval=1, max_interval=30, timeout=None, outfile=<open file '<stdout>', mode 'w'>, exit_on=['successful'], **kwargs)¶ Wait for a job resource object to enter certain status.
Parameters: - pk (int) – Primary key of the job resource object to wait.
- parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be
waited if
pk
is not set. - timeout (float) – Number in seconds after which this method will time out.
- min_interval (float) – Minimum polling interval to request an update from Tower.
- max_interval (float) – Maximum polling interval to request an update from Tower.
- outfile (file) – Alternative file than stdout to write job status updates on.
- exit_on (array) – Job resource object statuses to wait on.
- **kwargs – Keyword arguments used to look up job resource object to wait if
pk
is not provided.
Returns: A dictionary combining the JSON output of the status-changed job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is status-changed as expected; “id”, an integer which is the primary key of the job resource object being status-changed.
Return type: Raises: - tower_cli.exceptions.Timeout – When wait time reaches time out.
- tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.
-