|
1 | | -<img align="right" width="200" height="auto" src="https://github.com/gchq/Gaffer/raw/develop/logos/logo.png"> |
2 | | - |
3 | | -# Gaffer Python Client |
4 | | - |
5 | | - |
6 | | -[<img src="https://img.shields.io/badge/docs-passing-success.svg?logo=readthedocs">](https://gchq.github.io/gafferpy/) |
7 | | - |
8 | | -## Features |
9 | | - |
10 | | -- Persistently connect to a Gaffer rest api to run operations |
11 | | -- Connect using PKI certificates and SSL |
12 | | -- Generate Python client code for custom Operations, Predicates, Binary Operators and Functions |
13 | | -- Turn existing json queries into Python objects |
14 | | - |
15 | | -## Installation |
16 | | - |
17 | | -Gafferpy requires Python 3.6+. We don't currently release gafferpy on pypi, but you can install it over ssh with: |
18 | | - |
19 | | -```bash |
20 | | -pip install git+https://github.com/gchq/gafferpy.git |
21 | | -``` |
22 | | - |
23 | | -Or if you have the source code locally and want any changes you make reflected in your installation, you can run: |
24 | | - |
25 | | -```bash |
26 | | -pip install -e . |
27 | | -``` |
28 | | - |
29 | | -## Quick Start |
30 | | - |
31 | | -The python shell connects to a running Gaffer REST API. |
32 | | -You can start the Gaffer road-traffic-demo rest server from the Gaffer repository, using the command: |
33 | | - |
34 | | -```bash |
35 | | -mvn clean install -pl :road-traffic-demo -Proad-traffic-demo,quick |
36 | | -``` |
37 | | - |
38 | | -```python |
39 | | -# Import the client library and connector |
40 | | -from gafferpy import gaffer as g |
41 | | -from gafferpy import gaffer_connector |
42 | | - |
43 | | -# Instantiate a connector |
44 | | -gc = gaffer_connector.GafferConnector("http://localhost:8080/rest/latest") |
45 | | - |
46 | | -# You can use the connector to perform get requests |
47 | | -schema = gc.execute_get(g.GetSchema()) |
48 | | - |
49 | | -# And also run operations |
50 | | -elements = gc.execute_operation( |
51 | | - operation=g.GetAllElements() |
52 | | -) |
53 | | - |
54 | | -# Multiple operations |
55 | | -elements = gc.execute_operations( |
56 | | - operations=[ |
57 | | - g.GetAllElements(), |
58 | | - g.Limit(result_limit=3) |
59 | | - ] |
60 | | -) |
61 | | - |
62 | | -# And operation chains |
63 | | -elements = gc.execute_operation_chain( |
64 | | - operation_chain=g.OperationChain( |
65 | | - operations=[ |
66 | | - g.GetAllElements(), |
67 | | - g.Limit( |
68 | | - truncate=True, |
69 | | - result_limit=3 |
70 | | - ) |
71 | | - ] |
72 | | - ) |
73 | | -) |
74 | | -``` |
75 | | - |
76 | | -See [operation examples](https://gchq.github.io/gaffer-doc/v1docs/getting-started/operations/contents) for more examples of operations in python. |
77 | | - |
78 | | -## Coding Style |
79 | | -Please ensure that your coding style is consistent with the rest of the Gaffer project. Guides on the coding style for Gaffer can be found [here](https://gchq.github.io/gaffer-doc/latest/ways-of-working/#coding-style) |
80 | | - |
81 | | -## Testing |
82 | | - |
83 | | -```bash |
84 | | -# To run all of the tests, first deploy the road traffic example |
85 | | -# This needs to be done from the Gaffer java repository |
86 | | -mvn clean install -pl :road-traffic-demo -Proad-traffic-demo,quick |
87 | | - |
88 | | -# Then run |
89 | | -python -m unittest discover |
90 | | -``` |
91 | | - |
92 | | -## Building the documentation |
93 | | - |
94 | | -To build the docs locally, assuming you have Python installed, install the docs dependencies: |
95 | | -```bash |
96 | | -cd docs |
97 | | -pip install -r requirements.txt |
98 | | -``` |
99 | | - |
100 | | -Then use the sphinx Makefile: |
101 | | -```bash |
102 | | -make html |
103 | | -``` |
104 | | - |
105 | | -## License |
106 | | - |
107 | | -Copyright 2016-2022 Crown Copyright |
108 | | - |
109 | | -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 |
110 | | - |
111 | | -[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) |
112 | | - |
113 | | -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. |
| 1 | +<img align="right" width="200" height="auto" src="https://github.com/gchq/Gaffer/raw/develop/logos/logo.png"> |
| 2 | + |
| 3 | +# Gaffer Python Client |
| 4 | + |
| 5 | + |
| 6 | +[<img src="https://img.shields.io/badge/docs-passing-success.svg?logo=readthedocs">](https://gchq.github.io/gafferpy/) |
| 7 | + |
| 8 | +## Features |
| 9 | + |
| 10 | +- Persistently connect to a Gaffer rest api to run operations |
| 11 | +- Connect using PKI certificates and SSL |
| 12 | +- Generate Python client code for custom Operations, Predicates, Binary Operators and Functions |
| 13 | +- Turn existing json queries into Python objects |
| 14 | + |
| 15 | +## Installation |
| 16 | + |
| 17 | +`gafferpy` requires Python 3.6+. We do not currently release `gafferpy` on PyPI, but you can install it over ssh with: |
| 18 | + |
| 19 | +```bash |
| 20 | +pip install git+https://github.com/gchq/gafferpy.git |
| 21 | +``` |
| 22 | + |
| 23 | +Or if you have the source code locally and want any changes you make reflected in your installation, you can run: |
| 24 | + |
| 25 | +```bash |
| 26 | +pip install -e . |
| 27 | +``` |
| 28 | + |
| 29 | +## Quick Start |
| 30 | + |
| 31 | +The Python shell connects to a running Gaffer REST API. |
| 32 | +You can start the Gaffer [`road-traffic-demo`](https://github.com/gchq/Gaffer/blob/master/example/road-traffic/README.md) REST server from the Gaffer repository, using the command: |
| 33 | + |
| 34 | +```bash |
| 35 | +mvn clean install -pl :road-traffic-demo -Proad-traffic-demo,quick |
| 36 | +``` |
| 37 | +To connect to the running Gaffer API from Python (more information on the Python shell can be found [here](https://gchq.github.io/gaffer-doc/latest/user-guide/apis/python-api/)): |
| 38 | +```python |
| 39 | +# Import the client library and connector |
| 40 | +from gafferpy import gaffer as g |
| 41 | +from gafferpy import gaffer_connector |
| 42 | + |
| 43 | +# Instantiate a connector |
| 44 | +gc = gaffer_connector.GafferConnector("http://localhost:8080/rest/latest") |
| 45 | +``` |
| 46 | +Then perform requests against it: |
| 47 | +```python |
| 48 | +# You can use the connector to perform GET requests |
| 49 | +schema = gc.execute_get(g.GetSchema()) |
| 50 | + |
| 51 | +# And also run operations |
| 52 | +elements = gc.execute_operation( |
| 53 | + operation=g.GetAllElements() |
| 54 | +) |
| 55 | + |
| 56 | +# Multiple operations |
| 57 | +elements = gc.execute_operations( |
| 58 | + operations=[ |
| 59 | + g.GetAllElements(), |
| 60 | + g.Limit(result_limit=3) |
| 61 | + ] |
| 62 | +) |
| 63 | + |
| 64 | +# And operation chains |
| 65 | +elements = gc.execute_operation_chain( |
| 66 | + operation_chain=g.OperationChain( |
| 67 | + operations=[ |
| 68 | + g.GetAllElements(), |
| 69 | + g.Limit( |
| 70 | + truncate=True, |
| 71 | + result_limit=3 |
| 72 | + ) |
| 73 | + ] |
| 74 | + ) |
| 75 | +) |
| 76 | +``` |
| 77 | + |
| 78 | +See [Operations Guide](https://gchq.github.io/gaffer-doc/latest/reference/operations-guide/operations) for more examples of operations in Python. |
| 79 | + |
| 80 | +## Developer Guide |
| 81 | + |
| 82 | +### Coding Style |
| 83 | +Please ensure that your coding style is consistent with the rest of the Gaffer project. Guides on the coding style for `gafferpy` and Gaffer can be found [here](https://gchq.github.io/gaffer-doc/latest/development-guide/ways-of-working). |
| 84 | + |
| 85 | +### Testing |
| 86 | + |
| 87 | +The `gafferpy` tests are implemented using `tox` and `pytest`. |
| 88 | +To run the tests, install the `gafferpy` 'dev' extra: |
| 89 | +```bash |
| 90 | +pip install -e ".[dev]" # the quotes ensure compatibilty with zsh |
| 91 | +``` |
| 92 | +This will install extra development dependecies for running tests and building documentation. |
| 93 | + |
| 94 | +`gafferpy` has both unit tests and integration tests - the integration tests use the Road Traffic Example to test the Python API. If this is not running, the integration tests are skipped. It is advisable that the integration tests are run prior to any code commits to ensure they do not fail due to any code changes. |
| 95 | + |
| 96 | +*For help starting the Road Traffic Example, see the [Quick Start](#quick-start) section above.* |
| 97 | + |
| 98 | +To run the tests, execute the below from the root directory of `gafferpy`: |
| 99 | +```bash |
| 100 | +tox |
| 101 | +``` |
| 102 | +By default, `tox` will and try run the tests in multiple test envs (different Python versions) - if they do not exist then they are skipped. |
| 103 | +To run the test for a specifc test env e.g. Python3.9, run: |
| 104 | +```bash |
| 105 | +tox -e py39 |
| 106 | +``` |
| 107 | + |
| 108 | +### Building the documentation |
| 109 | + |
| 110 | +To build the docs locally, assuming you have Make and Python installed, and `gafferpy` installed with the 'dev' extra: |
| 111 | +```bash |
| 112 | +cd docs |
| 113 | +make html |
| 114 | +``` |
| 115 | + |
| 116 | +### Generating the Python API |
| 117 | +`gafferpy` has the ability to regenerate the Python API based upon the Gaffer REST API that a `GafferConnector` object is pointing at - a more detailed description and examples of how to do this can be found [here](./src/fishbowl/README.md). |
| 118 | + |
| 119 | +## License |
| 120 | + |
| 121 | +Copyright 2016-2024 Crown Copyright |
| 122 | + |
| 123 | +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 |
| 124 | + |
| 125 | +[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) |
| 126 | + |
| 127 | +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. |
0 commit comments