Server

Misc

JSON-RPC server package.

class pjrpc.server.AsyncDispatcher(*, request_class=<class 'pjrpc.common.v20.Request'>, response_class=<class 'pjrpc.common.v20.Response'>, batch_request=<class 'pjrpc.common.v20.BatchRequest'>, batch_response=<class 'pjrpc.common.v20.BatchResponse'>, json_loader=<function loads>, json_dumper=<function dumps>, json_encoder=<class 'pjrpc.server.dispatcher.JSONEncoder'>, json_decoder=None, middlewares=(), error_handlers={})

Bases: BaseDispatcher

Asynchronous method dispatcher.

Parameters:

• request_class (Type[Request]) –

• response_class (Type[Response]) –

• batch_request (Type[BatchRequest]) –

• batch_response (Type[BatchResponse]) –

• json_loader (Callable[[...], Any]) –

• json_dumper (Callable[[...], str]) –

• json_encoder (Type[JSONEncoder]) –

• json_decoder (Optional[Type[JSONDecoder]]) –

• middlewares (Iterable[AsyncMiddlewareType]) –

• error_handlers (Dict[Union[None, int, Exception], List[AsyncErrorHandlerType]]) –

async dispatch(request_text, context=None)

Deserializes request, dispatches it to the required method and serializes the result.

Parameters:

• request_text (str) – request text representation

• context (Optional[Any]) – application context (if supported)

Returns:

response text representation

Return type:

Optional[str]

class pjrpc.server.BaseDispatcher(*, request_class=<class 'pjrpc.common.v20.Request'>, response_class=<class 'pjrpc.common.v20.Response'>, batch_request=<class 'pjrpc.common.v20.BatchRequest'>, batch_response=<class 'pjrpc.common.v20.BatchResponse'>, json_loader=<function loads>, json_dumper=<function dumps>, json_encoder=<class 'pjrpc.server.dispatcher.JSONEncoder'>, json_decoder=None, middlewares=(), error_handlers={})

Bases: object

Method dispatcher.

Parameters:

• request_class (Type[Request]) – JSON-RPC request class

• response_class (Type[Response]) – JSON-RPC response class

• batch_request (Type[BatchRequest]) – JSON-RPC batch request class

• batch_response (Type[BatchResponse]) – JSON-RPC batch response class

• json_loader (Callable[[...], Any]) – request json loader

• json_dumper (Callable[[...], str]) – response json dumper

• json_encoder (Type[JSONEncoder]) – response json encoder

• json_decoder (Optional[Type[JSONDecoder]]) – request json decoder

• middlewares (Iterable[Callable[[...], Any]]) – request middlewares

• error_handlers (Dict[Union[None, int, Exception], List[Callable[[...], Any]]]) – request error handlers

add(method, name=None, context=None)

Adds method to the registry.

Parameters:

• method (Callable[[...], Any]) – method

• name (Optional[str]) – method name

• context (Optional[Any]) – application context name

Return type:

None

add_methods(*methods)

Adds methods to the registry.

Parameters:

methods (Union[MethodRegistry, Method, Callable[[...], Any]]) – method list. Each method may be an instance of pjrpc.server.MethodRegistry, pjrpc.server.Method or plain function

Return type:

None

view(view)

Adds class based view to the registry.

Parameters:

view (Type[ViewMixin]) – view to be added

Return type:

None

class pjrpc.server.Dispatcher(*, request_class=<class 'pjrpc.common.v20.Request'>, response_class=<class 'pjrpc.common.v20.Response'>, batch_request=<class 'pjrpc.common.v20.BatchRequest'>, batch_response=<class 'pjrpc.common.v20.BatchResponse'>, json_loader=<function loads>, json_dumper=<function dumps>, json_encoder=<class 'pjrpc.server.dispatcher.JSONEncoder'>, json_decoder=None, middlewares=(), error_handlers={})

Bases: BaseDispatcher

Synchronous method dispatcher.

Parameters:

• request_class (Type[Request]) –

• response_class (Type[Response]) –

• batch_request (Type[BatchRequest]) –

• batch_response (Type[BatchResponse]) –

• json_loader (Callable[[...], Any]) –

• json_dumper (Callable[[...], str]) –

• json_encoder (Type[JSONEncoder]) –

• json_decoder (Optional[Type[JSONDecoder]]) –

• middlewares (Iterable[MiddlewareType]) –

• error_handlers (Dict[Union[None, int, Exception], List[ErrorHandlerType]]) –

dispatch(request_text, context=None)

Deserializes request, dispatches it to the required method and serializes the result.

Parameters:

• request_text (str) – request text representation

• context (Optional[Any]) – application context (if supported)

Returns:

response text representation

Return type:

Optional[str]

class pjrpc.server.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Server JSON encoder. All custom server encoders should be inherited from it.

default(o)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

Parameters:

o (Any) –

Return type:

Any

class pjrpc.server.Method(method, name=None, context=None)

Bases: object

JSON-RPC method wrapper. Stores method itself and some metainformation.

Parameters:

• method (Callable[[...], Any]) – method

• name (Optional[str]) – method name

• context (Optional[str]) – context name

class pjrpc.server.MethodRegistry(prefix=None)

Bases: object

Method registry.

Parameters:

prefix (Optional[str]) – method name prefix to be used for naming containing methods

get(item)

Returns a method from the registry by name.

Parameters:

item (str) – method name

Returns:

found method or None

Return type:

Optional[Method]

add(maybe_method=None, name=None, context=None)

Decorator adding decorated method to the registry.

Parameters:

• maybe_method (Optional[Callable[[...], Any]]) – method or None

• name (Optional[str]) – method name to be used instead of __name__ attribute

• context (Optional[Any]) – parameter name to be used as an application context

