rpcq
====
[](https://pypi.org/project/rpcq/)
[](https://anaconda.org/conda-forge/rpcq)
[](https://hub.docker.com/r/rigetti/rpcq)
The asynchronous RPC client-server framework and message specification for
[Rigetti Quantum Cloud Services (QCS)](https://www.rigetti.com/).
Implements an efficient transport protocol by using [ZeroMQ](http://zeromq.org/) (ZMQ) sockets and
[MessagePack](https://msgpack.org/index.html) (`msgpack`) serialization.
Not intended to be a full-featured replacement for other frameworks like
[gRPC](https://grpc.io/) or [Apache Thrift](https://thrift.apache.org/).
Python Installation
-------------------
To install directly from the source, run `pip install -e .` from within the top-level
directory of the `rpcq` repository. To additionally install the requirements for testing,
make sure to run `pip install -r requirements.txt`.
To instead install the latest released verson of `rpcq` from the Python package manager PyPi,
run `pip install rpcq`.
**NOTE**: We strongly encourage users of `rpcq` to install the software within a (Python)
virtual environment (read up on [`virtualenv`](https://github.com/pypa/virtualenv),
[`pyenv`](https://github.com/pyenv/pyenv), or [`conda`](https://github.com/conda/conda)
for more info).
Lisp Installation
-----------------
Installation is easier with QuickLisp. After placing the source for RPCQ within your local
Lisp projects directory (cf. `ql:*local-project-directories*`), run `(ql:quickload :rpcq)`
and QuickLisp will download the necessary Lisp dependencies.
In addition to the Lisp dependencies, RPCQ depends on ZeroMQ. Be sure to install both the
library *and* its development headers (which are necessary for the Lisp foreign-function
interface to get its bearings).
Using the Client-Server Framework
---------------------------------
The following two code samples (first in Python, then in Lisp) demonstrate how to create a server, add a test handler, and spin it up.
```python
from rpcq import Server
server = Server()
@server.rpc_handler
def test():
return 'test'
server.run('tcp://*:5555')
```
```lisp
(defun test ()
"test")
(let ((dt (rpcq:make-dispatch-table)))
(rpcq:dispatch-table-add-handler dt 'test)
(rpcq:start-server :dispatch-table dt
:listen-addresses '("tcp://*:5555")))
```
In another window, we can (again first in Python, then in Lisp) create a client that points to the same socket, and call the test method.
```python
from rpcq import Client
client = Client('tcp://localhost:5555')
client.call('test')
```
```lisp
(rpcq:with-rpc-client (client "tcp://localhost:5555")
(rpcq:rpc-call client "test"))
```
In all cases (including interoperating a client/server pair written in different languages), this will return the string `'test'`.
Using the Message Spec
----------------------
The message spec as defined in `src/messages.lisp` (which in turn produces `rpcq/messages.py`)
is meant to be used with the [Rigetti QCS](https://www.rigetti.com/qcs) platform. Therefore,
these messages are used in [`pyquil`](https://github.com/rigetticomputing/pyquil), in order
to allow users to communicate with the Rigetti Quil compiler and quantum processing units (QPUs).
PyQuil provides utilities for users to interact with the QCS API and write programs in
[Quil](https://arxiv.org/abs/1608.03355), the quantum instruction language developed at Rigetti.
Thus, most users will not interact with `rpcq.messages` directly. However, for those interested
in building their own implementation of the QCS API utilities in pyQuil, becoming acquainted
with the client-server framework, the available messages in the message spec, and how they
are used in the `pyquil.api` module would be a good place to start!
Updating the Python Message Bindings
------------------------------------
Currently only Python bindings are available for the message spec, but more language bindings
are in the works. To update the Python message bindings after editing `src/messages.lisp`,
open `rlwrap sbcl` and run:
```lisp
(ql:quickload :rpcq)
(with-open-file (f "rpcq/messages.py" :direction :output :if-exists :supersede)
(rpcq:python-message-spec f))
```
**NOTE**: Requires pre-installed
[`sbcl`](http://www.sbcl.org/),
[`quicklisp`](https://www.quicklisp.org/beta/), and
(optionally) [`rlwrap`](https://github.com/hanslub42/rlwrap).
We can also use the rpcq docker container to update the message spec without to install the
requirements.
```bash
./docker_update_python_spec.sh
```
Running the Unit Tests
----------------------
The `rpcq` repository is configured with GitLab CI to automatically run the unit tests.
The tests run within a container based off of the
[`rigetti/lisp`](https://hub.docker.com/r/rigetti/lisp) Docker image, which is pinned to a specific
tag. If you need a more recent version of the image, update the tag in the `.gitlab-ci.yml`.
The Python unit tests can be executed locally by running `pytest` from the top-level
directory of the repository (assuming you have installed the test requirements).
The Lisp unit tests can be run locally by doing the following from within `rlwrap sbcl`:
```lisp
(ql:quickload :rpcq)
(asdf:test-system :rpcq)
```
There may be some instances of `STYLE-WARNING`, but if the test run successfully,
there should be something near the bottom of the output that looks like:
```
RPCQ-TESTS (Suite)
TEST-DEFMESSAGE [ OK ]
```
Automated Packaging with Docker
-------------------------------
The CI pipeline for `rpcq` produces a Docker image, available at
[`rigetti/rpcq`](https://hub.docker.com/r/rigetti/rpcq). To get the latest stable
version of `rpcq`, run `docker pull rigetti/rpcq`. The image is built from the
[`rigetti/lisp`](https://hub.docker.com/r/rigetti/lisp) Docker image, which is pinned to a specific
tag. If you need a more recent version of the image, update the tag in the `Dockerfile`.
To learn more about the `rigetti/lisp` Docker image, check out the
[`docker-lisp`](https://github.com/rigetti/docker-lisp) repository.
Release Process
---------------
1. Update `VERSION.txt` and dependency versions (if applicable) and push the commit to `master`.
2. Push a git tag `vX.Y.Z` that contains the same version number as in `VERSION.txt`.
3. Verify that the resulting build (triggered by pushing the tag) completes successfully.
4. Push the tagged commit to `pypi` and verify it appears [here](https://pypi.org/project/rpcq/).
5. Publish a [release](https://github.com/rigetti/rpcq/releases) using the tag as the name.
6. Close the [milestone](https://github.com/rigetti/rpcq/milestones) associated with this release,
and migrate incomplete issues to the next one.
Authors
-------
Developed at [Rigetti Computing](https://github.com/rigetticomputing) by
[Nikolas Tezak](https://github.com/ntezak),
[Steven Heidel](https://github.com/stevenheidel),
[Eric Peterson](https://github.com/ecp-rigetti),
[Colm Ryan](https://github.com/caryan),
[Peter Karalekas](https://github.com/karalekas),
[Guen Prawiroatmodjo](https://github.com/guenp),
[Erik Davis](https://github.com/kilimanjaro), and
[Robert Smith](https://github.com/tarballs-are-good).
Raw data
{
"_id": null,
"home_page": "https://github.com/rigetticomputing/rpcq.git",
"name": "rpcq",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "quantum rpc qcs",
"author": "Rigetti Computing",
"author_email": "info@rigetti.com",
"download_url": "https://files.pythonhosted.org/packages/b3/02/6113b7dedf92169486d2ea000875000f54920cbf3887f90fd102aa061e83/rpcq-3.11.0.tar.gz",
"platform": null,
"description": "rpcq\n====\n\n[](https://pypi.org/project/rpcq/)\n[](https://anaconda.org/conda-forge/rpcq)\n[](https://hub.docker.com/r/rigetti/rpcq)\n\nThe asynchronous RPC client-server framework and message specification for\n[Rigetti Quantum Cloud Services (QCS)](https://www.rigetti.com/).\n\nImplements an efficient transport protocol by using [ZeroMQ](http://zeromq.org/) (ZMQ) sockets and\n[MessagePack](https://msgpack.org/index.html) (`msgpack`) serialization.\n\nNot intended to be a full-featured replacement for other frameworks like\n[gRPC](https://grpc.io/) or [Apache Thrift](https://thrift.apache.org/).\n\nPython Installation\n-------------------\n\nTo install directly from the source, run `pip install -e .` from within the top-level\ndirectory of the `rpcq` repository. To additionally install the requirements for testing,\nmake sure to run `pip install -r requirements.txt`.\n\nTo instead install the latest released verson of `rpcq` from the Python package manager PyPi,\nrun `pip install rpcq`.\n\n**NOTE**: We strongly encourage users of `rpcq` to install the software within a (Python)\nvirtual environment (read up on [`virtualenv`](https://github.com/pypa/virtualenv),\n[`pyenv`](https://github.com/pyenv/pyenv), or [`conda`](https://github.com/conda/conda)\nfor more info).\n\nLisp Installation\n-----------------\n\nInstallation is easier with QuickLisp. After placing the source for RPCQ within your local\nLisp projects directory (cf. `ql:*local-project-directories*`), run `(ql:quickload :rpcq)`\nand QuickLisp will download the necessary Lisp dependencies.\n\nIn addition to the Lisp dependencies, RPCQ depends on ZeroMQ. Be sure to install both the\nlibrary *and* its development headers (which are necessary for the Lisp foreign-function\ninterface to get its bearings).\n\nUsing the Client-Server Framework\n---------------------------------\n\nThe following two code samples (first in Python, then in Lisp) demonstrate how to create a server, add a test handler, and spin it up.\n\n```python\nfrom rpcq import Server\n\nserver = Server()\n\n@server.rpc_handler\ndef test():\n return 'test'\n\nserver.run('tcp://*:5555')\n```\n\n```lisp\n(defun test ()\n \"test\")\n\n(let ((dt (rpcq:make-dispatch-table)))\n (rpcq:dispatch-table-add-handler dt 'test)\n (rpcq:start-server :dispatch-table dt\n :listen-addresses '(\"tcp://*:5555\")))\n```\n\nIn another window, we can (again first in Python, then in Lisp) create a client that points to the same socket, and call the test method.\n\n```python\nfrom rpcq import Client\n\nclient = Client('tcp://localhost:5555')\n\nclient.call('test')\n```\n\n```lisp\n(rpcq:with-rpc-client (client \"tcp://localhost:5555\")\n (rpcq:rpc-call client \"test\"))\n```\n\nIn all cases (including interoperating a client/server pair written in different languages), this will return the string `'test'`.\n\nUsing the Message Spec\n----------------------\n\nThe message spec as defined in `src/messages.lisp` (which in turn produces `rpcq/messages.py`)\nis meant to be used with the [Rigetti QCS](https://www.rigetti.com/qcs) platform. Therefore,\nthese messages are used in [`pyquil`](https://github.com/rigetticomputing/pyquil), in order\nto allow users to communicate with the Rigetti Quil compiler and quantum processing units (QPUs).\nPyQuil provides utilities for users to interact with the QCS API and write programs in\n[Quil](https://arxiv.org/abs/1608.03355), the quantum instruction language developed at Rigetti.\n\nThus, most users will not interact with `rpcq.messages` directly. However, for those interested\nin building their own implementation of the QCS API utilities in pyQuil, becoming acquainted\nwith the client-server framework, the available messages in the message spec, and how they\nare used in the `pyquil.api` module would be a good place to start!\n\nUpdating the Python Message Bindings\n------------------------------------\n\nCurrently only Python bindings are available for the message spec, but more language bindings\nare in the works. To update the Python message bindings after editing `src/messages.lisp`,\nopen `rlwrap sbcl` and run:\n\n```lisp\n(ql:quickload :rpcq)\n(with-open-file (f \"rpcq/messages.py\" :direction :output :if-exists :supersede)\n (rpcq:python-message-spec f))\n```\n\n**NOTE**: Requires pre-installed\n[`sbcl`](http://www.sbcl.org/),\n[`quicklisp`](https://www.quicklisp.org/beta/), and\n(optionally) [`rlwrap`](https://github.com/hanslub42/rlwrap).\n\nWe can also use the rpcq docker container to update the message spec without to install the\nrequirements.\n\n```bash\n./docker_update_python_spec.sh\n```\n\nRunning the Unit Tests\n----------------------\n\nThe `rpcq` repository is configured with GitLab CI to automatically run the unit tests.\nThe tests run within a container based off of the\n[`rigetti/lisp`](https://hub.docker.com/r/rigetti/lisp) Docker image, which is pinned to a specific\ntag. If you need a more recent version of the image, update the tag in the `.gitlab-ci.yml`.\n\nThe Python unit tests can be executed locally by running `pytest` from the top-level\ndirectory of the repository (assuming you have installed the test requirements).\n\nThe Lisp unit tests can be run locally by doing the following from within `rlwrap sbcl`:\n\n```lisp\n(ql:quickload :rpcq)\n(asdf:test-system :rpcq)\n```\n\nThere may be some instances of `STYLE-WARNING`, but if the test run successfully,\nthere should be something near the bottom of the output that looks like:\n\n```\nRPCQ-TESTS (Suite)\n TEST-DEFMESSAGE [ OK ]\n```\n\nAutomated Packaging with Docker\n-------------------------------\n\nThe CI pipeline for `rpcq` produces a Docker image, available at\n[`rigetti/rpcq`](https://hub.docker.com/r/rigetti/rpcq). To get the latest stable\nversion of `rpcq`, run `docker pull rigetti/rpcq`. The image is built from the\n[`rigetti/lisp`](https://hub.docker.com/r/rigetti/lisp) Docker image, which is pinned to a specific\ntag. If you need a more recent version of the image, update the tag in the `Dockerfile`.\n\nTo learn more about the `rigetti/lisp` Docker image, check out the\n[`docker-lisp`](https://github.com/rigetti/docker-lisp) repository.\n\nRelease Process\n---------------\n\n1. Update `VERSION.txt` and dependency versions (if applicable) and push the commit to `master`.\n2. Push a git tag `vX.Y.Z` that contains the same version number as in `VERSION.txt`.\n3. Verify that the resulting build (triggered by pushing the tag) completes successfully.\n4. Push the tagged commit to `pypi` and verify it appears [here](https://pypi.org/project/rpcq/).\n5. Publish a [release](https://github.com/rigetti/rpcq/releases) using the tag as the name.\n6. Close the [milestone](https://github.com/rigetti/rpcq/milestones) associated with this release,\n and migrate incomplete issues to the next one.\n\nAuthors\n-------\n\nDeveloped at [Rigetti Computing](https://github.com/rigetticomputing) by\n[Nikolas Tezak](https://github.com/ntezak),\n[Steven Heidel](https://github.com/stevenheidel),\n[Eric Peterson](https://github.com/ecp-rigetti),\n[Colm Ryan](https://github.com/caryan),\n[Peter Karalekas](https://github.com/karalekas),\n[Guen Prawiroatmodjo](https://github.com/guenp),\n[Erik Davis](https://github.com/kilimanjaro), and\n[Robert Smith](https://github.com/tarballs-are-good).",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The RPC framework and message specification for Rigetti QCS.",
"version": "3.11.0",
"split_keywords": [
"quantum",
"rpc",
"qcs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b3026113b7dedf92169486d2ea000875000f54920cbf3887f90fd102aa061e83",
"md5": "4ed235583eb32a94625962bd9ac397e8",
"sha256": "4361e759782f58dd0b8aa3a6d901e3ea5709f91c6a060bd444081fbb007b05a9"
},
"downloads": -1,
"filename": "rpcq-3.11.0.tar.gz",
"has_sig": false,
"md5_digest": "4ed235583eb32a94625962bd9ac397e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 45589,
"upload_time": "2023-03-23T23:17:00",
"upload_time_iso_8601": "2023-03-23T23:17:00.325141Z",
"url": "https://files.pythonhosted.org/packages/b3/02/6113b7dedf92169486d2ea000875000f54920cbf3887f90fd102aa061e83/rpcq-3.11.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-23 23:17:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "rigetticomputing",
"github_project": "rpcq.git",
"lcname": "rpcq"
}
JSON
