remotecall 0.4.0

The module provides functionality to expose Python functions to be called remotely over ethernet.

Remotecall

The module provides functionality to expose Python functions to be called remotely over ethernet.

The implementation uses Python's http.server.HTTPServer to implement a server side functionality and Request for client implementation.

Getting started

Exposing a function to be called remotely.

Server

Create a server and expose a function.

    from remotecall import Server

    def hello() -> str:
        return "Hello World"

    with Server(("localhost", 8000)) as server:
        server.expose(hello)
        server.serve_forever()

Client

Subclass a client from BaseClient to call exposed functions.

    from remotecall import Server

    class Client(BaseClient):
        def hello(self) -> str:
            return self.call("hello")

    client = Client(("localhost", 8000))
    client.hello()

Code generation

Use the module to generate client code instead of writing the client code.

  python -m remotecall generate_client http://localhost:8000

Usage

Basic example

Server side implementation to expose hello() function:

    from remotecall import Server

    def hello() -> str:
        return "Hello World"

    with Server(server_address=("localhost", 8000)) as server:
        server.register(hello)
        server.serve_forever()

Client side implementation is based on BaseClient class which is a thin wrapper around Requests module.

    from remotecall import BaseClient

    client = BaseClient(server_address=("localhost", 8000))
    client.call("hello")

Subclassing BaseClient makes accessing the available functions more convenient - for example, by enabling IDE autocompletion and providing the type information.

    from remotecall import BaseClient

    class Client(BaseClient):
        def hello(self) -> str:
            return self.call("hello")

    client = Client(server_address=("localhost", 8000))
    client.hello()

Usage of python -m remotecall generate_client automates the client code generation.

For more example, see examples directory.

Passing arguments

Module uses Python type annotations to determine type of parameter and return values.

The type information is used to generate API definition. The API definition is provided in JSON format and can be used to generate client code.

The type information is also used to encode and decode data - like parameter and return values - send between client and server.

The implementation support basic Python data types including bytes, int, float, bool, str, list, tuple and dict. It is possible to add support for addition types. See examples directory for an implementation for PIL Images and NumPy arrays.

Server

Exposing a function with parameters and return value.

    def echo(message: str) -> str:
        return message

Client

Calling the function from the client side.

    class Client(BaseClient):
        def echo(self, message: str) -> str:
            return self.call("echo", message=message)

HTTPS and SSL

By default, the server uses HTTP for the communication. HTTPS communication can be enabled by providing SSL certificate. The certificate is used to create a SSLContext to wrap the underlying socket instance.

See examples folder for an example and instructions to generate a self-signed certificate.

Server

    server = Server(...)
    server.use_ssl(cert_file="server.crt", key_file="server.key")

Client

    client = BaseClient(...)
    client.use_ssl(cert_file="server.pem")

Authentication

By default, the server does not require authentication.

Server provides an implementation for HTTP basic authenticator that can be set in use as demonstrated below. However, it's also possible to subclass remotecall.authentication.Authenticator and implement other type of authenticators.

Client implementation wraps Requests library and makes it possible to use the authentication methods available for that library. More documentation can be found from the library documentation https://requests.readthedocs.io/en/latest/user/authentication/.

Server

    server = Server(...)
    server.set_authenticator(BasicAuthenticator("user", "pass"))

Client

    from requests.auth import HTTPBasicAuth

    client = BaseClient(...)
    client.set_authentication(HTTPBasicAuth("user", "pass"))

Implementing authenticator

Implementing a custom authenticator begins with subclassing remotecall.authentication. Authenticator.

Authenticator is expected to implement authenticate method to carry out the authentication. It is called right after the HTTP server's do_* method gets called.

authenticate method receives an instance of BaseHTTPRequestHandler that represents the HTTP request received by the HTTP server and to handle it.

Authenticator is expected to handle the actions required to carry out the authentication.

It may raise AuthenticationError if the server should not continue processing the request. Server expects the authenticator to resolves the request by sending the corresponding headers and related data.

class Authenticator(ABC):
    @abstractmethod
    def authenticate(self, request: BaseHTTPRequestHandler):
        """Do the authentication."""

Code generation

The module provides an easy way to generate a Python client for a service provided by a server.

The API definition can be fetched from the server with the following command line command. The command returns an API definition in JSON format.

    $ python -m remotecall fetch_api http://localhost:8000

For example, in case of echo example the output would be:

{
    "endpoints": [
        {
            "name": "echo",
            "documentation": "",
            "parameters": [
                {
                    "name": "message",
                    "type": "str"
                }
            ],
            "return_type": "str"
        }
    ],
    "ssl_enabled": false,
    "address": {
        "hostname": "localhost",
        "port": 8000
    }
}

The API definition can be written in a file with output option.

    $ python -m remotecall fetch_api http://localhost:8000 --output api.json

Client code can be generated based on the definition:

    $ python -m remotecall generate_client api.json --output client.py

Where, output defines the output file.

By default, the client class is named as Client. This can be changed by using name option. For example, --name EchoClient.

The above steps can be combined if the intermediate results are not needed.

    $ python -m remotecall generate_client http://localhost:8000 --output client.py

Extending supported data type

See examples/image and examples/numpy for image and numpy codec examples.

Development

Set up virtual environment

Create virtual environment:

python3 -m venv venv

Activate virtual environment:

source venv/bin/activate

Running from source

pip install -e .

Installing from source

pip install .
python -m remotecall

Running tests

pip install .[test]
pytest

py.test -s

Building

Creating a wheel

$ pip install wheel
$ python setup.py bdist_wheel