Returns:

decorated method or decorator

Return type:

Callable[[…], Any]

add_methods(*methods)

Adds methods to the registry.

Parameters:

methods (Union[Callable[[...], Any], Method]) – methods to be added. Each one can be an instance of pjrpc.server.Method or plain method

Return type:

None

view(maybe_view=None, context=None, prefix=None)

Methods view decorator.

Parameters:

• maybe_view (Optional[Type[ViewMixin]]) – view class instance or None

• context (Optional[Any]) – application context name

• prefix (Optional[str]) – view methods prefix

Returns:

decorator or decorated view

Return type:

Union[ViewMixin, Callable[[…], Any]]

merge(other)

Merges two registries.

Parameters:

other (MethodRegistry) – registry to be merged in the current one

Return type:

None

class pjrpc.server.ViewMixin(context=None)

Bases: object

Simple class based method handler mixin. Exposes all public methods.

Parameters:

context (Optional[Any]) –

Types

pjrpc.server.typedefs.AsyncErrorHandlerType

Asynchronous server error handler

alias of Callable[[Request, Optional[Any], JsonRpcError], Awaitable[JsonRpcError]]

pjrpc.server.typedefs.AsyncMiddlewareType

Asynchronous middleware type

alias of Callable[[Request, Optional[Any], Callable[[Request, Optional[Any]], Awaitable[Union[UnsetType, Response]]]], Awaitable[Union[UnsetType, Response]]]

pjrpc.server.typedefs.AsyncHandlerType

Async RPC handler method, passed to middlewares

alias of Callable[[Request, Optional[Any]], Awaitable[Union[UnsetType, Response]]]

pjrpc.server.typedefs.MiddlewareResponse

middlewares and handlers return Response or UnsetType

alias of Union[UnsetType, Response]

pjrpc.server.typedefs.MiddlewareType

Synchronous middleware type

alias of Callable[[Request, Optional[Any], Callable[[Request, Optional[Any]], Union[UnsetType, Response]]], Union[UnsetType, Response]]

pjrpc.server.typedefs.ErrorHandlerType

Synchronous server error handler

alias of Callable[[Request, Optional[Any], JsonRpcError], JsonRpcError]

pjrpc.server.typedefs.ResponseOrUnset

Return value of RPC handlers and middlewares

alias of Union[UnsetType, Response]

pjrpc.server.typedefs.ContextType

Context argument for RPC methods and middlewares

alias of Optional[Any]

Integrations

aiohttp

aiohttp JSON-RPC server integration.

class pjrpc.server.integration.aiohttp.Application(path='', spec=None, app=None, **kwargs)

Bases: object

aiohttp based JSON-RPC server.

Parameters:

• path (str) – JSON-RPC handler base path

• app_args – arguments to be passed to aiohttp.web.Application

• kwargs (Any) – arguments to be passed to the dispatcher pjrpc.server.AsyncDispatcher

• spec (Optional[Specification]) –

• app (Optional[Application]) –

property app: Application

aiohttp application.

property dispatcher: AsyncDispatcher

JSON-RPC method dispatcher.

property endpoints: Mapping[str, AsyncDispatcher]

JSON-RPC application registered endpoints.

add_endpoint(prefix, subapp=None, **kwargs)

Adds additional endpoint.

Parameters:

• prefix (str) – endpoint prefix

• subapp (Optional[Application]) – aiohttp subapp the endpoint will be served on

• kwargs (Any) – arguments to be passed to the dispatcher pjrpc.server.Dispatcher

Returns:

dispatcher

Return type:

AsyncDispatcher

flask

Flask JSON-RPC extension.

class pjrpc.server.integration.flask.JsonRPC(path, spec=None, **kwargs)

Bases: object

Flask framework JSON-RPC extension class.

Parameters:

• path (str) – JSON-RPC handler base path

• spec (Optional[Specification]) – JSON-RPC specification

• kwargs (Any) – arguments to be passed to the dispatcher pjrpc.server.Dispatcher

property dispatcher: Dispatcher

JSON-RPC method dispatcher.

property endpoints: Dict[str, Dispatcher]

JSON-RPC application registered endpoints.

add_endpoint(prefix, blueprint=None, **kwargs)

Adds additional endpoint.

Parameters:

• prefix (str) – endpoint prefix

• blueprint (Optional[Blueprint]) – flask blueprint the endpoint will be served on

• kwargs (Any) – arguments to be passed to the dispatcher pjrpc.server.Dispatcher

Returns:

dispatcher

Return type:

Dispatcher

init_app(app)

Initializes flask application with JSON-RPC extension.

Parameters:

app (Union[Flask, Blueprint]) – flask application instance

Return type:

None

kombu

kombu JSON-RPC server integration.

class pjrpc.server.integration.kombu.Executor(broker_url, queue_name, conn_args=None, queue_args=None, publish_args=None, prefetch_count=0, **kwargs)

Bases: ConsumerProducerMixin

kombu based JSON-RPC server.

Parameters:

• broker_url (str) – broker connection url

• queue_name (str) – requests queue name

• conn_args (Optional[Dict[str, Any]]) – additional connection arguments

• queue_args (Optional[Dict[str, Any]]) – queue arguments

• publish_args (Optional[Dict[str, Any]]) – message publish additional arguments

• prefetch_count (int) – worker prefetch count

• kwargs (Any) – dispatcher additional arguments

property dispatcher: Dispatcher

JSON-RPC method dispatcher.

aio_pika

class pjrpc.server.integration.aio_pika.Executor(broker_url, rx_queue_name, tx_exchange_name=None, tx_routing_key=None, prefetch_count=0, **kwargs)

Bases: object

aio_pika based JSON-RPC server.

Parameters:

• broker_url (URL) – broker connection url

