AMPS Python Client
==================

Introduction
------------

The AMPS Python Client is a Python extension module that makes it easy to 
connect to AMPS. This client builds upon the AMPS C++ Client and Python/C api 
to bring high performance AMPS connectivity to Python code.


Prerequisites
-------------

To use the AMPS Python Client, you must have the following software installed 
and configured on your system:

* Python 3.8 and above.
* Python setuptools. Most python installations build and include this package 
by default, but you may run into issues building this extension module if 
setuptools is not functioning properly on your system.
* C++ compiler. gcc 4.9 or greater on Linux, or a verion of Visual Studio with 
Mainstream Support from Microsoft (please refer to Microsoft product lifecycle 
policies) on Windows. Note that this must be the same compiler used to build 
your python distribution, else python distutils may be unable to invoke your 
compiler.


Fedora prerequisites:
1. dnf install redhat-rpm-config
2. dnf install python3-devel # for use with Python3
3. dnf install gcc-c++

Building From a Git Clone
-------------------------

If you obtained this client by a git clone of the 60East amps-client-python 
repository, you also need to fetch the correct version of the AMPS C++ client 
submodule. To do this, issue a git submodule command to initialize and update 
the src/cpp submodule. One easy way to do this is by issuing the command:

    git submodule update --init

which will initialize and update the submodule in one step. Note that working 
with submodules in git requires extra care. Visit [this 
chapter](http://git-scm.com/book/en/Git-Tools-Submodules) to learn more about 
git submodules.

Build
-----

This client is distributed as source code and must be compiled before it is 
used. The build process emits a shared library (or DLL on Windows) that can be 
imported into your python application.

### To build on Linux:

1. Run `python3 setup.py build` from the AMPS Python Client directory to build 
the client.

   This script uses Python distutils to build the client library. Python 
distutils provides many additional options for installing the built library 
into your Python distribution, or otherwise controlling the output of the build 
process. Run `python3 setup.py --help` to view command help.

2. Check under the `build` directory for `AMPS.abi3.so` -- this is the Python 
extension module. Ensure this library's directory is in your PYTHONPATH.

3. To test, run `python3 -c "import AMPS"`.  If any errors occur importing the 
AMPS module, validate that the module built properly, and that the containing 
directory is in your PYTHONPATH.

### To build on Windows:

1. Use a Visual Studio Command Prompt to create a command prompt where the 
necessary Visual Studio environment variables are set for command line builds.

2. Add the Python directory (the location of the python.exe interpreter) to 
your path.

3. Run `python setup.py build` fom the AMPS Python Client directory to build 
the client module.

4. Check under the `build` directory for `AMPS.pyd` -- this is the Python 
extension module. Ensure this library's directory is in your PYTHONPATH.

5. To test, run `python -c "import AMPS"`. If any errors occur importing the 
AMPS module, validate that the module built properly, and that the containing 
directory is in your PYTHONPATH.

Installing the Python Binary Wheel
----------------------------------

60East also provides Linux-x86-64, Linux-aarch64, Macosx-arm64, and Windows 
x86-64 64-bit binary wheels built for Python 3.x.  These wheel files are 
provided on the 60East website and are available to install using `pip`.

## Installing From the 60East website:

1. Download the wheel file from the 60East client release page.

2. run 'python3 -m pip install *.whl'.

## Installing From pip:

1. run 'python3 -m pip install amps-python-client'.

Troubleshooting Build Problems
------------------------------

Symptom: Python.h not found

Resolution: Update or install python distutils. See the entry on python 
distutils in the prequisites section for information on installing this package.


For More Information
--------------------

The [AMPS Python Developer's 
Guide](https://crankuptheamps.com/clients/amps-client-python) is available on 
the 60East website. Generated API reference documentation for this client is 
available under the doc/ directory.

