[GitHub] [trafficcontrol] rawlinp commented on a change in pull request #3266: Added an implementation of the to-access functions to Python client package

[GitBox <gi...@apache.org>]

rawlinp commented on a change in pull request #3266: Added an implementation of the to-access functions to Python client package
URL: https://github.com/apache/trafficcontrol/pull/3266#discussion_r262232428
 
 

 ##########
 File path: traffic_control/clients/python/to_access/__init__.py
 ##########
 @@ -0,0 +1,620 @@
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""
+.. _toaccess:
+
+.. program:: 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 :file:`to{method}` where `method` is the name of
+an HTTP method (in lowercase). Collectively they are referred to as :program:`toaccess` Implemented
+methods thus far are:
+
+- delete
+- head
+- get
+- options
+- patch
+- post
+- put
+
+Arguments and Flags
+-------------------
+.. option:: PATH
+
+	This is the request path. By default, whatever is passed is considered to be relative to
+	:file:`/api/{api_version}/` where ``api_version`` is :option:`--api_version`. This behavior can
+	be disabled by using :option:`--raw_path`.
+
+.. option:: 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.
+
+.. option:: -h, --help
+
+	Print usage information and exit
+
+.. option:: -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
+	:option:`--raw_path` is used. (Default: 1.3)
+
+.. option:: -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 :option:`--request_headers`, :option:`--request_payload`, and
+	:option:`--response_headers` at the same time, and those options will have no effect if given.
+	(Default: false)
+
+.. option:: -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)
+
+.. option:: -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)
+
+.. option:: -r, --raw_path
+
+	Request exactly :option:`PATH`; do not preface the request path with :file:`/api/{api_version}`.
+	This effectively means that :option:`--api_version` will have no effect. (Default: false)
+
+.. option:: --request_headers
+
+	Output the request method line and any and all request headers. (Default: false)
+
+.. option:: --request_payload
+
+	Output the request body if any was sent. Will attempt to pretty-print the body as JSON if
+	:option:`--pretty` is used. (Default: false)
+
+.. option:: --response_headers
+
+	Output the response status line and any and all response headers. (Default: false)
+
+.. option:: --to_url URL
+
+	The :abbr:`FQDN (Fully Qualified Domain Name)` and optionally the port and scheme of the Traffic
+	Ops server. This will override :envvar:`TO_URL`. The format is the same as for :envvar:`TO_URL`.
+	(Default: uses the value of :envvar:`TO_URL`)
+
+.. option:: --to_password PASSWORD
+
+	The password to use when authenticating to Traffic Ops. Overrides :envvar:`TO_PASSWORD`.
+	(Default: uses the value of :envvar:`TO_PASSWORD`)
+
+.. option:: --to_user USERNAME
+
+	The username to use when connecting to Traffic Ops. Overrides :envvar:`TO_USER`. (Default: uses
+	the value of :envvar:`TO_USER`)
+
+Environment Variables
+---------------------
+If defined, :program:`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 :option:`--to_url`, :option:`--to_user`, and :option:`--to_password` on
+every invocation.
+
+.. envvar:: TO_PASSWORD
+
+	Will be used to authenticate the user defined by either :option:`--to_user` or :envvar:`TO_USER`.
+
+.. envvar:: TO_URL
+
+	The :abbr:`FQDN (Fully Qualified Domain Name)` of the Traffic Ops server to which the script
+	will connect. The format of this should be :file:`[{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 :program:`toaccess` scripts will assume that port 443 should be
+	used unless otherwise specified. They will further assume that the protocol is HTTPS unless
+	:envvar:`TO_URL` (or :option:`--to_url`) starts with ``http://``, in which case the default port
+	will also be set to 80 unless otherwise specified in the URL.
+
+.. envvar:: TO_USER
+
+	The name of the user as whom to connect to the Traffic Ops server. Overriden by
+	:option:`--to_user`.
+
+Exit Codes
+----------
+The exit code of a :program:`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 :option:`--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. :option:`--request_payload` as well as
+	:option:`-p`/:option:`--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. :option:`--request_payload` as well as
+	:option:`-p`/:option:`--pretty`.
+32
+	This is the error code emitted by Python's :mod:`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
+================
+
+"""
+from __future__ import print_function, raise_from
+
+import json
+import logging
+import os
+import sys
+
+from trafficops.restapi import LoginError, OperationError, InvalidJSONError
+from trafficops.tosession import TOSession
+
+l = logging.getLogger()
+l.disabled = True
+logging.basicConfig(level=logging.CRITICAL+1)
+
+#: The full path to a file used to store the user's Mojolicious athentication cookie (currently unused)
+COOKIEFILE = "" #os.path.expanduser(os.path.join("~", ".to-auth.cookie"))
 
 Review comment:
   Since the cookie functionality is missing, I don't think we should include this or the `set_cookie` function. If it gets added later, that's fine, but right now this is just going to be dead code that is misleading.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services