• rx_queue_name (str) – requests queue name

• tx_exchange_name (str) – response exchange name

• tx_routing_key (str) – response routing key

• prefetch_count (int) – worker prefetch count

• kwargs (Any) – dispatcher additional arguments

property dispatcher: AsyncDispatcher

JSON-RPC method dispatcher.

async start(queue_args=None, exchange_args=None)

Starts executor.

Parameters:

• queue_args (Optional[Dict[str, Any]]) – queue arguments

• exchange_args (Optional[Dict[str, Any]]) – exchange arguments

Return type:

None

async shutdown()

Stops executor.

Return type:

None

werkzeug

class pjrpc.server.integration.werkzeug.JsonRPC(path='', **kwargs)

Bases: object

werkzeug server JSON-RPC integration.

Parameters:

• path (str) – JSON-RPC handler base path

• kwargs (Any) – arguments to be passed to the dispatcher pjrpc.server.Dispatcher

property dispatcher: Dispatcher

JSON-RPC method dispatcher.

Validators

JSON-RPC method parameters validators.

class pjrpc.server.validators.BaseValidator

Bases: object

Base method parameters validator. Uses inspect.signature() for validation.

validate(maybe_method=None, **kwargs)

Decorator marks a method the parameters of which to be validated when calling it using JSON-RPC protocol.

Parameters:

• maybe_method (Optional[Callable[[...], Any]]) – method the parameters of which to be validated or None if called as @validate(…)

• kwargs (Any) – validator arguments

Return type:

Callable[[…], Any]

validate_method(method, params, exclude=(), **kwargs)

Validates params against method signature.

Parameters:

• method (Callable[[...], Any]) – method to validate parameters against

• params (Optional[Union[List[Any], Tuple[Any, ...], Dict[str, Any]]]) – parameters to be validated

• exclude (Iterable[str]) – parameter names to be excluded from validation

• kwargs (Any) – additional validator arguments

Raises:

pjrpc.server.validators.ValidationError

Returns:

bound method parameters

Return type:

Dict[str, Any]

bind(signature, params)

Binds parameters to method. :param signature: method to bind parameters to :param params: parameters to be bound

Raises:

ValidationError is parameters binding failed

Returns:

bound parameters

Parameters:

• signature (Signature) –

• params (Optional[Union[List[Any], Tuple[Any, ...], Dict[str, Any]]]) –

Return type:

BoundArguments

signature(method, exclude)

Returns method signature.

Parameters:

• method (Callable[[...], Any]) – method to get signature of

• exclude (Tuple[str]) – parameters to be excluded

Returns:

signature

Return type:

Signature

exception pjrpc.server.validators.ValidationError

Bases: Exception

Method parameters validation error. Raised when parameters validation failed.

jsonschema

class pjrpc.server.validators.jsonschema.JsonSchemaValidator(**kwargs)

Bases: BaseValidator

Parameters validator based on jsonschema library.

Parameters:

kwargs (Any) – default jsonschema validator arguments

validate_method(method, params, exclude=(), **kwargs)

Validates params against method using pydantic validator.

Parameters:

• method (Callable[[...], Any]) – method to validate parameters against

• params (Optional[Union[List[Any], Tuple[Any, ...], Dict[str, Any]]]) – parameters to be validated

• exclude (Iterable[str]) – parameter names to be excluded from validation

• kwargs (Any) – jsonschema validator arguments

Raises:

pjrpc.server.validators.ValidationError

Return type:

Dict[str, Any]

pydantic

class pjrpc.server.validators.pydantic.PydanticValidator(coerce=True, **config_args)

Bases: BaseValidator

Parameters validator based on pydantic library. Uses python type annotations for parameters validation.

Parameters:

• coerce (bool) – if True returns converted (coerced) parameters according to parameter type annotation otherwise returns parameters as is

• config_args (Any) –

validate_method(method, params, exclude=(), **kwargs)

Validates params against method using pydantic validator.

Parameters:

• method (Callable[[...], Any]) – method to validate parameters against

• params (Optional[Union[List[Any], Tuple[Any, ...], Dict[str, Any]]]) – parameters to be validated

• exclude (Iterable[str]) – parameter names to be excluded from validation

• kwargs (Any) –

Returns:

coerced parameters if coerce flag is True otherwise parameters as is

Raises:

ValidationError

Return type:

Dict[str, Any]

build_validation_schema(signature)

Builds pydantic model based validation schema from method signature.

Parameters:

signature (Signature) – method signature to build schema for

Returns:

validation schema

Return type:

Dict[str, Any]

Specification

class pjrpc.server.specs.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Schema JSON encoder.

default(o)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

Parameters:

o (Any) –

Return type:

Any

class pjrpc.server.specs.BaseUI

Bases: ABC

Base UI.

abstract get_static_folder()

Returns ui statics folder.

Return type:

str

abstract get_index_page(spec_url)

Returns ui index webpage.

Parameters:

spec_url (str) – specification url.

Return type:

str

class pjrpc.server.specs.Specification(path='/spec.json', ui=None, ui_path=None)

Bases: ABC

JSON-RPC specification.

Parameters:

• path (str) – specification url path suffix

• ui (Optional[BaseUI]) – specification ui instance

• ui_path (Optional[str]) – specification ui url path suffix

property path: str

Returns specification url path.

property ui: Optional[BaseUI]

Returns ui instance.

property ui_path: Optional[str]

Returns specification ui url path.

abstract schema(path, methods=(), methods_map={})

Returns specification schema.

Parameters:

• path (str) – methods endpoint path

• methods (Iterable[Method]) – methods list the specification is generated for

• methods_map (Mapping[str, Iterable[Method]]) – methods map the specification is generated for. Each item is a mapping from a prefix to methods on which the methods will be served

