From ae52bd01ebd824daa20f8456d0f3db8ed5862389 Mon Sep 17 00:00:00 2001 From: Benjamin Braatz Date: Wed, 24 Jul 2024 16:13:42 +0200 Subject: [PATCH] Add some clarifications to documentation * Where to find the correct certificate chain and key file * Optionally using a virtual environment to encapsulate dependency installation * Some additions to .gitignore to have cleaner statuses --- .gitignore | 9 ++++++--- doc/index.md | 43 +++++++++++++++++++++++++++++-------------- 2 files changed, 35 insertions(+), 17 deletions(-) diff --git a/.gitignore b/.gitignore index e0bb05d..badcbce 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ -graph.crt -config.json -*-briefbogen.pdf +/venv/ +/graph_graphit.egg-info/ +/graph.crt +/config.json +/*-briefbogen.pdf +__pycache__/ diff --git a/doc/index.md b/doc/index.md index e3f6bca..f2dd065 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,25 +1,39 @@ # Python Graph API - This is a minimal Python API for the [Graph](https://graph-it.com/). It works with Python 2 as well as Python 3. ## Installation +Optionally, create and activate a virtual environment, so that +installations are not system-wide: +```shellsession +$ python -m venv +$ source /bin/activate +``` -The Python Graph API can be installed with `pip` directly from our git repository: -```sh +The Python Graph API can be installed with `pip` directly from our git +repository: +```shellsession $ pip install git+git://git.graph-it.com/graphit/graph-client-py.git ``` The Graph API uses [msgpack](https://msgpack.org/). So, the Python binding for it will be installed as a dependency. -In order to use TLS connections to graphs, a client certificate chain has to -be available in a file. +In order to use TLS connections to graphs, a client certificate chain +including the private key has to be available in a file. +(Internally, +[`SSLContext.load_cert_chain()`](https://docs.python.org/3/library/ssl.html#ssl.SSLContext.load_cert_chain) +is used to establish the TLS connection.) -## Usage +In our current graph installations a chain file with a private key can be +found in `/var/lib/graph/var/cert/srv/local.srv.pem`: +```shellsession +$ scp graph.example.com:/var/lib/graph/var/cert/srv/local.srv.pem graph.crt +``` -A graph connection is initialised by giving a URL and optionally the filename -of the certificate chain to the constructor: +## Usage +A graph connection is initialised by giving a URL and (if it is a TLS URL) +the filename of the certificate chain to the constructor: ```python >>> import graph >>> gc = graph.Connection('tls://graph.example.com:4439', 'graph.crt') @@ -48,16 +62,17 @@ attribut:

Allgemeines Merkmal

``` ## Test script - The `test.py` script reads the configuration of a main graph from `config.json`, queries this main graph for remote graphs configured in it, -prints a summary of all graph modules in the main graph and all remote graphs -and downloads stationeries in all the graphs if they are configured there. +prints a summary of all graph modules in the main graph and all remote +graphs and downloads stationeries in all the graphs if they are configured +there. ## Plans - Up to now, only a raw connection is implemented, -i.e., the Python implementation does not know anything about the actual API calls and just passes them to the graph server. +i.e., the Python implementation does not know anything about the actual API +calls and just passes them to the graph server. We should add implementation and documentation for these actual API calls. -This would also allow to do at least some of the necessary conversions already in the library. +This would also allow to do at least some of the necessary conversions +already in the library. -- 2.34.1