coarnotify.core.notify ====================== .. py:module:: coarnotify.core.notify .. autoapi-nested-parse:: This module is home to all the core model objects from which the notify patterns extend Attributes ---------- .. autoapisummary:: coarnotify.core.notify.NOTIFY_NAMESPACE coarnotify.core.notify.VALIDATORS Classes ------- .. autoapisummary:: coarnotify.core.notify.NestedPatternObjectMixin coarnotify.core.notify.NotifyActor coarnotify.core.notify.NotifyBase coarnotify.core.notify.NotifyItem coarnotify.core.notify.NotifyObject coarnotify.core.notify.NotifyPattern coarnotify.core.notify.NotifyPatternPart coarnotify.core.notify.NotifyProperties coarnotify.core.notify.NotifyService coarnotify.core.notify.NotifyTypes coarnotify.core.notify.SummaryMixin Module Contents --------------- .. py:class:: 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 :py:class:`NotifyObject` This mixin needs to be first on the inheritance list, as it overrides the object property of the NotifyPattern class. For example: .. code-block:: python class MySpecialPattern(NestedPatternObjectMixin, NotifyPattern): pass .. py:property:: object :type: Union[NotifyPattern, NotifyObject, None] Retrieve an object as it's correctly typed pattern, falling back to a default ``NotifyObject`` if no pattern matches .. py:class:: NotifyActor(stream: Union[coarnotify.core.activitystreams2.ActivityStream, dict] = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True) Bases: :py:obj:`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 .. py:attribute:: ALLOWED_TYPES The allowed types for an actor: ``Service``, ``Application``, ``Group``, ``Organisation``, ``Person`` .. py:attribute:: DEFAULT_TYPE Default type is ``Service``, but can also be set as any one of the other allowed types .. py:property:: name :type: str Get the name property of the actor .. py:class:: NotifyBase(stream: Union[coarnotify.core.activitystreams2.ActivityStream, dict] = None, validate_stream_on_construct: bool = True, validate_properties: bool = True, validators: coarnotify.validate.Validator = None, validation_context: Union[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: 1. Patterns, which are the notifications themselves 2. 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" .. py:method:: get_property(prop_name: Union[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. :param prop_name: The property to retrieve :param by_reference: Whether to retrieve by_reference or by_value. If not supplied will default to the object-wide setting :return: the property value .. py:method:: optional_and_validate(ve: coarnotify.exceptions.ValidationError, prop_name: Union[str, tuple], value) Validate the value if it is not None, but do not raise a validation error if it is None :param ve: :param prop_name: :param value: :return: .. py:method:: required(ve: coarnotify.exceptions.ValidationError, prop_name: Union[str, tuple], value) Add a required error to the validation error if the value is None :param ve: The validation error to which to add the message :param prop_name: The property to check :param value: The value .. py:method:: required_and_validate(ve: coarnotify.exceptions.ValidationError, prop_name: Union[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 :param ve: the validation error to which to add the message :param prop_name: The property to check :param value: the value to check .. py:method:: set_property(prop_name: Union[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. :param prop_name: The property to set :param value: The value to set :param by_reference: Whether to set by_reference or by_value. If not supplied will default to the object-wide setting .. py:method:: to_jsonld() -> dict Get the notification pattern as JSON-LD :return: JSON-LD representation of the pattern .. py:method:: 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. :return: ``True`` or raise a :py:class:`coarnotify.exceptions.ValidationError` if there are errors .. py:method:: validate_property(prop_name: Union[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 :py:meth:`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. :param prop_name: The property to validate :param value: the value to validate :param force_validate: whether to validate anyway, even if property validation is turned off at the object level :param raise_error: raise an exception on validation failure, or return a tuple with the result :return: 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) .. py:property:: doc The underlying ActivityStream object, excluding the JSON-LD @context .. py:property:: id :type: str The ``id`` of the object .. py:property:: type :type: Union[str, list[str]] The ``type`` of the object .. py:property:: validate_properties :type: bool Are properties being validated on set .. py:property:: validate_stream_on_construct :type: bool Is the stream validated on construction .. py:property:: validators :type: coarnotify.validate.Validator The validator object for this instance .. py:class:: NotifyItem(stream: Union[coarnotify.core.activitystreams2.ActivityStream, dict] = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True) Bases: :py:obj:`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 .. py:method:: 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. :return: ``True`` if valid, otherwise raises :py:class:`coarnotify.exceptions.ValidationError` .. py:property:: media_type :type: str Get the ``mediaType`` property of the item .. py:class:: NotifyObject(stream: Union[coarnotify.core.activitystreams2.ActivityStream, dict] = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True) Bases: :py:obj:`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 .. py:method:: 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. :return: ``True`` if valid, otherwise raises :py:class:`coarnotify.exceptions.ValidationError` .. py:property:: cite_as :type: str Get the ``ietf:cite-as`` property of the object .. py:property:: item :type: Union[NotifyItem, None] Get the ``ietf:item`` property of the object .. py:property:: triple :type: tuple[str, str, str] Get object, relationship and subject properties as a relationship triple .. py:class:: NotifyPattern(stream: Union[coarnotify.core.activitystreams2.ActivityStream, dict] = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True) Bases: :py:obj:`NotifyBase` Base class for all notification patterns .. py:method:: 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 :py:class:`NotifyBase` :return: ``True`` if valid, otherwise raises :py:class:`coarnotify.exceptions.ValidationError` .. py:attribute:: TYPE The type of the pattern. This should be overridden by subclasses, otherwise defaults to ``Object`` .. py:property:: actor :type: Union[NotifyActor, None] Get the actor property of the notification .. py:property:: context :type: Union[NotifyObject, None] Get the context property of the notification .. py:property:: in_reply_to :type: str Get the inReplyTo property of the notification .. py:property:: object :type: Union[NotifyObject, None] Get the object property of the notification .. py:property:: origin :type: Union[NotifyService, None] Get the origin property of the notification .. py:property:: target :type: Union[NotifyService, None] Get the target property of the notification .. py:class:: NotifyPatternPart(stream: Union[coarnotify.core.activitystreams2.ActivityStream, dict] = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True) Bases: :py:obj:`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 :param stream: The activity stream object, or a dict from which one can be created :param validate_stream_on_construct: should the incoming stream be validated at construction-time :param validate_properties: should individual properties be validated as they are set :param validators: the validator object for this class and all nested elements. If not provided will use the default :py:data:`VALIDATORS` :param validation_context: the context in which this object is being validated. This is used to determine which validators to use :param 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. .. py:attribute:: ALLOWED_TYPES :value: [] The list of types that are permissable for this object. If the list is empty, then any type is allowed .. py:attribute:: DEFAULT_TYPE :value: None The default type for this object, if none is provided on construction. If not provided, then no default type will be set .. py:class:: 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. .. py:attribute:: CITE_AS ``ietf:cite-as`` property .. py:attribute:: INBOX ``inbox`` property .. py:attribute:: ITEM ``ietf:item`` property .. py:attribute:: MEDIA_TYPE :value: 'mediaType' ``mediaType`` property .. py:attribute:: NAME :value: 'name' ``name`` property .. py:class:: NotifyService(stream: Union[coarnotify.core.activitystreams2.ActivityStream, dict] = None, validate_stream_on_construct=True, validate_properties=True, validators=None, validation_context=None, properties_by_reference=True) Bases: :py:obj:`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 .. py:attribute:: DEFAULT_TYPE The default type for a service is ``Service``, but the type can be set to any value .. py:property:: inbox :type: str Get the ``inbox`` property of the service .. py:class:: NotifyTypes List of all the COAR Notify types patterns may use. These are in addition to the base Activity Streams types, which are in :py:class:`coarnotify.core.activitystreams2.ActivityStreamsTypes` .. py:attribute:: ABOUT_PAGE :value: 'sorg:AboutPage' .. py:attribute:: ENDORSMENT_ACTION :value: 'coar-notify:EndorsementAction' .. py:attribute:: INGEST_ACTION :value: 'coar-notify:IngestAction' .. py:attribute:: RELATIONSHIP_ACTION :value: 'coar-notify:RelationshipAction' .. py:attribute:: REVIEW_ACTION :value: 'coar-notify:ReviewAction' .. py:attribute:: UNPROCESSABLE_NOTIFICATION :value: 'coar-notify:UnprocessableNotification' .. py:class:: SummaryMixin Mixin to provide an API for setting and getting the ``summary`` property of a pattern .. py:property:: summary :type: str The summary property of the pattern .. py:data:: NOTIFY_NAMESPACE :value: 'https://coar-notify.net' Namespace for COAR Notify, to be used to construct namespaced properties used in COAR Notify Patterns .. py:data:: VALIDATORS :type: coarnotify.validate.Validator Default Validator object for all pattern types, of type :py:class:`coarnotify.validate.Validator`