Return type:

Dict[str, Any]

extractors

class pjrpc.server.specs.extractors.Schema(schema, required=True, summary=UNSET, description=UNSET, deprecated=UNSET, definitions=UNSET)

Bases: object

Method parameter/result schema.

Parameters:

• schema (Dict[str, Any]) –

• required (bool) –

• summary (Union[UnsetType, str]) –

• description (Union[UnsetType, str]) –

• deprecated (Union[UnsetType, bool]) –

• definitions (Union[UnsetType, Dict[str, Any]]) –

class pjrpc.server.specs.extractors.Example(params, result, version='2.0', summary=UNSET, description=UNSET)

Bases: object

Method usage example.

Parameters:

• params (Dict[str, Any]) –

• result (Any) –

• version (str) –

• summary (Union[UnsetType, str]) –

• description (Union[UnsetType, str]) –

class pjrpc.server.specs.extractors.ErrorExample(code, message, data=UNSET, summary=UNSET, description=UNSET)

Bases: object

Method error example.

Parameters:

• code (int) –

• message (str) –

• data (Optional[Union[UnsetType, Any]]) –

• summary (Union[UnsetType, str]) –

• description (Union[UnsetType, str]) –

class pjrpc.server.specs.extractors.Tag(name, description=UNSET, externalDocs=UNSET)

Bases: object

A list of method tags.

Parameters:

• name (str) –

• description (Union[UnsetType, str]) –

• externalDocs (Union[UnsetType, str]) –

class pjrpc.server.specs.extractors.Error(code, message, data=UNSET, data_required=UNSET, title=UNSET, description=UNSET, deprecated=UNSET, definitions=UNSET)

Bases: object

Defines an application level error.

Parameters:

• code (int) –

• message (str) –

• data (Union[UnsetType, Dict[str, Any]]) –

• data_required (Union[UnsetType, bool]) –

• title (Union[UnsetType, str]) –

• description (Union[UnsetType, str]) –

• deprecated (Union[UnsetType, bool]) –

• definitions (Union[UnsetType, Dict[str, Any]]) –

class pjrpc.server.specs.extractors.BaseSchemaExtractor

Bases: object

Base method schema extractor.

extract_params_schema(method, exclude=())

Extracts method parameters schema.

Parameters:

• method (Callable[[...], Any]) –

• exclude (Iterable[str]) –

Return type:

Dict[str, Schema]

extract_result_schema(method)

Extracts method result schema.

Parameters:

method (Callable[[...], Any]) –

Return type:

Schema

extract_description(method)

Extracts method description.

Parameters:

method (Callable[[...], Any]) –

Return type:

Union[UnsetType, str]

extract_summary(method)

Extracts method summary.

Parameters:

method (Callable[[...], Any]) –

Return type:

Union[UnsetType, str]

extract_errors_schema(method, errors=None)

Extracts method errors schema.

Parameters:

• method (Callable[[...], Any]) –

• errors (Optional[Iterable[Type[JsonRpcError]]]) –

Return type:

Union[UnsetType, List[Error]]

extract_tags(method)

Extracts method tags.

Parameters:

method (Callable[[...], Any]) –

Return type:

Union[UnsetType, List[Tag]]

extract_examples(method)

Extracts method usage examples.

Parameters:

method (Callable[[...], Any]) –

Return type:

Union[UnsetType, List[Example]]

extract_error_examples(method, errors=None)

Extracts method error examples.

Parameters:

• method (Callable[[...], Any]) –

• errors (Optional[Iterable[Type[JsonRpcError]]]) –

Return type:

Union[UnsetType, List[ErrorExample]]

extract_deprecation_status(method)

Extracts method deprecation status.

Parameters:

method (Callable[[...], Any]) –

Return type:

Union[UnsetType, bool]

class pjrpc.server.specs.extractors.pydantic.PydanticSchemaExtractor(ref_template='#/components/schemas/{model}')

Bases: BaseSchemaExtractor

Pydantic method specification extractor.

Parameters:

ref_template (str) –

extract_params_schema(method, exclude=())

Extracts method parameters schema.

Parameters:

• method (Callable[[...], Any]) –

• exclude (Iterable[str]) –

Return type:

Dict[str, Schema]

extract_result_schema(method)

Extracts method result schema.

Parameters:

method (Callable[[...], Any]) –

Return type:

Schema

extract_errors_schema(method, errors=None)

Extracts method errors schema.

Parameters:

• method (Callable[[...], Any]) –

• errors (Optional[Iterable[Type[JsonRpcError]]]) –

Return type:

Union[UnsetType, List[Error]]

schemas

OpenAPI Specification generator. See https://swagger.io/specification/.

class pjrpc.server.specs.openapi.Contact(name=UNSET, url=UNSET, email=UNSET)

Bases: object

Contact information for the exposed API.

Parameters:

• name (Union[UnsetType, str]) – the identifying name of the contact person/organization

• url (Union[UnsetType, str]) – the URL pointing to the contact information

• email (Union[UnsetType, str]) – the email address of the contact person/organization

class pjrpc.server.specs.openapi.License(name, url=UNSET)

Bases: object

License information for the exposed API.

Parameters:

• name (str) – the license name used for the API

• url (Union[UnsetType, str]) – a URL to the license used for the API

class pjrpc.server.specs.openapi.Info(title, version, description=UNSET, contact=UNSET, license=UNSET, termsOfService=UNSET)

Bases: object

Metadata about the API.

Parameters:

• title (str) – the title of the application

• version (str) – the version of the OpenAPI document

• description (Union[UnsetType, str]) – a short description of the application

• contact (Union[UnsetType, Contact]) – the contact information for the exposed API

• license (Union[UnsetType, License]) – the license information for the exposed API

