To start using the python shell you will need an instance of the REST API running. You can start the Gaffer road-traffic-demo rest server and ui (see ui/README.md) using the command:

./ui/example/road-traffic/scripts/start.sh

Once this is running you can run the python example by using the command (all commands are run from the root of the python-shell project):

python3 src/example.py
python3 src/example_map.py

Alternatively if you have you own REST API running that is authenticated with PKI certificates then you can follow the pki example. Before using the example you will need to export your PKI certificate into a .pem file:

python3 src/example_pki.py
python3 src/example_map_pki.py

To use the python shell without installing just ensure you are execute your scripts from within the python-shell directory. To connect to gaffer you will need to do something like this:

from gafferpy import gaffer as g
from gafferpy import gaffer_connector
gc = gaffer_connector.GafferConnector("http://localhost:8080/rest/latest")

To fetch the Gaffer schema you can then run:

result = gc.execute_get(g.GetSchema())

print('Schema:')
print(result)
print()

You can run an operation like this:

elements = gc.execute_operation(
    operation=g.GetAllElements()
)

Multiple operations like this:

elements = gc.execute_operations(
    operations=[
        g.GetAllElements(),
        g.Limit(result_limit=3)
    ]
)

And an operation chain like this:

elements = gc.execute_operation_chain(
    operation_chain=g.OperationChain(
        operations=[
            g.GetAllElements(),
            g.Limit(
                truncate=True,
                result_limit=3
            )
        ]
    )
)

See operation examples for more examples of operations in python.

Installation

We currently don't release gafferpy on pypi, but there are plently of ways to use it once you have the source code.
As well as refering to the Python source files as above, you can also build gafferpy from source (useful for distribution) or install a local copy in develop mode that will update when you change the source code.

Build with bdist_wheel

This option builds gafferpy and puts the binaries in python-shell/dist where it can then be distributed and installed with pip install.

Compilation of the project requires the wheel package, this can be installed using pip:

pip3 install wheel

The project can then be compiled by running the following command from the root of the python-shell project:

python3 setup.py bdist_wheel

This creates a distributable Python wheel which can installed locally to provide the Gaffer Python shell to other applications.

The wheel file is install using pip:

pip3 install dist/gafferpy-<gaffer.version>-py2.py3-none-any.whl

Developer installation

Alternatively, if you want to just install gafferpy locally and have any code changes you make to it reflected in your installation, you can go to the python-shell directory and run:

pip3 install -e .

Note that this does not install the dependencies, which can be found in the requirements.txt, and installed with:

pip3 install -r requirements.txt

Import

After either installation, the shell can be imported into an application from anywhere as below:

from gafferpy import gaffer as g
from gafferpy import gaffer_connector
gc = gaffer_connector.GafferConnector("http://localhost:8080/rest/latest")

Testing

We have some unit and integration tests for our python shell. To run all of the tests, first deploy the REST API (UI will also be deploy):

./ui/example/road-traffic/scripts/start.sh

then from within the python-shell folder run:

python3 -m unittest discover