From 5fddc1e29ff94d02b1d80836d92d5902c30886a6 Mon Sep 17 00:00:00 2001 From: Ryan Barrett Date: Tue, 29 Aug 2023 11:59:30 -0700 Subject: [PATCH] release v0.3 --- README.md | 46 +++++++++++++++++++++---------------------- docs/conf.py | 4 ++-- docs/index.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++----- pyproject.toml | 4 ++-- 4 files changed, 75 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index c92b1cb..826f0f9 100644 --- a/README.md +++ b/README.md @@ -147,33 +147,33 @@ Here's how to package, test, and ship a new release. Test code to paste into the interpreter: ```py - from lexrpc import Server - - server = Server([{ - 'lexicon': 1, - 'id': 'io.example.ping', - 'defs': { - 'main': { - 'type': 'query', - 'description': 'Ping the server', - 'parameters': {'message': { 'type': 'string' }}, - 'output': { - 'encoding': 'application/json', - 'schema': { - 'type': 'object', - 'required': ['message'], - 'properties': {'message': { 'type': 'string' }}, - }, +from lexrpc import Server + +server = Server([{ + 'lexicon': 1, + 'id': 'io.example.ping', + 'defs': { + 'main': { + 'type': 'query', + 'description': 'Ping the server', + 'parameters': {'message': { 'type': 'string' }}, + 'output': { + 'encoding': 'application/json', + 'schema': { + 'type': 'object', + 'required': ['message'], + 'properties': {'message': { 'type': 'string' }}, }, }, }, - }]) + }, +}]) - @server.method('io.example.ping') - def ping(input, message=''): - return {'message': message} +@server.method('io.example.ping') +def ping(input, message=''): + return {'message': message} - print(server.call('io.example.ping', {}, message='hello world')) +print(server.call('io.example.ping', {}, message='hello world')) ``` 1. Tag the release in git. In the tag message editor, delete the generated comments at bottom, leave the first line blank (to omit the release "title" in github), put `### Notable changes` on the second line, then copy and paste this version's changelog contents below it. @@ -193,7 +193,7 @@ Here's how to package, test, and ship a new release. ## Changelog -### 0.3 - unreleased +### 0.3 - 2023-08-29 * Add array type support. * Add support for non-JSON input and output encodings. diff --git a/docs/conf.py b/docs/conf.py index e5f6a8f..0459451 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -87,9 +87,9 @@ # built documents. # # The short X.Y version. -version = '0.2' +version = '0.3' # The full version, including alpha/beta/rc tags. -release = '0.2' +release = '0.3' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/index.rst b/docs/index.rst index 8a6d692..6d711c6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,6 +45,17 @@ NSIDs to make calls, passing input as a dict and parameters as kwargs: Note that ``-`` characters in method NSIDs are converted to ``_``\ s, eg the call above is for the method ``com.example.my-query``. +`Event stream methods with type +``subscription `__ are +generators that ``yield`` (header, payload) tuples sent by the server. +They take parameters as kwargs, but no positional ``input``. + +:: + + for header, msg in client.com.example.count(start=1, end=10): + print(header['t']) + print(msg['num']) + Server ------ @@ -64,8 +75,8 @@ to call them, whether from your web framework or anywhere else. server = Server(lexicons) @server.method('com.example.my-query') - def my_query_hander(input, **params): - output = {'foo': input['foo'], 'b': params['param_a'] + 1} + def my_query(input, num=None): + output = {'foo': input['foo'], 'b': num + 1} return output # Extract nsid and decode query parameters from an HTTP request, @@ -76,6 +87,28 @@ to call them, whether from your web framework or anywhere else. output = server.call(nsid, input, **params) response.write_json(output) +You can also register a method handler with +`Server.register `__: + +:: + + server.register('com.example.my-query', my_query_handler) + +`Event stream methods with type +``subscription `__ should be +generators that ``yield`` frames to send to the client. `Each frame is a +``(header dict, payload dict)`` +tuple `__ that will be +DAG-CBOR encoded and sent to the websocket client. Subscription methods +take parameters as kwargs, but no positional ``input``. + +:: + + @server.method('com.example.count') + def count(start=None, end=None): + for num in range(start, end): + yield {'num': num} + Flask server ------------ @@ -126,8 +159,6 @@ TODO - `extensions `__. is there anything to do? ah, `they’re currently TODO in the spec `__. -- `“binary blob” support. `__ currently - undefined ish? is it based on the ``encoding`` field? - `authentication, currently TODO in the spec `__ @@ -251,6 +282,18 @@ Here’s how to package, test, and ship a new release. Changelog --------- +0.3 - 2023-08-29 +~~~~~~~~~~~~~~~~ + +- Add array type support. +- Add support for non-JSON input and output encodings. +- Add ``subscription`` method type support over websockets. +- Add ``headers`` kwarg to ``Client`` constructor. +- Add new ``Server.register`` method for manually registering handlers. +- Bug fix for server ``@method`` decorator. + +.. _section-1: + 0.2 - 2023-03-13 ~~~~~~~~~~~~~~~~ @@ -266,7 +309,7 @@ put more effort into matching and fully implementing them. Stay tuned! format `__. Original format is no longer supported. -.. _section-1: +.. _section-2: 0.1 - 2022-12-13 ~~~~~~~~~~~~~~~~ diff --git a/pyproject.toml b/pyproject.toml index 30bd372..e2f422e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -9,7 +9,7 @@ packages = ['lexrpc'] [project] name = 'lexrpc' -version = '0.2' +version = '0.3' authors = [ { name='Ryan Barrett', email='lexrpc@ryanb.org' }, ] @@ -18,6 +18,7 @@ readme = 'README.md' requires-python = '>=3.7' keywords = ['XRPC', 'Lexicon', 'AT Protocol', 'ATP'] dependencies = [ + 'dag-cbor', 'jsonschema>=4.0', 'requests>=2.0', 'simple-websocket', @@ -37,7 +38,6 @@ classifiers = [ [project.optional-dependencies] flask = [ - 'dag-cbor', 'Flask>=2.0', 'flask-sock', ]