• termsOfService (Union[UnsetType, str]) – a URL to the Terms of Service for the API

class pjrpc.server.specs.openapi.ServerVariable(default, enum=UNSET, description=UNSET)

Bases: object

An object representing a Server Variable for server URL template substitution.

Parameters:

• default (str) – the default value to use for substitution, which SHALL be sent if an alternate value is not supplied

• enum (Union[UnsetType, List[str]]) – an enumeration of string values to be used if the substitution options are from a limited set

• description (Union[UnsetType, str]) – an optional description for the server variable

class pjrpc.server.specs.openapi.Server(url, description=UNSET, variables=UNSET)

Bases: object

Connectivity information of a target server.

Parameters:

• url (str) – a URL to the target host

• description (Union[UnsetType, str]) – an optional string describing the host designated by the URL

• variables (Union[UnsetType, Dict[str, ServerVariable]]) –

class pjrpc.server.specs.openapi.ExternalDocumentation(url, description=UNSET)

Bases: object

Allows referencing an external resource for extended documentation.

Parameters:

• url (str) – a short description of the target documentation.

• description (Union[UnsetType, str]) – the URL for the target documentation

class pjrpc.server.specs.openapi.Tag(name, description=UNSET, externalDocs=UNSET)

Bases: object

A list of tags for API documentation control. Tags can be used for logical grouping of methods by resources or any other qualifier.

Parameters:

• name (str) – the name of the tag

• externalDocs (Union[UnsetType, ExternalDocumentation]) – additional external documentation for this tag

• description (Union[UnsetType, str]) – a short description for the tag

class pjrpc.server.specs.openapi.SecuritySchemeType(value)

Bases: str, Enum

The type of the security scheme.

class pjrpc.server.specs.openapi.ApiKeyLocation(value)

Bases: str, Enum

The location of the API key.

class pjrpc.server.specs.openapi.OAuthFlow(authorizationUrl, tokenUrl, scopes, refreshUrl=UNSET)

Bases: object

Configuration details for a supported OAuth Flow.

Parameters:

• authorizationUrl (str) – the authorization URL to be used for this flow

• tokenUrl (str) – the token URL to be used for this flow

• refreshUrl (Union[UnsetType, str]) – the URL to be used for obtaining refresh tokens

• scopes (Dict[str, str]) – the available scopes for the OAuth2 security scheme

class pjrpc.server.specs.openapi.OAuthFlows(implicit=UNSET, password=UNSET, clientCredentials=UNSET, authorizationCode=UNSET)

Bases: object

Configuration of the supported OAuth Flows.

Parameters:

• implicit (Union[UnsetType, OAuthFlow]) – configuration for the OAuth Implicit flow

• password (Union[UnsetType, OAuthFlow]) – configuration for the OAuth Resource Owner Password flow

• clientCredentials (Union[UnsetType, OAuthFlow]) – configuration for the OAuth Client Credentials flow

• authorizationCode (Union[UnsetType, OAuthFlow]) – configuration for the OAuth Authorization Code flow

class pjrpc.server.specs.openapi.SecurityScheme(type, scheme, name=UNSET, location=UNSET, bearerFormat=UNSET, flows=UNSET, openIdConnectUrl=UNSET, description=UNSET)

Bases: object

Defines a security scheme that can be used by the operations.

Parameters:

• type (SecuritySchemeType) – the type of the security scheme

• name (Union[UnsetType, str]) – the name of the header, query or cookie parameter to be used

• location (Union[UnsetType, ApiKeyLocation]) – the location of the API key

• scheme (str) – the name of the HTTP Authorization scheme to be used in the Authorization header

• bearerFormat (Union[UnsetType, str]) – a hint to the client to identify how the bearer token is formatted

• flows (Union[UnsetType, OAuthFlows]) – an object containing configuration information for the flow types supported

• openIdConnectUrl (Union[UnsetType, str]) –

• description (Union[UnsetType, str]) – a short description for security scheme

class pjrpc.server.specs.openapi.Components(securitySchemes=UNSET, schemas=<factory>)

Bases: object

Holds a set of reusable objects for different aspects of the OAS.

Parameters:

• securitySchemes (Union[UnsetType, Dict[str, SecurityScheme]]) – an object to hold reusable Security Scheme Objects

• schemas (Dict[str, Dict[str, Any]]) – the definition of input and output data types

class pjrpc.server.specs.openapi.MethodExample(params, result, version='2.0', summary=UNSET, description=UNSET)

Bases: object

Method usage example.

Parameters:

• params (Dict[str, Any]) – example parameters

• result (Any) – example result

• name – name for the example pairing

• summary (Union[UnsetType, str]) – short description for the example pairing

• description (Union[UnsetType, str]) – a verbose explanation of the example pairing

• version (str) –

class pjrpc.server.specs.openapi.ExampleObject(value, summary=UNSET, description=UNSET, externalValue=UNSET)

Bases: object

Method usage example.

Parameters:

• value (Any) – embedded literal example

• summary (Union[UnsetType, str]) – short description for the example.

• description (Union[UnsetType, str]) – long description for the example

• externalValue (Union[UnsetType, str]) – a URL that points to the literal example

class pjrpc.server.specs.openapi.MediaType(schema, examples=UNSET)

Bases: object

Each Media Type Object provides schema and examples for the media type identified by its key.

Parameters:

• schema (Dict[str, Any]) – the schema defining the content.

• example – example of the media type

• examples (Union[UnsetType, Dict[str, ExampleObject]]) –

class pjrpc.server.specs.openapi.Response(description, content=UNSET)

Bases: object

A container for the expected responses of an operation.

Parameters:

• description (str) – a short description of the response

• content (Union[UnsetType, Dict[str, MediaType]]) – a map containing descriptions of potential response payloads

