diff --git a/python-shell/README.md b/python-shell/README.md index 092e2b2bc..d14e982dd 100644 --- a/python-shell/README.md +++ b/python-shell/README.md @@ -1,70 +1,64 @@ -# Deprecated + -The python-shell, or gafferpy, has been [deprecated](https://github.com/gchq/gaffer-tools/issues/951) as of 24/11/21. We plan to delete it at some point in the Gaffer 2 release process. This is because gafferpy is being replaced by fishbowl for Gaffer 2 graphs. Before Gaffer 2.0.0's full release, fishbowl will be updated to work with Gaffer 2 and have all the missing functionality added to it. Therefore, in the future, you should use fishbowl for interacting with Gaffer 2 graphs and gafferpy for Gaffer 1 graphs. -## Python shell +# Gaffer Python Client -This python shell connects to a Gaffer REST API and requires Python 3.x See [gaffer-tools/python-shell](https://github.com/gchq/gaffer-tools/tree/master/python-shell). +![ci](https://github.com/gchq/gaffer-tools/actions/workflows/continuous-integration.yaml/badge.svg) +[](https://gchq.github.io/gaffer-doc/latest/) -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: +## Features + +- Persistently connect to a Gaffer rest api to run operations +- Connect using PKI certificates and SSL +- Generate Python client code for custom Operations, Predicates, Binary Operators and Functions +- Stream results back + +## Installation + +Gafferpy requires Python 3.6+. We don't currently release gafferpy on pypi, but you can install it over ssh with: ```bash -./ui/example/road-traffic/scripts/start.sh +pip install git+https://github.com/gchq/gaffer-tools.git#subdirectory=python-shell ``` -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\): +Or if you have the source code locally and want any changes you make reflected in your installation, you can go to the python-shell directory and run: ```bash -python3 src/example.py -python3 src/example_map.py +pip install -e . ``` -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: +## Quick Start + +The python shell connects to a running Gaffer REST API. You can start the Gaffer road-traffic-demo rest server and [ui](../ui/README.md) using the command: ```bash -python3 src/example_pki.py -python3 src/example_map_pki.py +./ui/example/road-traffic/scripts/start.sh ``` -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: - ```python +# Import the client library and connector 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: - -```python -result = gc.execute_get(g.GetSchema()) -print('Schema:') -print(result) -print() -``` +# Instantiate a connector +gc = gaffer_connector.GafferConnector("http://localhost:8080/rest/latest") -You can run an operation like this: +# You can use the connector to perform get requests +schema = gc.execute_get(g.GetSchema()) -```python +# And also run operations elements = gc.execute_operation( operation=g.GetAllElements() ) -``` - -Multiple operations like this: -```python +# Multiple operations elements = gc.execute_operations( operations=[ g.GetAllElements(), g.Limit(result_limit=3) ] ) -``` -And an operation chain like this: - -```python +# And operation chains elements = gc.execute_operation_chain( operation_chain=g.OperationChain( operations=[ @@ -80,69 +74,14 @@ elements = gc.execute_operation_chain( See [operation examples](https://gchq.github.io/gaffer-doc/v1docs/getting-started/operations/contents) 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: - -```bash -pip3 install wheel -``` - -The project can then be compiled by running the following command from the root of the python-shell project: - -```bash -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: - -```bash -pip3 install dist/gafferpy--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: - -```bash -pip3 install -e . -``` -Note that this does not install the dependencies, which can be found in the `requirements.txt`, and installed with: -```bash -pip3 install -r requirements.txt -``` - - -#### Import -After either installation, the shell can be imported into an application from anywhere as below: - -```python -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\): +## Testing ```bash +# To run all of the tests, first deploy the road traffic example ./ui/example/road-traffic/scripts/start.sh -``` - -then from within the python-shell folder run: -```bash -python3 -m unittest discover +# Then from within the python-shell folder run +python -m unittest discover ``` ## License diff --git a/python-shell/setup.py b/python-shell/setup.py index 103d53505..178442ab5 100644 --- a/python-shell/setup.py +++ b/python-shell/setup.py @@ -16,18 +16,15 @@ "License :: OSI Approved :: Apache Software License", "Operating System :: OS Independent", "Programming Language :: Python", - "Programming Language :: Python :: 3" - "Programming Language :: Python :: 3.0", - "Programming Language :: Python :: 3.1", - "Programming Language :: Python :: 3.2", - "Programming Language :: Python :: 3.3", - "Programming Language :: Python :: 3.4", - "Programming Language :: Python :: 3.5", + "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3 :: Only", "Topic :: Software Development :: Libraries :: Python Modules", ] -install_requires = [] +python_requires = ">3.6" +install_requires = [ + "requests>=2.4.0" +] ############################################################################### @@ -81,5 +78,6 @@ def find_meta(meta): zip_safe=False, classifiers=classifiers, install_requires=install_requires, + python_requires=python_requires, py_modules=['gafferpy.gafferpy', 'gafferpy.example'] ) diff --git a/python-shell/src/__init__.py b/python-shell/src/__init__.py index 121d3a323..e69de29bb 100644 --- a/python-shell/src/__init__.py +++ b/python-shell/src/__init__.py @@ -1,11 +0,0 @@ -__version__ = "2.0.0-alpha-0.2" - -__title__ = "gafferpy" -__description__ = "Gaffer Python Shell" -__uri__ = "https://github.com/gchq/gafferpy-tools" -__doc__ = __description__ + " <" + __uri__ + ">" - -__author__ = "GCHQ" - -__license__ = "Apache 2.0" -__copyright__ = "Crown Copyright (c) 2016-2017" diff --git a/python-shell/src/Gaffer-Python-Demo.ipynb b/python-shell/src/examples/Gaffer-Python-Demo.ipynb similarity index 100% rename from python-shell/src/Gaffer-Python-Demo.ipynb rename to python-shell/src/examples/Gaffer-Python-Demo.ipynb diff --git a/python-shell/src/examples/__init__.py b/python-shell/src/examples/__init__.py new file mode 100644 index 000000000..121d3a323 --- /dev/null +++ b/python-shell/src/examples/__init__.py @@ -0,0 +1,11 @@ +__version__ = "2.0.0-alpha-0.2" + +__title__ = "gafferpy" +__description__ = "Gaffer Python Shell" +__uri__ = "https://github.com/gchq/gafferpy-tools" +__doc__ = __description__ + " <" + __uri__ + ">" + +__author__ = "GCHQ" + +__license__ = "Apache 2.0" +__copyright__ = "Crown Copyright (c) 2016-2017" diff --git a/python-shell/src/example.py b/python-shell/src/examples/example.py similarity index 100% rename from python-shell/src/example.py rename to python-shell/src/examples/example.py diff --git a/python-shell/src/example_map.py b/python-shell/src/examples/example_map.py similarity index 100% rename from python-shell/src/example_map.py rename to python-shell/src/examples/example_map.py diff --git a/python-shell/src/example_map_pki.py b/python-shell/src/examples/example_map_pki.py similarity index 100% rename from python-shell/src/example_map_pki.py rename to python-shell/src/examples/example_map_pki.py diff --git a/python-shell/src/example_pki.py b/python-shell/src/examples/example_pki.py similarity index 100% rename from python-shell/src/example_pki.py rename to python-shell/src/examples/example_pki.py diff --git a/python-shell/src/fromJson.py b/python-shell/src/fromJson.py deleted file mode 100755 index ad8f96d1a..000000000 --- a/python-shell/src/fromJson.py +++ /dev/null @@ -1,36 +0,0 @@ -# -# Copyright 2016-2019 Crown Copyright -# -# 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. -# - -import sys - -from gafferpy import gaffer as g - -if __name__ == "__main__": - if len(sys.argv) < 2: - raise TypeError('JSON str argument is required') - - json_str = sys.argv[1] - if len(sys.argv) > 2: - class_name = sys.argv[2] - else: - class_name = None - - pythonObj = g.JsonConverter.from_json(json_str, - class_name=class_name) - if not isinstance(pythonObj, g.ToCodeString): - raise TypeError('Unable to convert JSON to a Python: ' + json_str) - - print(pythonObj.to_code_string()) diff --git a/python-shell/src/test/test_example.py b/python-shell/src/test/test_example.py index d7459d47a..1a0ad9c35 100755 --- a/python-shell/src/test/test_example.py +++ b/python-shell/src/test/test_example.py @@ -16,7 +16,7 @@ import unittest -import example +from examples import example class ExampleTest(unittest.TestCase): diff --git a/python-shell/src/test/test_example_map.py b/python-shell/src/test/test_example_map.py index 87b7d58c4..785de42f6 100644 --- a/python-shell/src/test/test_example_map.py +++ b/python-shell/src/test/test_example_map.py @@ -16,7 +16,7 @@ import unittest -import example_map +from examples import example_map class ExampleMapTest(unittest.TestCase):