Contents

Low Level Python API

Low Level Python API

Module: terragen_rpc.jsonrpc

terragen_rpc.jsonrpc.call(method, params=[])

Generate an RPC query string, send it to the Terragen RPC server and return a Reply object.

Raises

  • ConnectionError – Raised by socket if a connection error occurs.

  • TimeoutError – Raised by impl.send_string() if a socket timeout occurs.

  • ReplyError – Raised if the response from the server cannot be decoded and parsed.

  • ApiError (subclass thererof) – Raised if the reply from the server contains an error code that suggests an API mismatch between client and server or an incorrect use of the API.

  • LowLevelError (subclass thereof) – Raised if the reply from the server contains an error code that suggests a problem with its implementation, or if this module encounters an internal error.

terragen_rpc.jsonrpc.call_with_invalid_json()

Test the RPC server with deliberately invalid JSON and attempt to return a Reply object, which should raise an exception.

Raises

  • ConnectionError – Raised by socket if a connection error occurs.

  • TimeoutError – Raised by impl.send_string() if a socket timeout occurs.

  • ReplyError – Raised if the response from the server cannot be decoded and parsed.

  • LowLevelParseError – Raised if the connection is successful and the server responds correctly to unparseable JSON with error code -32700.

terragen_rpc.jsonrpc.call_with_invalid_request()

Test the RPC server with a deliberately invalid request and attempt to return a Reply object, which should raise an exception.

Raises

  • ConnectionError – Raised by socket if a connection error occurs.

  • TimeoutError – Raised by impl.send_string() if a socket timeout occurs.

  • ReplyError – Raised if the response from the server cannot be decoded and parsed.

  • LowLevelInvalidRequest – Raised if the connection is successful and the server responds correctly to an invalid request with error code -32600.

Exceptions

We think that in production it’s appropriate to handle at least ConnectionError and TimeoutError (the built-in Python exceptiona) and terragen_rpc.ReplyError. These indicate issues that might be resolvable by the user at runtime, for example by restarting the server (Terragen) or resolving a network issue. A handler for these exceptions should give the user the opportunity to resolve them.

These and other exceptions are documented below.

Base Class

exception terragen_rpc.jsonrpc.Error(reply, msg='')

Base class for exceptions raised when an RPC call fails after making a successful connection.

Has subclasses including ReplyError, ApiError and LowLevelError.

reply

The Reply object being created when the exception was raised.

Type

Reply

Main Exceptions

exception terragen_rpc.jsonrpc.ReplyError(reply, msg='Terragen RPC server responded with data that cannot be parsed.')

An exception raised when the server responds with data that could not be parsed. We recommend that you catch and handle this exception.

A subclass of Error.

reply

The Reply object being created when the exception was raised.

Type

Reply

exception terragen_rpc.jsonrpc.ApiError(reply)

An exception raised when the reply from the server contains an error code that suggests an API mismatch between client and server or an incorrect use of the API. We recommend that you catch and handle this exception.

A subclass of Error.

Has subclasses including ApiInvalidParams and ApiMethodNotFound.

reply

The Reply object being created when the exception was raised.

Type

Reply

exception terragen_rpc.jsonrpc.LowLevelError(reply)

An exception raised when the reply from the server contains an error code that suggests a problem with its implementation, or when this module encounters an internal error.

A subclass of Error.

Has subclasses including LowLevelParseError, LowLevelInvalidRequest, LowLevelInternalError and LowLevelServerError.

reply

The Reply object being created when the exception was raised.

Type

Reply

Subclasses

The following exceptions are subclasses of the main exception classes above. It is not expected that you catch these directly.

exception terragen_rpc.jsonrpc.ApiMethodNotFound(reply)

An exception raised when the server responds with JSON-RPC error code -32601.

A subclass of ApiError.

reply

The Reply object being created when the exception was raised.

Type

Reply

exception terragen_rpc.jsonrpc.ApiInvalidParams(reply)

An exception raised when the server responds with JSON-RPC error code -32602.

A subclass of ApiError.

reply

The Reply object being created when the exception was raised.

Type

Reply

exception terragen_rpc.jsonrpc.LowLevelParseError(reply)

An exception raised when the server responds with JSON-RPC error code -32700.

A subclass of LowLevelError.

reply

The Reply object being created when the exception was raised.

Type

Reply

exception terragen_rpc.jsonrpc.LowLevelInvalidRequest(reply)

An exception raised when the server responds with JSON-RPC error code -32600.

A subclass of LowLevelError.

reply

The Reply object being created when the exception was raised.

Type

Reply

exception terragen_rpc.jsonrpc.LowLevelInternalError(reply)

A subclass of LowLevelError.

reply

The Reply object being created when the exception was raised.

Type

Reply

exception terragen_rpc.jsonrpc.LowLevelServerError(reply)

An exception raised when the server responds with a JSON-RPC error code between -32099 and -32000.

A subclass of LowLevelError.

reply

The Reply object being created when the exception was raised.

Type

Reply

Reply Class

class terragen_rpc.jsonrpc.Reply(reply_bytes, method, params)

Data returned by low-level RPC calls, which may include error info.

Raises

  • ReplyError – Raised if the response from the server cannot be decoded and parsed.

  • ApiError (subclass thererof) – Raised if the reply from the server contains an error code that suggests an API mismatch between client and server or an incorrect use of the API.

  • LowLevelError (subclass thereof) – Raised if the reply from the server contains an error code that suggests a problem with its implementation, or if this module encounters an internal error.

ok

Whether the call was successful.

Type

bool

value

If ok is True, value is the main value of interest, whose type depends on the function that was called. Should be equal to raw_dict['result'].

jsonrpc_error_code

An error code returned by the server if the response was parsed. It is either the error code returned by the server or -32603 for an internal error. It is expected to follow the JSON-RPC 2.0 specification (https://www.jsonrpc.org/specification). Possible values include: -32700 (Parse error); -32600 (Invalid Request); -32601 (Method not found); -32602 (Invalid params); -32603 (Internal error); -32000 to -32099 (Server error).

Type

int

jsonrpc_error_msg

An error message returned by the server if the response was parsed, or ‘Internal error’ if the response was not parsed, or None if no error occurred. If not None it is expected to follow the JSON-RPC 2.0 specification (https://www.jsonrpc.org/specification). Possible values include: ‘Parse error’; ‘Invalid Request’; ‘Method not found’; ‘Invalid params’; ‘Internal error’; ‘Server error’.

Type

str or None

more_error_info

May be a string with more information about an error, or may be None.

Type

str or None

raw_bytes

The byte array returned by the server, which is expected to conform to JSON-RPC 2.0 protocol. Not normally needed, but could be useful for debugging.

Type

byte array

raw_dict

A dictionary representation of the JSON object returned by the server. Not normally needed, but could be useful for debugging.

Type

dict

previous

High Level Python API

next

Download/Install