class pjrpc.server.specs.openapi.RequestBody(content, required=UNSET, description=UNSET)

Bases: object

Describes a single request body.

Parameters:

• content (Dict[str, MediaType]) – the content of the request body

• required (Union[UnsetType, bool]) – determines if the request body is required in the request

• description (Union[UnsetType, str]) – a brief description of the request body

class pjrpc.server.specs.openapi.ParameterLocation(value)

Bases: str, Enum

The location of the parameter.

class pjrpc.server.specs.openapi.StyleType(value)

Bases: str, Enum

Describes how the parameter value will be serialized depending on the type of the parameter value.

class pjrpc.server.specs.openapi.Parameter(name, location, description=UNSET, required=UNSET, deprecated=UNSET, allowEmptyValue=UNSET, style=UNSET, explode=UNSET, allowReserved=UNSET, schema=UNSET, examples=UNSET, content=UNSET)

Bases: object

Describes a single operation parameter.

Parameters:

• name (str) – the name of the parameter

• location (ParameterLocation) – the location of the parameter

• description (Union[UnsetType, str]) – a brief description of the parameter

• required (Union[UnsetType, bool]) – determines whether this parameter is mandatory

• deprecated (Union[UnsetType, bool]) – a parameter is deprecated and SHOULD be transitioned out of usage

• allowEmptyValue (Union[UnsetType, bool]) – the ability to pass empty-valued parameters

• style (Union[UnsetType, StyleType]) – describes how the parameter value will be serialized depending on the type of the parameter value

• explode (Union[UnsetType, bool]) – when this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map

• allowReserved (Union[UnsetType, bool]) – determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&’()*+,;= to be included without percent-encoding

• schema (Union[UnsetType, Dict[str, Any]]) – the schema defining the type used for the parameter.

• examples (Union[UnsetType, Dict[str, ExampleObject]]) – examples of the parameter’s potential value

• content (Union[UnsetType, Dict[str, MediaType]]) – a map containing the representations for the parameter

class pjrpc.server.specs.openapi.Operation(responses, requestBody=UNSET, tags=UNSET, summary=UNSET, description=UNSET, externalDocs=UNSET, deprecated=UNSET, servers=UNSET, security=UNSET, parameters=UNSET)

Bases: object

Describes a single API operation on a path.

Parameters:

• tags (Union[UnsetType, List[str]]) – a list of tags for API documentation control

• summary (Union[UnsetType, str]) – a short summary of what the operation does

• description (Union[UnsetType, str]) – a verbose explanation of the operation behavior

• externalDocs (Union[UnsetType, ExternalDocumentation]) – additional external documentation for this operation

• requestBody (Union[UnsetType, RequestBody]) – the request body applicable for this operation

• responses (Dict[str, Response]) – the list of possible responses as they are returned from executing this operation

• deprecated (Union[UnsetType, bool]) – declares this operation to be deprecated

• servers (Union[UnsetType, List[Server]]) – an alternative server array to service this operation

• security (Union[UnsetType, List[Dict[str, List[str]]]]) – a declaration of which security mechanisms can be used for this operation

• parameters (Union[UnsetType, List[Parameter]]) –

class pjrpc.server.specs.openapi.Path(get=UNSET, put=UNSET, post=UNSET, delete=UNSET, options=UNSET, head=UNSET, patch=UNSET, trace=UNSET, summary=UNSET, description=UNSET, servers=UNSET)

Bases: object

Describes the interface for the given method name.

Parameters:

• summary (Union[UnsetType, str]) – an optional, string summary, intended to apply to all operations in this path

• description (Union[UnsetType, str]) – an optional, string description, intended to apply to all operations in this path

• servers (Union[UnsetType, List[Server]]) – an alternative server array to service all operations in this path

• get (Union[UnsetType, Operation]) –

• put (Union[UnsetType, Operation]) –

• post (Union[UnsetType, Operation]) –

• delete (Union[UnsetType, Operation]) –

• options (Union[UnsetType, Operation]) –

• head (Union[UnsetType, Operation]) –

• patch (Union[UnsetType, Operation]) –

• trace (Union[UnsetType, Operation]) –

pjrpc.server.specs.openapi.annotate(params_schema=UNSET, result_schema=UNSET, errors_schema=UNSET, errors=UNSET, examples=UNSET, error_examples=UNSET, tags=UNSET, summary=UNSET, description=UNSET, external_docs=UNSET, deprecated=UNSET, security=UNSET, parameters=UNSET)

Adds Open Api specification annotation to the method.

Parameters:

• params_schema (Union[UnsetType, Dict[str, Schema]]) – method parameters JSON schema

• result_schema (Union[UnsetType, Schema]) – method result JSON schema

• errors_schema (Union[UnsetType, List[Error]]) – method errors schema

• errors (Union[UnsetType, List[Type[JsonRpcError]]]) – method errors

• examples (Union[UnsetType, List[MethodExample]]) – method usage examples

• error_examples (Union[UnsetType, List[ErrorExample]]) – method error examples

• tags (Union[UnsetType, List[str]]) – a list of tags for method documentation control

• summary (Union[UnsetType, str]) – a short summary of what the method does

• description (Union[UnsetType, str]) – a verbose explanation of the method behavior

• external_docs (Union[UnsetType, ExternalDocumentation]) – an external resource for extended documentation

• deprecated (Union[UnsetType, bool]) – declares this method to be deprecated

• security (Union[UnsetType, List[Dict[str, List[str]]]]) – a declaration of which security mechanisms can be used for the method

• parameters (Union[UnsetType, List[Parameter]]) – a list of parameters that are applicable for the method

Return type:

Callable[[Func], Func]

