coarnotify.core.notify¶

This module is home to all the core model objects from which the notify patterns extend

Attributes¶

`NOTIFY_NAMESPACE`	Namespace for COAR Notify, to be used to construct namespaced properties used in COAR Notify Patterns
`VALIDATORS`	Default Validator object for all pattern types, of type `coarnotify.validate.Validator`

Classes¶

`NestedPatternObjectMixin`	A mixin to add to a pattern which can override the default object property to return a full
`NotifyActor`	Deafult class to represents an actor in the COAR Notify pattern.
`NotifyBase`	Base class from which all Notify objects extend.
`NotifyItem`	Defult class to represent an item in the COAR Notify pattern.
`NotifyObject`	Deafult class to represent an object in the COAR Notify pattern. Objects can be used for `object` or `context` properties
`NotifyPattern`	Base class for all notification patterns
`NotifyPatternPart`	Base class for all pattern parts, such as objects, contexts, actors, etc
`NotifyProperties`	COAR Notify properties used in COAR Notify Patterns
`NotifyService`	Default class to represent a service in the COAR Notify pattern.
`NotifyTypes`	List of all the COAR Notify types patterns may use.
`SummaryMixin`	Mixin to provide an API for setting and getting the `summary` property of a pattern

Module Contents¶

class coarnotify.core.notify.NestedPatternObjectMixin¶

A mixin to add to a pattern which can override the default object property to return a full nested pattern from the object property, rather than the default NotifyObject

This mixin needs to be first on the inheritance list, as it overrides the object property of the NotifyPattern class.

For example:

class MySpecialPattern(NestedPatternObjectMixin, NotifyPattern):
    pass

property object: NotifyPattern | NotifyObject | None¶: Retrieve an object as it’s correctly typed pattern, falling back to a default NotifyObject if no pattern matches

class coarnotify.core.notify.NotifyActor(stream: coarnotify.core.activitystreams2.ActivityStream | dict = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True)¶

Bases: NotifyPatternPart

Deafult class to represents an actor in the COAR Notify pattern. Actors are used to represent the actor property in the notification patterns

Specific patterns may need to extend this class to provide their specific behaviours and validation

ALLOWED_TYPES¶: The allowed types for an actor: Service, Application, Group, Organisation, Person

DEFAULT_TYPE¶: Default type is Service, but can also be set as any one of the other allowed types

property name: str¶: Get the name property of the actor

class coarnotify.core.notify.NotifyBase(stream: coarnotify.core.activitystreams2.ActivityStream | dict = None, validate_stream_on_construct: bool = True, validate_properties: bool = True, validators: coarnotify.validate.Validator = None, validation_context: str | Tuple[str, str] = None, properties_by_reference: bool = True)¶

Base class from which all Notify objects extend.

There are two kinds of Notify objects:

Patterns, which are the notifications themselves
Pattern Parts, which are nested elements in the Patterns, such as objects, contexts, actors, etc

This class forms the basis for both of those types, and provides essential services, such as construction, accessors and validation, as well as supporting the essential properties “id” and “type”

get_property(prop_name: str | Tuple[str, str], by_reference: bool = None)¶

Generic property getter. It is strongly recommended that all accessors proxy for this function as this enforces by-reference/by-value accessing, and mediates directly with the underlying activity stream object.

Parameters:

prop_name – The property to retrieve
by_reference – Whether to retrieve by_reference or by_value. If not supplied will default to the object-wide setting

Returns:

the property value

optional_and_validate(ve: coarnotify.exceptions.ValidationError, prop_name: str | tuple, value)¶

Validate the value if it is not None, but do not raise a validation error if it is None

Parameters:

ve
prop_name
value

Returns:

required(ve: coarnotify.exceptions.ValidationError, prop_name: str | tuple, value)¶

Add a required error to the validation error if the value is None

Parameters:

ve – The validation error to which to add the message
prop_name – The property to check
value – The value

