diff --git a/docs/user-guide/gaffer-basics/what-is-python.md b/docs/user-guide/gaffer-basics/what-is-python.md index e69de29bb2..2a96486401 100644 --- a/docs/user-guide/gaffer-basics/what-is-python.md +++ b/docs/user-guide/gaffer-basics/what-is-python.md @@ -0,0 +1,43 @@ +# What is Python and how is it used in Gaffer? + +Python is a popular high level programming language that's seen massive popularity specifically in the data science and educational programming areas. Python is an interpreted general purpose language that's dynamically typed and garbage collected. For more info on Python please reference theĀ [official Python docs](https://www.python.org/). + +## Python in Gaffer + +Whilst Gaffer is written primarily in Java a Python interface has been provided so that you can programmatically access Gaffer functionality with Python, this can be accessed via the gafferpy library located in the [gaffer-tools repository](https://github.com/gchq/gaffer-tools). +This provides a Python 3.6+ compatible import that will allow you to speak directly to the Gaffer REST API, it supports persistent connections to Gaffer, connection via SSL and the associated Python functionality to interact with available Gaffer operations. + +!!! note + See the page on [using the Python API](../apis/python-api.md) in gaffer for further information. + +Inside the gaffer-tools library you'll find a set of examples that show how you can interact with Gaffer, here is a basic example of using gafferpy: + +!!! example "" + This executes a get request into Gaffer to retrieve the current schema. + + ```py + from gafferpy import gaffer as g + from gafferpy import gaffer_connector + + def get_schema(gc) -> None: + """Gets and prints the schema from the Gaffer graph instance. + + Args: + gc: The pre-initialised gaffer_connector. + """ + # Get Schema + result = gc.execute_get(g.GetSchema()) + + # Print result + print("Schema:\n{0}\n".format(result)) + + # Establish connection + g_connector = gaffer_connector.GafferConnector("http://localhost:8080/rest") + get_schema(g_connector) + ``` + +In this simple example you can see the use of a `gaffer_connector`; the purpose of this is to orchestrate the connection to a Gaffer REST endpoint. +The main `gaffer` Python module (usually imported as `g`) allows access to various functions to run Gaffer operations. This connection works by serialising the Python code into JSON and then transferring this to be deserialised and ran in Gaffer. + +!!! tip + A link to the gaffer tools repository can be found here: [GCHQ/gaffer-tools](https://github.com/gchq/gaffer-tools)