Core¶

Core API reference

class notifiers.core.SchemaResource[source]¶

Base class that represent an object schema and its utility methods

_get_environs(prefix: str = None) → dict[source]¶

Fetches set environment variables if such exist, via the dict_from_environs() Searches for [PREFIX_NAME]_[PROVIDER_NAME]_[ARGUMENT] for each of the arguments defined in the schema

Return type: dict
Parameters: prefix (str) – The environ prefix to use. If not supplied, uses the default
Returns: A dict of arguments and value retrieved from environs

_merge_defaults(data: dict) → dict[source]¶

Convenience method that calls merge_dicts() in order to merge default values

Return type: dict
Parameters: data (dict) – Notification data
Returns: A merged dict of provided data with added defaults

_prepare_data(data: dict) → dict[source]¶

Use this method to manipulate data that’ll fit the respected provider API.: For example, all provider must use the message argument but sometimes provider expects a different variable name for this, like text.

Return type: dict
Parameters: data (dict) – Notification data
Returns: Returns manipulated data, if there’s a need for such manipulations.

_process_data(**data) → dict[source]¶

The main method that process all resources data. Validates schema, gets environs, validates data, prepares: it via provider requirements, merges defaults and check for data dependencies

Return type: dict
Parameters: data – The raw data passed by the notifiers client
Returns: Processed data

abstract property _required¶: Will hold the schema’s required part

abstract property _schema¶: Resource JSON schema without the required part

_validate_data(data: dict)[source]¶

Validates data against provider schema. Raises BadArguments if relevant

Parameters: data (dict) – Data to validate
Raises: BadArguments

_validate_data_dependencies(data: dict) → dict[source]¶

Validates specific dependencies based on the content of the data, as opposed to its structure which can be verified on the schema level

Return type: dict
Parameters: data (dict) – Data to validate
Returns: Return data if its valid
Raises: NotifierException

_validate_schema()[source]¶

Validates provider schema for syntax issues. Raises SchemaError if relevant

Raises: SchemaError

property arguments¶: Returns all of the provider argument as declared in the JSON schema

create_response(data: dict = None, response: requests.models.Response = None, errors: list = None) → notifiers.core.Response[source]¶

Helper function to generate a Response object

Return type

Response

Parameters

data (dict) – The data that was used to send the notification
response (Response) – requests.Response if exist
errors (list) – List of errors if relevant

property defaults¶: A dict of default provider values if such is needed

abstract property name¶: Resource provider name

property required¶: Returns a dict of the relevant required parts of the schema

property schema¶

A property method that’ll return the constructed provider schema. Schema MUST be an object and this method must be overridden

Returns: JSON schema of the provider

class notifiers.core.Provider[source]¶

The Base class all notification providers inherit from.

abstract _send_notification(data: dict) → notifiers.core.Response[source]¶

The core method to trigger the provider notification. Must be overridden.

Return type: Response
Parameters: data (dict) – Notification data

property metadata¶: Returns a dict of the provider metadata as declared. Override if needed.

notify(raise_on_errors: bool = False, **kwargs) → notifiers.core.Response[source]¶

The main method to send notifications. Prepares the data via the _prepare_data() method and then sends the notification via the _send_notification() method

Return type

Response

Parameters

kwargs – Notification data
raise_on_errors (bool) – Should the raise_on_errors() be invoked immediately

Returns

A Response object

Raises

NotificationError if raise_on_errors is set to True and response contained errors

property resources¶: Return a list of names of relevant ProviderResource objects

class notifiers.core.ProviderResource[source]¶: The base class that is used to fetch provider related resources like rooms, channels, users etc.

class notifiers.core.Response(status: str, provider: str, data: dict, response: requests.models.Response = None, errors: list = None)[source]¶

A wrapper for the Notification response.

Parameters

status – Response status string. SUCCESS or FAILED
provider – Provider name that returned that response. Correlates to name
data – The notification data that was used for the notification
response – The response object that was returned. Usually requests.Response
errors – Holds a list of errors if relevant

raise_on_errors()[source]¶

Raises a NotificationError if response hold errors

Raises: NotificationError: If response has errors

notifiers.core.get_notifier(provider_name: str, strict: bool = False) → notifiers.core.Provider[source]¶

Convenience method to return an instantiated Provider object according to it name

Return type

Provider

Parameters

provider_name (str) – The name of the requested Provider
strict (bool) – Raises a ValueError if the given provider string was not found

Returns

Provider or None

Raises

ValueError – In case strict is True and provider not found

notifiers.core.all_providers() → list[source]¶: Returns a list of all Provider names

notifiers.core.notify(provider_name: str, **kwargs) → notifiers.core.Response[source]¶

Quickly sends a notification without needing to get a notifier via the get_notifier() method.

Return type

Response

Parameters

provider_name (str) – Name of the notifier to use. Note that if this notifier name does not exist it will raise a
kwargs – Notification data, dependant on provider

Returns

Response

Raises

NoSuchNotifierError If provider_name is unknown, will raise notification error

Logging¶

class notifiers.logging.NotificationHandler(provider: str, defaults: dict = None, **kwargs)[source]¶

A logging.Handler that enables directly sending log messages to notifiers

emit(record)[source]¶

Override the emit() method that takes the msg attribute from the log record passed

Parameters: record – logging.LogRecord

handleError(record)[source]¶

Handles any errors raised during the emit() method. Will only try to pass exceptions to fallback notifier (if defined) in case the exception is a sub-class of NotifierException

Parameters: record – logging.LogRecord

init_providers(provider, kwargs)[source]¶

Inits main and fallback provider if relevant

Parameters

provider – Provider name to use
kwargs – Additional kwargs

Raises

ValueError – If provider name or fallback names are not valid providers, a ValueError will be raised