class pjrpc.server.specs.openapi.OpenAPI(info, path='/openapi.json', servers=UNSET, external_docs=UNSET, tags=UNSET, security=UNSET, security_schemes=UNSET, openapi='3.0.0', schema_extractor=None, schema_extractors=(), ui=None, ui_path='/ui/')

Bases: Specification

OpenAPI Specification.

Parameters:

• info (Info) – provides metadata about the API

• servers (Union[UnsetType, List[Server]]) – an array of Server Objects, which provide connectivity information to a target server

• external_docs (Union[UnsetType, ExternalDocumentation]) – additional external documentation

• openapi (str) – the semantic version number of the OpenAPI Specification version that the OpenAPI document uses

• tags (Union[UnsetType, List[Tag]]) – a list of tags used by the specification with additional metadata

• security (Union[UnsetType, List[Dict[str, List[str]]]]) – a declaration of which security mechanisms can be used across the API

• schema_extractor (Optional[BaseSchemaExtractor]) – method specification extractor

• schema_extractors (Iterable[BaseSchemaExtractor]) – method specification extractors. Extractors results will be merged in reverse order (former extractor rewrites the result of the later one)

• path (str) – specification url path

• security_schemes (Union[UnsetType, Dict[str, SecurityScheme]]) – an object to hold reusable Security Scheme Objects

• ui (Optional[BaseUI]) – web ui instance

• ui_path (str) – wet ui path

schema(path, methods=(), methods_map={})

Returns specification schema.

Parameters:

• path (str) – methods endpoint path

• methods (Iterable[Method]) – methods list the specification is generated for

• methods_map (Mapping[str, Iterable[Method]]) – methods map the specification is generated for. Each item is a mapping from a prefix to methods on which the methods will be served

Return type:

Dict[str, Any]

class pjrpc.server.specs.openapi.SwaggerUI(**configs)

Bases: BaseUI

Swagger UI.

Parameters:

• config – documentation configurations (see https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md).

• configs (Any) –

get_static_folder()

Returns ui statics folder.

Return type:

str

get_index_page(spec_url)

Returns ui index webpage.

Parameters:

spec_url (str) – specification url.

Return type:

str

class pjrpc.server.specs.openapi.RapiDoc(**configs)

Bases: BaseUI

RapiDoc UI.

Parameters:

