Add python client library (#474)

* 'building', testing and deployment on PyPI via travis-ci
* documentation hosting on readthedocs

.travis.yml

@@ -0,0 +1,24 @@
+dist: trusty
+language: python
+python:
+  - 2.7
+  - 3.5
+  - 3.6
+install:
+  - cd python
+  - pip install
+  - pip install tox-travis
+script:
+  - tox
+before_deploy:
+  - cd python
+  - pip install twine
+deploy:
+  provider: pypi
+  user: nachbaur
+  password:
+    secure: QT9y2YUvHLKhT5Tn8P23REtj8yeyxtmsSymr2IG0oqBn4sfmQbEpf7GO/NYiK1h+XQwh/h9iLSvqNXYtNc/hGJotP/6Jw0JXVrkI3tqepvQY0X0AzJATX1A2ioI1q09+SJQXgEdaDZj7Dafy0vyj+nIK+Ig1zjrb1wbv89EvpVi/QMh825tQPKlZk/Y7kOyJVWWqWQOuKxSfcc4suqiPEUplUFnOXtLJZr+Q5eNX2BcaiTmlzJ+IasVZYIZUatHTiDrL5j35VnXRYfGfn+CBp/CzfJBqPMKtzk+QJwla3UYYjreG4Z35xSHR83/ErYE3GOCFrmsIZ/fnu0cMMbMzQ6kz/DhblTiPqwO+clhqZlMqkpzV2WILLZsB19tld7hNQhBLP9W2qLnMg/2rWMfuqk4sqOgMBXzbuBUSAGKZLXXXe8W0uoVbRhIeh9Kf6CKTb+SXDPh8zxsuLpgdazultK2hXQcRIIf4NEFvzKlC+12+OVtuFkeKtSrUPSAcwlWNH28aJ/URuKMK7RjkqC5ATJrdtTmg1T5FQUA2Hf+fv7vHAQnAPM8gp2lD37MG34qRkhbc1icMCxc62mJ14atwgLk5jKqOAmKjV7EIHT4bZhtn0uyukWQYUIu5NaNswvHhHR5XyJbQMjZJ3dSGN/UJNpZKdXXsDHFpH/AwqYf8HA8=
+  on:
+    tags: true
+    branch: master
+    condition: "$TRAVIS_PYTHON_VERSION == 3.6"

README.md

@@ -1,5 +1,12 @@
 # Brayns
 
+[![C++ Build Status](https://bbpcode.epfl.ch/ci/buildStatus/icon?job=oss.Brayns)](https://bbpcode.epfl.ch/ci/job/oss.Brayns/)
+[![Docker Build Status](https://bbpcode.epfl.ch/ci/buildStatus/icon?job=oss.Brayns.docker)](https://bbpcode.epfl.ch/ci/job/oss.Brayns.docker/)
+[![Python Build Status](https://travis-ci.org/BlueBrain/Brayns.svg?branch=pypi)](https://travis-ci.org/BlueBrain/Brayns)
+[![Read the Docs](https://readthedocs.org/projects/brayns/badge/?version=latest)](http://brayns.readthedocs.io/en/latest/?badge=latest)
+[![Docker Pulls](https://img.shields.io/docker/pulls/bluebrain/brayns.svg)](https://hub.docker.com/r/bluebrain/brayns/)
+[![GitHub release](https://img.shields.io/github/release/BlueBrain/Brayns.svg)](https://github.com/BlueBrain/Brayns/releases)
+
 ![Brayns](doc/images/Brayns.jpg)
 
 One of the keys towards understanding how the brain works as a whole is

python/.gitignore

@@ -1,6 +1,12 @@
-.idea*
-env/
+.coverage
+.idea/
+brayns.egg-info/
+.installed
+pycodestyle.txt
+pydocstyle.txt
+pylint.txt
 *.pyc
 dist/
-build/
-pyBrayns.egg-info/
+.tox/
+venv/
+doc/source/.ipynb_checkpoints/

python/MANIFEST.in

@@ -0,0 +1 @@
+include requirements*.txt

python/Makefile

@@ -0,0 +1,96 @@
+# Copyright (c) 2016-2018, Blue Brain Project
+#                          Raphael Dumusc <raphael.dumusc@epfl.ch>
+#                          Daniel Nachbaur <daniel.nachbaur@epfl.ch>
+#                          Cyrille Favreau <cyrille.favreau@epfl.ch>
+#
+# This file is part of Brayns <https://github.com/BlueBrain/Brayns>
+#
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License version 3.0 as published
+# by the Free Software Foundation.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+# All rights reserved. Do not distribute without further notice.
+
+ROOT_DIR := $(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
+
+#see if we're in a virtualenv, and use that, otherwise use the default
+ifdef VIRTUAL_ENV
+   VENV=$(VIRTUAL_ENV)
+else
+   VENV:=venv
+endif
+VENV_BIN:=$(VENV)/bin
+
+# simulate running in headless mode
+unexport DISPLAY
+
+# Test coverage pass threshold (percent)
+MIN_COV?=100
+VENV_INSTALLED=.installed
+PIP_INSTALL_OPTIONS=--ignore-installed
+
+FIND_LINT_PY=`find brayns -name "*.py" -not -path "*/*test*"`
+LINT_PYFILES := $(shell find $(FIND_LINT_PY))
+
+$(VENV):
+	virtualenv --system-site-packages $(VENV)
+
+$(VENV_INSTALLED): $(VENV)
+	$(VENV_BIN)/pip install --upgrade pip
+	$(VENV_BIN)/pip install $(PIP_INSTALL_OPTIONS) -r requirements_dev.txt
+	$(VENV_BIN)/pip install -e .
+	touch $@
+
+run_pycodestyle: $(VENV_INSTALLED)
+	$(VENV_BIN)/pycodestyle $(LINT_PYFILES) > pycodestyle.txt
+
+run_pydocstyle: $(VENV_INSTALLED)
+	$(VENV_BIN)/pydocstyle $(LINT_PYFILES) > pydocstyle.txt
+
+run_pylint: $(VENV_INSTALLED)
+	$(VENV_BIN)/pylint --rcfile=pylintrc --extension-pkg-whitelist=numpy $(LINT_PYFILES) > pylint.txt
+
+run_tests: $(VENV_INSTALLED)
+	$(VENV_BIN)/nosetests -v --with-coverage --cover-min-percentage=$(MIN_COV) --cover-erase --cover-package brayns
+
+run_tests_xunit: $(VENV_INSTALLED)
+	@mkdir -p $(ROOT_DIR)/test-reports
+	$(VENV_BIN)/nosetests brayns --with-coverage --cover-min-percentage=$(MIN_COV) --cover-inclusive --cover-erase --cover-package=brayns --with-xunit --xunit-file=test-reports/nosetests_brayns.xml
+
+lint: run_pycodestyle run_pydocstyle run_pylint
+
+test: lint run_tests
+
+doc: $(VENV_INSTALLED)
+	make SPHINXBUILD=$(VENV_BIN)/sphinx-build -C doc html
+
+doc_pdf: $(VENV_INSTALLED)
+	make SPHINXBUILD=$(VENV_BIN)/sphinx-build -C doc latexpdf
+
+clean_test_venv:
+	@rm -rf $(VENV_INSTALLED)
+	@rm -rf $(ROOT_DIR)/test-reports
+
+clean_doc:
+	@test -x $(VENV_BIN)/sphinx-build && make SPHINXBUILD=$(VENV_BIN)/sphinx-build  -C doc clean || true
+	@rm -rf $(ROOT_DIR)/doc/build
+
+clean: clean_doc clean_test_venv
+	@rm -f pycodestyle.txt
+	@rm -f pydocstyle.txt
+	@rm -f pylint.txt
+	@rm -rf brayns/brayns.egg-info
+	@rm -f .coverage
+	@rm -rf test-reports
+	@rm -rf dist
+	@rm -f $(VENV_INSTALLED)
+
+.PHONY: run_pycodestyle test clean_test_venv clean doc

python/README.md

@@ -0,0 +1,58 @@
+# Brayns
+
+The brayns package provides a python API to the brayns application.
+
+## Documentation
+
+Brayns documentation is built and hosted on [readthedocs](https://readthedocs.org/).
+
+* [latest snapshot](http://brayns.readthedocs.org/en/latest/)
+* [latest release](http://brayns.readthedocs.org/en/stable/)
+
+## Installation
+
+It is recommended that you use [`pip`](https://pip.pypa.io/en/stable/) to install
+`Brayns` into a [`virtualenv`](https://virtualenv.pypa.io/en/stable/). The following
+assumes a `virtualenv` named `venv` has been set up and
+activated. We will see three ways to install `Brayns`
+
+
+### 1. From the Python Package Index
+
+```
+(venv)$ pip install brayns
+```
+
+### 2. From git repository
+
+```
+(venv)$ pip install git+https://github.com/BlueBrain/Brayns.git#subdirectory=python
+```
+
+### 3. From source
+
+Clone the repository and install it:
+
+```
+(venv)$ git clone https://github.com/BlueBrain/Brayns.git
+(venv)$ pip install -e ./Brayns/python
+```
+
+This installs `Brayns` into your `virtualenv` in "editable" mode. That means changes
+made to the source code are seen by the installation. To install in read-only mode, omit
+the `-e`.
+
+## Connect to running Brayns instance
+
+```python
+>>> from brayns import Client
+
+>>> brayns = Client('localhost:8200')
+>>> print(brayns)
+Brayns version 0.7.0.c52dd4b running on http://localhost:8200/
+```
+
+## Examples
+
+Please find some examples how to interact with Brayns from python on
+[`Read the Docs`](https://brayns.readthedocs.io/en/latest/examples.html).

python/brayns/__init__.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2016-2018, Blue Brain Project
+#                          Raphael Dumusc <raphael.dumusc@epfl.ch>
+#                          Daniel Nachbaur <daniel.nachbaur@epfl.ch>
+#                          Cyrille Favreau <cyrille.favreau@epfl.ch>
+#
+# This file is part of Brayns <https://github.com/BlueBrain/Brayns>
+#
+# This library is free software; you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License version 3.0 as published
+# by the Free Software Foundation.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+# All rights reserved. Do not distribute without further notice.
+
+"""The Brayns python client library provides access to remote control a running Brayns instance."""
+
+from .client import Client
+from .rpcclient import RpcClient
+from .version import VERSION as __version__
+
+__all__ = ['Client', 'RpcClient']