Metadata-Version: 2.1
Name: Apache-TrafficControl
Version: 1.1.2
Summary: Python API Client for Traffic Control
Home-page: http://trafficcontrol.apache.org/
Author: Apache Software Foundation
Author-email: dev@trafficcontrol.apache.org
License: http://www.apache.org/licenses/LICENSE-2.0
Keywords: Apache TrafficControl Traffic Control Client TrafficOps Ops
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
Requires-Dist: future (>=0.16.0)
Requires-Dist: requests (>=2.13.0)
Requires-Dist: munch (>=2.1.1)
Provides-Extra: dev
Requires-Dist: pylint (<3.0,>=2.0) ; extra == 'dev'

************
Introduction
************
This is the Traffic Ops Python Client for Python 2.x and Python 3.x.

.. attention:: Traffic Control version 3.0.0 officially deprecates Python 2.x support. Starting with Traffic Control version 4.0.0, Python 2.x support will be dropped, and only Python 3.x will be supported. Users and developers are encouraged to switch to Python 3 as soon as possible.

.. note:: This client has only been tested against Python 2.7, 3.4, and 3.6. Other versions may or may not work.

Installation
============
The official installation method is to use ``pip`` to install directly from from GitHub.

.. code-block:: shell
	:caption: Install Using 'pip' From GitHub

	pip install git+https://github.com/apache/trafficcontrol.git#"egg=trafficops&subdirectory=traffic_control/clients/python"

	# or
	# pip install "git+ssh://git@github.com/apache/trafficcontrol.git#"egg=trafficops&subdirectory=traffic_control/clients/python"

Local Installation
------------------
The preferred method is to use ``pip`` to install locally. Starting from the repository's root directory, the following script should do the job:

.. code-block:: shell
	:linenos:
	:caption: Local Installation of Python Client

	cd traffic_control/clients/python
	pip install .

	# The above will install using the system's default Python interpreter - to use a specific
	# version it will be necessary to specify the interpreter and pass the 'pip' module to it.
	# e.g. for the system's default Python 2 interpreter, typically one would do:
	# sudo -H /usr/bin/env python2 -m pip install .

	# Developers may wish to use the '-e' flag. This will install the package 'edit-ably',
	# meaning that changes made to the package within the repository structure will be effected on
	# the system-wide installation.
	# sudo -H pip install -e .

	# If your system does not have 'pip', but does (somehow) have 'setuptools' as well
	# as the package's dependencies, you can call 'setup.py' directly to install the
	# package for the system's default Python 3 interpreter
	# sudo -H ./setup.py install

The local installation method requires ``pip`` and ``setuptools``. ``setuptools`` should be installed if your system has ``pip``, but if you are missing either of them they can both be relatively easily installed with Python standard libraries.

.. code-block:: shell
	:caption: Setuptools Package Installation

	# Here I'm using 'python' because that points to a Python 3 interpreter on my system. You may
	# wish to use 'python3' or 'python2' (please not that one) instead.
	sudo -H python -m ensure_pip
	sudo -H python -m pip install -U pip

	# If your system's 'python' already has 'pip', then you may skip to this step to
	# install only 'setuptools'
	sudo -H python -m pip install setuptools

Development Dependencies
------------------------
To install the development dependencies, first ensure that your system has ``pip`` and ``setuptools`` then use ``pip`` to install the development environment.

.. note:: Currently, the development environment only "requires" `Pylint <https://www.pylint.org/>`_, which is a simple linter for which a configuration file is provided at :file:`traffic_control/clients/python/pylint.rc`. This linter might be nice to catch common mistakes, but is in no way enforced by the project at this time. Once Python2 support is dropped with the release of the Apache-TrafficControl package 2.0, it will hopefully be refined and put to use. In the meantime, feel free to use it - or not.

.. code-block:: shell
	:caption: Development Dependencies Installation

	pip install -e .[dev]


Versioning
==========
The :mod:`trafficops.__version__` module contains only the :data:`__version__` "constant" which
gives the version of this *Apache-TrafficControl package* and **not** the version of
*Apache Traffic Control* for which it was made. The two are versioned separately, to allow the
client to grow in a version-controlled manner without being tied to the release cadence of Apache
Traffic Control as a whole.

Version 1.0 is supported for use with Apache Traffic Control version 3.0 (release pending at the
time of this writing). New functionality will be added as the :ref:`to-api` evolves, but changes to
this client will remain non-breaking for existing code using it until the next major version is
released.

.. deprecated:: 1.0
	The v1.0 release of this client deprecates support of Python2. Versions 2.0 and onward will
	*only* support Python3 (v3.4+). Note that this release is expected either by the time Python2
	reaches its end-of-life at the end of 2019, or with the release of Apache Traffic Control v4.0,
	should that happen first. Users and developers are encouraged to switch to Python3 as soon as
	possible.