required_and_validate(ve: coarnotify.exceptions.ValidationError, prop_name: str | tuple, value)¶

Add a required error to the validation error if the value is None, and then validate the value if not.

Any error messages are added to the ValidationError object

Parameters:

ve – the validation error to which to add the message
prop_name – The property to check
value – the value to check

set_property(prop_name: str | Tuple[str, str], value, by_reference: bool = None)¶

Generic property setter. It is strongly recommended that all accessors proxy for this function as this enforces by-reference/by-value accessing, and mediates directly with the underlying activity stream object.

Parameters:

prop_name – The property to set
value – The value to set
by_reference – Whether to set by_reference or by_value. If not supplied will default to the object-wide setting

to_jsonld() → dict¶

Get the notification pattern as JSON-LD

Returns:: JSON-LD representation of the pattern

validate() → bool¶

Validate the object. This provides the basic validation on id and type. Subclasses should override this method with their own validation, and call this method via super first to ensure the basic properties are validated.

Returns:: True or raise a coarnotify.exceptions.ValidationError if there are errors

validate_property(prop_name: str | Tuple[str, str], value, force_validate: bool = False, raise_error: bool = True) → Tuple[bool, str]¶

Validate a single property. This is used internally by set_property().

If the object has validate_properties set to False then that behaviour may be overridden by setting force_validate to True

The validator applied to the property will be determined according to the validators property of the object and the validation_context of the object.

Parameters:

prop_name – The property to validate
value – the value to validate
force_validate – whether to validate anyway, even if property validation is turned off at the object level
raise_error – raise an exception on validation failure, or return a tuple with the result

Returns:

A tuple of whether validation was successful, and the error message if it was not (the empty string is returned as the second element if validation was successful)

property doc¶: The underlying ActivityStream object, excluding the JSON-LD @context

property id: str¶: The id of the object

property type: str | list[str]¶: The type of the object

property validate_properties: bool¶: Are properties being validated on set

property validate_stream_on_construct: bool¶: Is the stream validated on construction

property validators: coarnotify.validate.Validator¶: The validator object for this instance

class coarnotify.core.notify.NotifyItem(stream: coarnotify.core.activitystreams2.ActivityStream | dict = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True)¶

Bases: NotifyPatternPart

Defult class to represent an item in the COAR Notify pattern. Items are used to represent the ietf:item property in the notification patterns

Specific patterns may need to extend this class to provide their specific behaviours and validation

validate()¶

Validate the item. This overrides the base validation, as objects only absolutely require an id property, so the base requirement for a type is relaxed.

Returns:: True if valid, otherwise raises coarnotify.exceptions.ValidationError

property media_type: str¶: Get the mediaType property of the item

class coarnotify.core.notify.NotifyObject(stream: coarnotify.core.activitystreams2.ActivityStream | dict = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True)¶

Bases: NotifyPatternPart

Deafult class to represent an object in the COAR Notify pattern. Objects can be used for object or context properties in notify patterns

Specific patterns may need to extend this class to provide their specific behaviours and validation

validate() → bool¶

Validate the object. This overrides the base validation, as objects only absolutely require an id property, so the base requirement for a type is relaxed.

Returns:: True if valid, otherwise raises coarnotify.exceptions.ValidationError

property cite_as: str¶: Get the ietf:cite-as property of the object

property item: NotifyItem | None¶: Get the ietf:item property of the object

property triple: tuple[str, str, str]¶: Get object, relationship and subject properties as a relationship triple

class coarnotify.core.notify.NotifyPattern(stream: coarnotify.core.activitystreams2.ActivityStream | dict = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True)¶

Bases: NotifyBase

Base class for all notification patterns

validate() → bool¶

Base validator for all notification patterns. This extends the validate function on the superclass.

In addition to the base class’s constraints, this applies the following validation:

The origin, target and object properties are required and must be valid
The actor inReplyTo and context properties are optional, but if present must be valid

NotifyBase :return: True if valid, otherwise raises coarnotify.exceptions.ValidationError