• config – documentation configurations (see https://mrin9.github.io/RapiDoc/api.html). Be aware that configuration parameters should be in snake case, for example: parameter heading-text should be passed as heading_text)

• configs (Any) –

get_static_folder()

Returns ui statics folder.

Return type:

str

get_index_page(spec_url)

Returns ui index webpage.

Parameters:

spec_url (str) – specification url.

Return type:

str

class pjrpc.server.specs.openapi.ReDoc(**configs)

Bases: BaseUI

ReDoc UI.

Parameters:

• config – documentation configurations (see https://github.com/Redocly/redoc#configuration). Be aware that configuration parameters should be in snake case, for example: parameter heading-text should be passed as heading_text)

• configs (Any) –

get_static_folder()

Returns ui statics folder.

Return type:

str

get_index_page(spec_url)

Returns ui index webpage.

Parameters:

spec_url (str) – specification url.

Return type:

str

OpenRPC specification generator. See https://spec.open-rpc.org/.

class pjrpc.server.specs.openrpc.Contact(name=UNSET, url=UNSET, email=UNSET)

Bases: object

Contact information for the exposed API.

Parameters:

• name (Union[UnsetType, str]) – the identifying name of the contact person/organization

• url (Union[UnsetType, str]) – the URL pointing to the contact information

• email (Union[UnsetType, str]) – the email address of the contact person/organization

class pjrpc.server.specs.openrpc.License(name, url=UNSET)

Bases: object

License information for the exposed API.

Parameters:

• name (str) – the license name used for the API

• url (Union[UnsetType, str]) – a URL to the license used for the API

class pjrpc.server.specs.openrpc.Info(title, version, description=UNSET, contact=UNSET, license=UNSET, termsOfService=UNSET)

Bases: object

Metadata about the API.

Parameters:

• title (str) – the title of the application

• version (str) – the version of the OpenRPC document

• description (Union[UnsetType, str]) – a verbose description of the application

• contact (Union[UnsetType, Contact]) – the contact information for the exposed API

• license (Union[UnsetType, License]) – the license information for the exposed API

• termsOfService (Union[UnsetType, str]) – a URL to the Terms of Service for the API

class pjrpc.server.specs.openrpc.Server(name, url, summary=UNSET, description=UNSET)

Bases: object

Connectivity information of a target server.

Parameters:

• name (str) – a name to be used as the canonical name for the server.

• url (str) – a URL to the target host

• summary (Union[UnsetType, str]) – a short summary of what the server is

• description (Union[UnsetType, str]) – an optional string describing the host designated by the URL

class pjrpc.server.specs.openrpc.ExternalDocumentation(url, description=UNSET)

Bases: object

Allows referencing an external resource for extended documentation.

Parameters:

• url (str) – A verbose explanation of the target documentation

• description (Union[UnsetType, str]) – The URL for the target documentation. Value MUST be in the format of a URL

class pjrpc.server.specs.openrpc.Tag(name, summary=UNSET, description=UNSET, externalDocs=UNSET)

Bases: object

A list of tags for API documentation control. Tags can be used for logical grouping of methods by resources or any other qualifier.

Parameters:

• name (str) – the name of the tag

• summary (Union[UnsetType, str]) – a short summary of the tag

• description (Union[UnsetType, str]) – a verbose explanation for the tag

• externalDocs (Union[UnsetType, ExternalDocumentation]) – additional external documentation for this tag

class pjrpc.server.specs.openrpc.ExampleObject(value, name, summary=UNSET, description=UNSET)

Bases: object

The ExampleObject object is an object the defines an example.

Parameters:

• value (Optional[Union[str, int, float, dict, bool, list, tuple, set]]) – embedded literal example

• name (str) – canonical name of the example

• summary (Union[UnsetType, str]) – short description for the example

• description (Union[UnsetType, str]) – a verbose explanation of the example

class pjrpc.server.specs.openrpc.MethodExample(name, params, result, summary=UNSET, description=UNSET)

Bases: object

The example Pairing object consists of a set of example params and result.

Parameters:

• params (List[ExampleObject]) – example parameters

• result (ExampleObject) – example result

• name (str) – name for the example pairing

• summary (Union[UnsetType, str]) – short description for the example pairing

• description (Union[UnsetType, str]) – a verbose explanation of the example pairing

class pjrpc.server.specs.openrpc.ContentDescriptor(name, schema, summary=UNSET, description=UNSET, required=UNSET, deprecated=UNSET)

Bases: object

Content Descriptors are objects that describe content. They are reusable ways of describing either parameters or result.

Parameters:

• name (str) – name of the content that is being described

• schema (Dict[str, Any]) – schema that describes the content. The Schema Objects MUST follow the specifications outline in the JSON Schema Specification 7 (https://json-schema.org/draft-07/json-schema-release-notes.html)

• summary (Union[UnsetType, str]) – a short summary of the content that is being described

• description (Union[UnsetType, str]) – a verbose explanation of the content descriptor behavior

• required (Union[UnsetType, bool]) – determines if the content is a required field

• deprecated (Union[UnsetType, bool]) – specifies that the content is deprecated and SHOULD be transitioned out of usage

class pjrpc.server.specs.openrpc.Error(code, message, data=UNSET)

Bases: object

Defines an application level error.

Parameters:

• code (int) – a Number that indicates the error type that occurred

• message (str) – a String providing a short description of the error

• data (Union[UnsetType, Dict[str, Any]]) – a Primitive or Structured value that contains additional information about the error

class pjrpc.server.specs.openrpc.ParamStructure(value)

Bases: str, Enum

The expected format of the parameters.

class pjrpc.server.specs.openrpc.MethodInfo(name, params, result, errors=UNSET, paramStructure=UNSET, examples=UNSET, summary=UNSET, description=UNSET, tags=UNSET, deprecated=UNSET, externalDocs=UNSET, servers=UNSET)

Bases: object

Describes the interface for the given method name.

Parameters:

• name (str) – the canonical name for the method

• params (List[Union[ContentDescriptor, Dict[str, Any]]]) – a list of parameters that are applicable for this method

• result (Union[ContentDescriptor, Dict[str, Any]]) – the description of the result returned by the method

• errors (Union[UnsetType, List[Error]]) – a list of custom application defined errors that MAY be returned

• examples (Union[UnsetType, List[MethodExample]]) – method usage examples

• summary (Union[UnsetType, str]) – a short summary of what the method does

• description (Union[UnsetType, str]) – a verbose explanation of the method behavior

• tags (Union[UnsetType, List[Tag]]) – a list of tags for API documentation control

• deprecated (Union[UnsetType, bool]) – declares this method to be deprecated

• paramStructure (Union[UnsetType, ParamStructure]) – the expected format of the parameters

• externalDocs (Union[UnsetType, ExternalDocumentation]) – additional external documentation for this method

• servers (Union[UnsetType, List[Server]]) – an alternative servers array to service this method

class pjrpc.server.specs.openrpc.Components(schemas=<factory>)

Bases: object

Set of reusable objects for different aspects of the OpenRPC.

Parameters:

schemas (Dict[str, Any]) – reusable Schema Objects

pjrpc.server.specs.openrpc.annotate(params_schema=UNSET, result_schema=UNSET, errors=UNSET, examples=UNSET, summary=UNSET, description=UNSET, tags=UNSET, deprecated=UNSET)

Adds JSON-RPC method to the API specification.

Parameters:

• params_schema (Union[UnsetType, List[ContentDescriptor]]) – a list of parameters that are applicable for this method

• result_schema (Union[UnsetType, ContentDescriptor]) – the description of the result returned by the method

• errors (Union[UnsetType, List[Union[Error, Type[JsonRpcError]]]]) – a list of custom application defined errors that MAY be returned

• examples (Union[UnsetType, List[MethodExample]]) – method usage example

• summary (Union[UnsetType, str]) – a short summary of what the method does

• description (Union[UnsetType, str]) – a verbose explanation of the method behavior

• tags (Union[UnsetType, List[Union[Tag, str]]]) – a list of tags for API documentation control

• deprecated (Union[UnsetType, bool]) – declares this method to be deprecated

Return type:

Callable[[Func], Func]

class pjrpc.server.specs.openrpc.OpenRPC(info, path='/openrpc.json', servers=UNSET, external_docs=UNSET, openrpc='1.0.0', schema_extractor=None)

Bases: Specification

OpenRPC Specification.

Parameters:

• info (Info) – specification information

• path (str) – specification url path

• servers (Union[UnsetType, List[Server]]) – connectivity information

• external_docs (Union[UnsetType, ExternalDocumentation]) – additional external documentation

• openrpc (str) – the semantic version number of the OpenRPC Specification version that the OpenRPC document uses

• schema_extractor (Optional[BaseSchemaExtractor]) – method specification extractor

schema(path, methods=(), methods_map={})

Returns specification schema.

Parameters:

• path (str) – methods endpoint path

• methods (Iterable[Method]) – methods list the specification is generated for

• methods_map (Mapping[str, Iterable[Method]]) – methods map the specification is generated for. Each item is a mapping from a prefix to methods on which the methods will be served

Return type:

Dict[str, Any]