toaccess
toaccess
This module provides a set of functions meant to provide ease-of-use functionality for interacting
with the Traffic Ops API. It provides scripts named tomethod
where method is the name of
an HTTP method (in lowercase). Collectively they are referred to as toaccess Implemented
methods thus far are:
delete
head
get
options
patch
post
put
Arguments and Flags
- PATH
This is the request path. By default, whatever is passed is considered to be relative to
/api/api-version/
whereapi-version
is--api-version
. This behavior can be disabled by using--raw-path
.
- DATA
An optional positional argument that is a data payload to pass to the Traffic Ops server in the request body. If this is the absolute or relative path to a file, the contents of the file will instead be read and used as the request payload.
- -h, --help
Print usage information and exit
- -a API_VERSION, --api-version API_VERSION
Specifies the version of the Traffic Ops API that will be used for the request. Has no effect if
--raw-path
is used. (Default: 4.1)
- -f, --full
Output the full HTTP exchange including request method line, request headers, request body (if any), response status line, and response headers (as well as the response body, if any). This is equivalent to using
--request-headers
,--request-payload
, and--response-headers
at the same time, and those options will have no effect if given. (Default: false)
- -k, --insecure
Do not verify SSL certificates - typically useful for making requests to development or testing servers as they frequently have self-signed certificates. (Default: false)
- -p, --pretty
Pretty-print any payloads that are output as formatted JSON. Has no effect on plaintext payloads. Uses tab characters for indentation. (Default: false)
- -r, --raw-path
Request exactly
PATH
; do not preface the request path with/api/api_version
. This effectively means that--api-version
will have no effect. (Default: false)
- -v, --version
Print version information and exit.
- --request-headers
Output the request method line and any and all request headers. (Default: false)
- --request-payload
Output the request body if any was sent. Will attempt to pretty-print the body as JSON if
--pretty
is used. (Default: false)
- --response-headers
Output the response status line and any and all response headers. (Default: false)
- --to-url URL
The FQDN and optionally the port and scheme of the Traffic Ops server. This will override
TO_URL
. The format is the same as forTO_URL
. (Default: uses the value ofTO_URL
)
- --to-password PASSWORD
The password to use when authenticating to Traffic Ops. Overrides
TO_PASSWORD
. (Default: uses the value ofTO_PASSWORD
)
Environment Variables
If defined, toaccess scripts will use the TO_URL
, TO_USER
, and
:envvar`TO_PASSWORD` environment variables to define their connection to and authentication with the
Traffic Ops server. Typically, setting these is easier than using the long options --to-url
,
--to-user
, and --to-password
on every invocation.
Exit Codes
The exit code of a toaccess script can sometimes be used by the caller to determine what the result of calling the script was without needing to parse the output. The exit codes used are:
- 0
The command executed successfully, and the result is on STDOUT.
- 1
Typically this exit code means that an error was encountered when parsing positional command line arguments. However, this is also the exit code used by most Python interpreters to signal an unhandled exception.
- 2
Signifies a runtime error that caused the request to fail - this is not generally indicative of an HTTP client or server error, but rather an underlying issue connecting to or authenticating with Traffic Ops. This is distinct from an exit code of
32
in that the format of the arguments was correct, but there was some problem with the value. For example, passinghttps://test:
to--to-url
will cause an exit code of2
, not32
.- 4
An HTTP client error occurred. The HTTP stack will be printed to stdout as indicated by other options - meaning by default it will only print the response payload if one was given, but will respect options like e.g.
--request-payload
as well as-p
/--pretty
.- 5
An HTTP server error occurred. The HTTP stack will be printed to stdout as indicated by other options - meaning by default it will only print the response payload if one was given, but will respect options like e.g.
--request-payload
as well as-p
/--pretty
.- 32
This is the error code emitted by Python’s
argparse
module when the passed arguments could not be parsed successfully.
Note
The way exit codes 4
and 5
are implemented is by returning the status code of the
HTTP request divided by 100 whenever it is at least 400. This means that if the Traffic Ops
server ever started returning e.g. 700 status codes, the exit code of the script would be 7.
Module Reference
- to_access.delete()
Entry point for todelete
- Returns:
The program’s exit code
- to_access.get()
Entry point for toget
- Returns:
The program’s exit code
- to_access.head()
Entry point for tohead
- Returns:
The program’s exit code
- to_access.options()
Entry point for tooptions
- Returns:
The program’s exit code
- to_access.output(r, pretty, request_header, response_header, request_payload, indent='\t')
Prints the passed response object in a format consistent with the other parameters.
- Parameters:
r – The
requests
response object being printedpretty – If
True
, attempt to pretty-print payloads as JSONrequest_header – If
True
, print request line and request headersresponse_header – If
True
, print response line and response headersrequest_payload – If
True
, print the request payloadindent – An optional number of spaces for pretty-printing indentation (default is the tab character)
- to_access.parse_arguments(program)
A common-use function that parses the command line arguments.
- Parameters:
program – The name of the program being run - used for usage informational output
- Returns:
The Traffic Ops HTTP session object, the requested path, any data to be sent, an output format specification, whether or not the path is raw, and whether or not output should be prettified
- to_access.patch()
Entry point for topatch
- Returns:
The program’s exit code
- to_access.post()
Entry point for topost
- Returns:
The program’s exit code
- to_access.put()
Entry point for toput
- Returns:
The program’s exit code
- to_access.request(method)
All of the scripts wind up calling this function to handle their common functionality.
- Parameters:
method – The name of the request method to use (case-insensitive)
- Returns:
The program’s exit code