# pyqode.core.backend

The backend package contains the API to use on the server side:
  - server + methods for running it
  - workers definitions

pyQode uses a client-server architecture for running heavy tasks such as code analysis (lint), code completion,...

## Protocol

We use a worker based json messaging server using the TCP/IP protocol.

We build our own, very simple protocoal where each message is made up of two parts:

> - a header: simply contains the length of the payload
> - a payload: a json formatted string, the content of the message.

The content of the json object depends on if this is a request or a response.

### Request

For a request, the object will contains the following fields:

> - ‘request_id’: uuid generated client side
> - ‘worker’: fully qualified name to the worker callable (class or function), e.g. ‘pyqode.core.backend.workers.echo_worker’
> - ‘data’: data specific to the chose worker.

E.g:

    {
        'request_id': 'a97285af-cc88-48a4-ac69-7459b9c7fa66',
        'worker': 'pyqode.core.backend.workers.echo_worker',
        'data': ['some code', 0]
    }

### Response

For a response, the object will contains the following fields:
  - ‘request_id’: uuid generated client side that is simply echoed back
  - ‘status’: worker status, boolean
  - ‘results’: worker results (list, tuple, string,...)

E.g:

    {
        'request_id': 'a97285af-cc88-48a4-ac69-7459b9c7fa66',
        'status': True,
        'results': ['some code', 0]
    }

#### Server script

The server script must be written by the user. Don’t worry, its very simple. All you have to do is to create and run a JsonTcpServer instance.

We choose to let you write the main script to let you easily configure it.

Some workers will requires some tweaking (for the completion worker, you will want to add custom completion providers, you might also want to modify sys.path,...). It also makes the packaging process more consistent, your script will be packaged on linux using setup.py and will be frozen on windows using cx_Freeze.

Here is the most simple and basic example of a server script:

Warning

The user can choose the python interpreter that will run the server. That means that classes and functions that run server side ( workers) should fully support python2 syntax and that pyqode.core should be installed on the target interpreter sys path!!! (even for a virtual env). An alternative is to keep pyqode.core package in a zip archive that you mount on the sys path in your server script.

Note

print statements on the server side will be logged as debug messages on the client side. To have your messages logged as error message, use sys.stderr instead of print.

exception `pyqode.core.backend.``NotConnected`

  Bases: `builtins.Exception`

  Raised if the client is not connected to the server when an operation is requested.

class `pyqode.core.backend.``JsonServer`(args=None)

  Bases: `socketserver.TCPServer`

  A server socket based on a json messaging system.

class `pyqode.core.backend.``CodeCompletionWorker`

  Bases: `builtins.object`

  This is the worker associated with the code completion mode.

  The worker does not actually do anything smart, the real work of collecting code completions is accomplished by the completion providers (see the `pyqode.core.backend.workers.CodeCompletionWorker.Provider` interface) listed in `pyqode.core.backend.workers.CompletionWorker.providers`.

  Completion providers must be installed on the CodeCompletionWorker at the beginning of the main server script, e.g.:

      from pyqode.core.backend import CodeCompletionWorker
      CodeCompletionWorker.providers.insert(0, MyProvider())

  class `Provider`

    Bases: `builtins.object`

    This class describes the expected interface for code completion providers.

    You can inherit from this class but this is not required as long as you implement a `complete` method which returns the list of completions and have the expected signature:

        def complete(self, code, line, column, path, encoding, prefix):
            pass

    `complete`(code, line, column, path, encoding, prefix)

      Returns a list of completions.

      A completion is dictionary with the following keys:

      > - ‘name’: name of the completion, this the text displayed and inserted when the user select a completion in the list
      > - ‘icon’: an optional icon file name
      > - ‘tooltip’: an optional tooltip string

      Parameters: | code – code string line – line number (1 based) column – column number (0 based) path – file path encoding – file encoding prefix – completion prefix (text before cursor)
      Returns: | A list of completion dicts as described above.
      Return type: | list

class `pyqode.core.backend.``DocumentWordsProvider`

  Bases: `builtins.object`

  Provides completions based on the document words

  `complete`(code, *args)

    Provides completions based on the document words.

  static `split`(txt, seps)

    Splits a text in a meaningful list of words based on a list of word separators (define in pyqode.core.settings)

    Parameters: | txt – Text to split seps – List of words separators
    Returns: | A set of words found in the document (excluding punctuations, numbers, ...)

`pyqode.core.backend.``default_parser`()

  Configures and return the default argument parser. You should use this parser as a base if you want to add custom arguments.

  The default parser only has one argument, the tcp port used to start the server socket. (CodeEdit picks up a free port and use it to run the server and connect its client socket)

  Returns: | The default server argument parser.

`pyqode.core.backend.``serve_forever`(args=None)

  Creates the server and serves forever

  Parameters: | args – Optional args if you decided to use your own argument parser. Default is None to let the JsonServer setup its own parser and parse command line arguments.

`pyqode.core.backend.``echo_worker`(data)

  Example of worker that simply echoes back the received data.

  Returns: | True, data