TYPE¶: The type of the pattern. This should be overridden by subclasses, otherwise defaults to Object

property actor: NotifyActor | None¶: Get the actor property of the notification

property context: NotifyObject | None¶: Get the context property of the notification

property in_reply_to: str¶: Get the inReplyTo property of the notification

property object: NotifyObject | None¶: Get the object property of the notification

property origin: NotifyService | None¶: Get the origin property of the notification

property target: NotifyService | None¶: Get the target property of the notification

class coarnotify.core.notify.NotifyPatternPart(stream: coarnotify.core.activitystreams2.ActivityStream | dict = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True)¶

Bases: NotifyBase

Base class for all pattern parts, such as objects, contexts, actors, etc

If there is a default type specified, and a type is not given at construction, then the default type will be added

Parameters:

stream – The activity stream object, or a dict from which one can be created
validate_stream_on_construct – should the incoming stream be validated at construction-time
validate_properties – should individual properties be validated as they are set
validators – the validator object for this class and all nested elements. If not provided will use the default VALIDATORS
validation_context – the context in which this object is being validated. This is used to determine which validators to use
properties_by_reference – should properties be get and set by reference (the default) or by value. Use this with caution: setting by value makes it impossible to set a property in a nested object using the dot notation, like obj.actor.name = "Bob", instead you will need to retrive the object, set the value, then set the whole object back on the parent object.

ALLOWED_TYPES = []¶: The list of types that are permissable for this object. If the list is empty, then any type is allowed

DEFAULT_TYPE = None¶: The default type for this object, if none is provided on construction. If not provided, then no default type will be set

class coarnotify.core.notify.NotifyProperties¶

COAR Notify properties used in COAR Notify Patterns

Most of these are provided as tuples, where the first element is the property name, and the second element is the namespace. Some are provided as plain strings without namespaces

These are suitable to be used as property names in all the property getters/setters in the notify pattern objects and in the validation configuration.

CITE_AS¶: ietf:cite-as property

INBOX¶: inbox property

ITEM¶: ietf:item property

MEDIA_TYPE = 'mediaType'¶: mediaType property

NAME = 'name'¶: name property

class coarnotify.core.notify.NotifyService(stream: coarnotify.core.activitystreams2.ActivityStream | dict = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True)¶

Bases: NotifyPatternPart

Default class to represent a service in the COAR Notify pattern.

Services are used to represent origin and target properties in the notification patterns

Specific patterns may need to extend this class to provide their specific behaviours and validation

DEFAULT_TYPE¶: The default type for a service is Service, but the type can be set to any value

property inbox: str¶: Get the inbox property of the service

class coarnotify.core.notify.NotifyTypes¶

List of all the COAR Notify types patterns may use.

These are in addition to the base Activity Streams types, which are in coarnotify.core.activitystreams2.ActivityStreamsTypes

ABOUT_PAGE = 'sorg:AboutPage'¶

ENDORSMENT_ACTION = 'coar-notify:EndorsementAction'¶

INGEST_ACTION = 'coar-notify:IngestAction'¶

RELATIONSHIP_ACTION = 'coar-notify:RelationshipAction'¶

REVIEW_ACTION = 'coar-notify:ReviewAction'¶

UNPROCESSABLE_NOTIFICATION = 'coar-notify:UnprocessableNotification'¶

class coarnotify.core.notify.SummaryMixin¶

Mixin to provide an API for setting and getting the summary property of a pattern

property summary: str¶: The summary property of the pattern

coarnotify.core.notify.NOTIFY_NAMESPACE = 'https://coar-notify.net'¶: Namespace for COAR Notify, to be used to construct namespaced properties used in COAR Notify Patterns

coarnotify.core.notify.VALIDATORS: coarnotify.validate.Validator¶: Default Validator object for all pattern types, of type coarnotify.validate.Validator

coarnotify.core.notify¶

Attributes¶

Classes¶

Module Contents¶

coarnotify

Navigation

Related Topics