coarnotify.server

Supporting classes for COAR Notify server implementations

Exceptions

COARNotifyServerError

An exception class for server errors in the COAR Notify server implementation.

Classes

COARNotifyReceipt	An object representing the response from a COAR Notify server.
COARNotifyServer	The main entrypoint to the COAR Notify server implementation.
COARNotifyServiceBinding	Interface for implementing a COAR Notify server binding.

Module Contents

exception coarnotify.server.COARNotifyServerError(status: int, msg: str)

Bases: Exception

An exception class for server errors in the COAR Notify server implementation.

The web layer of your server implementation should be able to intercept this from the COARNotifyServer.receive() method and return the appropriate HTTP status code and message to the user in its standard way.

Parameters:

• status – HTTP Status code to respond to the client with

• msg – Message to send back to the client

property message: str

The error message

property status: int

HTTP status code for the error

class coarnotify.server.COARNotifyReceipt(status: int, location: str = None)

An object representing the response from a COAR Notify server.

Server implementations should construct and return this object with the appropriate properties when implementing the COARNotifyServiceBinding.notification_received() binding

Parameters:

• status – the HTTP status code, should be one of the constants CREATED (201) or ACCEPTED (202)

• location – the HTTP URI for the resource that was created (if present)

ACCEPTED = 202

The status code for an accepted request

CREATED = 201

The status code for a created resource

property location: str | None

The HTTP URI of the created resource, if present

property status: int

The status code of the response. Should be one of the constants CREATED (201) or ACCEPTED (202)

class coarnotify.server.COARNotifyServer(service_impl: COARNotifyServiceBinding)

The main entrypoint to the COAR Notify server implementation.

The web layer of your application should pass the json/raw payload of any incoming notification to the receive() method, which will parse the payload and pass it to the COARNotifyServiceBinding.notification_received() method of your service implementation

This object should be constructed with your service implementation passed to it, for example

server = COARNotifyServer(MyServiceBinding())
try:
    response = server.receive(request.json)
    return jsonify(response)
except COARNotifyServerError as e:
    abort(e.status, e.message)

Parameters:

service_impl – Your service implementation

receive(raw: dict | str, validate: bool = True) → COARNotifyReceipt

Receive an incoming notification as JSON, parse and validate (optional) and then pass to the service implementation

Parameters:

• raw – The JSON representation of the data, either as a string or a dictionary

• validate – Whether to validate the notification before passing to the service implementation

Returns:

The COARNotifyReceipt response from the service implementation

class coarnotify.server.COARNotifyServiceBinding

Interface for implementing a COAR Notify server binding.

Server implementation should extend this class and implement the notification_received() method

That method will receive a NotifyPattern object, which will be one of the known types and should return a COARNotifyReceipt object with the appropriate status code and location URL

abstract notification_received(notification: coarnotify.core.notify.NotifyPattern) → COARNotifyReceipt

Process the receipt of the given notification, and respond with an appropriate receipt object

Parameters:

notification – the notification object received

Returns:

the receipt object to send back to the client