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/ where api-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: 2.0)

-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 for TO_URL. (Default: uses the value of TO_URL)

--to-password PASSWORD

The password to use when authenticating to Traffic Ops. Overrides TO_PASSWORD. (Default: uses the value of TO_PASSWORD)

--to-user USERNAME

The username to use when connecting to Traffic Ops. Overrides TO_USER. (Default: uses the value of TO_USER)

Environment Variables

If defined, toaccess scripts will use these 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.

TO_PASSWORD

Will be used to authenticate the user defined by either --to-user or TO_USER.

TO_URL

The FQDN of the Traffic Ops server to which the script will connect. The format of this should be [http or https://]hostname[:port]. Note that this may optionally start with http:// or https:// (case insensitive), but typically this is unnecessary. Also notice that the port number may be specified, though again this isn’t usually required. All toaccess scripts will assume that port 443 should be used unless otherwise specified. They will further assume that the protocol is HTTPS unless TO_URL (or --to-url) starts with http://, in which case the default port will also be set to 80 unless otherwise specified in the URL.

TO_USER

The name of the user as whom to connect to the Traffic Ops server. Overriden by --to-user.

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, passing https://test: to --to-url will cause an exit code of 2, not 32.

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 printed

  • pretty – If True, attempt to pretty-print payloads as JSON

  • request_header – If True, print request line and request headers

  • response_header – If True, print response line and response headers

  • request_payload – If True, print the request payload

  • indent – 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