Jsonrpc.Client¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`error_quark` ()
class	`new` (io_stream)
	`call` (method, params, cancellable)
	`call_async` (method, params, cancellable, callback, *user_data)
	`call_finish` (result)
	`call_with_id_async` (method, params, cancellable, callback, *user_data)
	`close` (cancellable)
	`close_async` (cancellable, callback, *user_data)
	`close_finish` (result)
	`get_use_gvariant` ()
	`reply` (id, result, cancellable)
	`reply_async` (id, result, cancellable, callback, *user_data)
	`reply_error_async` (id, code, message, cancellable, callback, *user_data)
	`reply_error_finish` (result)
	`reply_finish` (result)
	`send_notification` (method, params, cancellable)
	`send_notification_async` (method, params, cancellable, callback, *user_data)
	`send_notification_finish` (result)
	`set_use_gvariant` (use_gvariant)
	`start_listening` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_failed` ()
	`do_handle_call` (method, id, params)
	`do_notification` (method_name, params)

Properties¶

Name	Type	Flags	Short Description
`io-stream`	`Gio.IOStream`	w/co	The stream to communicate over
`use-gvariant`	`bool`	r/w	If `GLib.Variant` encoding should be used

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`failed`	The “failed” signal is called when the client has failed communication or the connection has been knowingly closed.
`handle-call`	This signal is emitted when an RPC has been received from the peer we are connected to.
`notification`	This signal is emitted when a notification has been received from a peer.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class Jsonrpc.Client(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Jsonrpc.ClientClass

A client for JSON-RPC communication

The Jsonrpc.Client class provides a convenient API to coordinate with a JSON-RPC server. You can provide the underlying [class`Gio`.IOStream] to communicate with allowing you to control the negotiation of how you setup your communications channel. One such method might be to use a [class`Gio`.Subprocess] and communicate over stdin and stdout.

Because JSON-RPC allows for out-of-band notifications from the server to the client, it is important that the consumer of this API calls [method`Client`.close] or [method`Client`.close_async] when they no longer need the client. This is because Jsonrpc.Client contains an asynchronous read-loop to process incoming messages. Until [method`Client`.close] or [method`Client`.close_async] have been called, this read loop will prevent the object from finalizing (being freed).

To make an RPC call, use [method`Client`.call] or [method`Client`.call_async] and provide the method name and the parameters as a [struct`GLib`.Variant] for call.

It is a programming error to mix synchronous and asynchronous API calls of the Jsonrpc.Client class.

For synchronous calls, Jsonrpc.Client will use the thread-default [struct`GLib`.MainContext]. If you have special needs here ensure you’ve set the context before calling into any Jsonrpc.Client API.

New in version 3.26.

classmethod error_quark()¶

Return type:: int

classmethod new(io_stream)¶

Parameters:: io_stream (Gio.IOStream) – A [class`Gio`.IOStream]
Returns:: A newly created Jsonrpc.Client
Return type:: Jsonrpc.Client

Creates a new Jsonrpc.Client instance.

If you want to communicate with a process using stdin/stdout, consider using [class`Gio`.Subprocess] to launch the process and create a [class`Gio`.SimpleIOStream] using the [method`Gio`.Subprocess.get_stdin_pipe] and [method`Gio`.Subprocess.get_stdout_pipe].

New in version 3.26.

call(method, params, cancellable)¶

Parameters:

method (str) – The name of the method to call
params (GLib.Variant or None) – A [struct`GLib`.Variant] of parameters or None
cancellable (Gio.Cancellable or None) – A Gio.Cancellable or None

Raises:

GLib.Error

Returns:

True on success; otherwise False and error is set.

return_value:: A location for a [struct`GLib`.Variant]

Return type:

(bool, return_value: GLib.Variant or None)

Synchronously calls method with params on the remote peer.

once a reply has been received, or failure, this function will return. If successful, return_value will be set with the reslut field of the response.

If params is floating then this function consumes the reference.

New in version 3.26.

call_async(method, params, cancellable, callback, *user_data)¶

Parameters:

method (str) – The name of the method to call
params (GLib.Variant or None) – A [struct`GLib`.Variant] of parameters or None
cancellable (Gio.Cancellable or None) – A Gio.Cancellable or None
callback (Gio.AsyncReadyCallback or None) – a callback to executed upon completion
user_data (object or None) – user data for callback

Asynchronously calls method with params on the remote peer.

Upon completion or failure, callback is executed and it should call [method`Client`.call_finish] to complete the request and release any memory held.

If params is floating, the floating reference is consumed.

New in version 3.26.

call_finish(result)¶

Parameters:

result (Gio.AsyncResult) – A Gio.AsyncResult provided to the callback in [method`Client`.call_async]

Raises:

GLib.Error

Returns:

True if successful and return_value is set, otherwise False and error is set.

return_value:: A location for a [struct`GLib`.Variant] or None

Return type:

(bool, return_value: GLib.Variant or None)

Completes an asynchronous call to [method`Client`.call_async].

New in version 3.26.

call_with_id_async(method, params, cancellable, callback, *user_data)¶

Parameters:

method (str) – The name of the method to call
params (GLib.Variant or None) – A [struct`GLib`.Variant] of parameters or None
cancellable (Gio.Cancellable or None) – A Gio.Cancellable or None
callback (Gio.AsyncReadyCallback or None) – Callback to executed upon completion
user_data (object or None) – User data for callback

Returns:

A location for a [struct`GLib`.Variant] describing the identifier used for the method call, or None.

Return type:

id: GLib.Variant

Asynchronously calls method with params on the remote peer.

Upon completion or failure, callback is executed and it should call [method`Client`.call_finish] to complete the request and release any memory held.

This function is similar to [method`Client`.call_async] except that it allows the caller to get the id of the command which might be useful in systems where you can cancel the operation (such as the Language Server Protocol).

If params is floating, the floating reference is consumed.

New in version 3.30.

close(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) –
Raises:: GLib.Error
Returns:: True if successful; otherwise False and error is set.
Return type:: bool

Closes the underlying streams and cancels any inflight operations of the Jsonrpc.Client.

This is important to call when you are done with the client so that any outstanding operations that have caused self to hold additional references are cancelled.

Failure to call this method results in a leak of Jsonrpc.Client.

New in version 3.26.

close_async(cancellable, callback, *user_data)¶

Parameters:

cancellable (Gio.Cancellable or None) –
callback (Gio.AsyncReadyCallback or None) –
user_data (object or None) –

Asynchronous version of [method`Client`.close].

Currently this operation is implemented synchronously, but in the future may be converted to using asynchronous operations.

New in version 3.26.

close_finish(result)¶

Parameters:: result (Gio.AsyncResult) –
Raises:: GLib.Error
Returns:: True if successful; otherwise False and error is set.
Return type:: bool

Completes an asynchronous request of [method`Client`.close_async].

New in version 3.26.

get_use_gvariant()¶

Returns:: True if [struct`GLib`.Variant] is being used; otherwise False.
Return type:: bool

Gets the [property`Client`:py:data::use-gvariant<Jsonrpc.Client.props.use_gvariant>] property.

Indicates if [struct`GLib`.Variant] is being used to communicate with the peer.

New in version 3.26.

reply(id, result, cancellable)¶

Parameters:

id (GLib.Variant) – The id of the message to reply
result (GLib.Variant or None) – The return value or None
cancellable (Gio.Cancellable or None) – A Gio.Cancellable, or None

Raises:

GLib.Error

Return type:

bool

Synchronous variant of [method`Client`.reply_async].

If id or result are floating, there floating references are consumed.

New in version 3.26.

reply_async(id, result, cancellable, callback, *user_data)¶

Parameters:

id (GLib.Variant) –
result (GLib.Variant) –
cancellable (Gio.Cancellable or None) –
callback (Gio.AsyncReadyCallback or None) –
user_data (object or None) –

reply_error_async(id, code, message, cancellable, callback, *user_data)¶

Parameters:

id (GLib.Variant) – A [struct`GLib`.Variant] containing the call id
code (int) – The error code
message (str or None) – An optional error message
cancellable (Gio.Cancellable or None) – A Gio.Cancellable, or None
callback (Gio.AsyncReadyCallback or None) – A Gio.AsyncReadyCallback or None
user_data (object or None) – Closure data for callback

Asynchronously replies to the peer, sending a JSON-RPC error message.

Call [method`Client`.reply_error_finish] to get the result of this operation.

If id is floating, it’s floating reference is consumed.

New in version 3.28.

reply_error_finish(result)¶

Parameters:: result (Gio.AsyncResult) –
Raises:: GLib.Error
Return type:: bool

reply_finish(result)¶

Parameters:: result (Gio.AsyncResult) – A Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if successful; otherwise False and error is set.
Return type:: bool

Completes an asynchronous request to [method`Client`.reply_async].

New in version 3.26.

send_notification(method, params, cancellable)¶

Parameters:

method (str) – The name of the method to call
params (GLib.Variant or None) – A [struct`GLib`.Variant] of parameters or None
cancellable (Gio.Cancellable or None) – A Gio.Cancellable or None

Raises:

GLib.Error

Returns:

True on success; otherwise False and error is set.

Return type:

bool

Synchronously calls method with params on the remote peer.

This function will not wait or expect a reply from the peer.

If params is floating then the reference is consumed.

New in version 3.26.

send_notification_async(method, params, cancellable, callback, *user_data)¶

Parameters:

method (str) – The name of the method to call
params (GLib.Variant or None) – A [struct`GLib`.Variant] of parameters or None
cancellable (Gio.Cancellable or None) – A Gio.Cancellable or None
callback (Gio.AsyncReadyCallback or None) –
user_data (object or None) –

Asynchronously calls method with params on the remote peer.

This function will not wait or expect a reply from the peer.

This function is useful when the caller wants to be notified that the bytes have been delivered to the underlying stream. This does not indicate that the peer has received them.

If params is floating then the reference is consumed.

New in version 3.26.

send_notification_finish(result)¶

Parameters:: result (Gio.AsyncResult) –
Raises:: GLib.Error
Returns:: True if the bytes have been flushed to the [class`Gio`.IOStream]; otherwise False and error is set.
Return type:: bool

Completes an asynchronous call to [method`Client`.send_notification_async].

Successful completion of this function only indicates that the request has been written to the underlying buffer, not that the peer has received the notification.

New in version 3.26.

set_use_gvariant(use_gvariant)¶

Parameters:: use_gvariant (bool) – If [struct`GLib`.Variant] should be used

Sets the [property`Client`:py:data::use-gvariant<Jsonrpc.Client.props.use_gvariant>] property.

This function sets if [struct`GLib`.Variant] should be used to communicate with the peer. Doing so can allow for more efficient communication by avoiding expensive parsing overhead and memory allocations. However, it requires that the peer also supports [struct`GLib`.Variant] encoding.

New in version 3.26.

start_listening()¶: This function requests that client start processing incoming messages from the peer.

New in version 3.26.

do_failed() virtual¶

do_handle_call(method, id, params) virtual¶

Parameters:

method (str) –
id (GLib.Variant) –
params (GLib.Variant) –

Return type:

bool

do_notification(method_name, params) virtual¶

Parameters:

method_name (str) –
params (GLib.Variant) –

Signal Details¶

Jsonrpc.Client.signals.failed(client)¶

Signal Name:: failed
Flags:: RUN_LAST
Parameters:: client (Jsonrpc.Client) – The object which received the signal

The “failed” signal is called when the client has failed communication or the connection has been knowingly closed.

New in version 3.28.

Jsonrpc.Client.signals.handle_call(client, method, id, params)¶

Signal Name:

handle-call

Flags:

RUN_LAST, DETAILED

Parameters:

client (Jsonrpc.Client) – The object which received the signal
method (str) – The method name
id (GLib.Variant) – The “id” field of the JSONRPC message
params (GLib.Variant or None) – The “params” field of the JSONRPC message

Return type:

bool

This signal is emitted when an RPC has been received from the peer we are connected to. Return True if you have handled this message, even asynchronously. If no handler has returned True an error will be synthesized.

If you handle the message, you are responsible for replying to the peer in a timely manner using [method`Client`.reply] or [method`Client`.reply_async].

Additionally, since 3.28 you may connect to the “detail” of this signal to handle a specific method call. Use the method name as the detail of the signal.

New in version 3.26.

Jsonrpc.Client.signals.notification(client, method, params)¶

Signal Name:

notification

Flags:

RUN_LAST, DETAILED

Parameters:

client (Jsonrpc.Client) – The object which received the signal
method (str) – The method name of the notification
params (GLib.Variant or None) – Params for the notification

This signal is emitted when a notification has been received from a peer. Unlike [signal`Client`:py:func:::handle-call<Jsonrpc.Client.signals.handle_call>], this does not have an “id” parameter because notifications do not have ids. They do not round trip.

New in version 3.26.

Property Details¶

Jsonrpc.Client.props.io_stream¶

Name:: io-stream
Type:: Gio.IOStream
Default Value:: None
Flags:: WRITABLE, CONSTRUCT_ONLY

The “io-stream” property is the [class`Gio`.IOStream] to use for communicating with a JSON-RPC peer.

New in version 3.26.

Jsonrpc.Client.props.use_gvariant¶

Name:: use-gvariant
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

The “use-gvariant” property denotes if [struct`GLib`.Variant] should be used to communicate with the peer instead of JSON. You should only set this if you know the peer is also a Jsonrpc-GLib based client.

Setting this property allows the peers to communicate using GLib.Variant instead of JSON. This means that we can access the messages without expensive memory allocations and parsing costs associated with JSON. [struct`GLib`.Variant] is much more optimal for memory-bassed message passing.

New in version 3.26.