Utils

Assorted helper utils

notifiers.utils.helpers.text_to_bool(value: str) → bool[source]

Tries to convert a text value to a bool. If unsuccessful returns if value is None or not

Parameters:

value – Value to check

notifiers.utils.helpers.merge_dicts(target_dict: dict, merge_dict: dict) → dict[source]

Merges merge_dict into target_dict if the latter does not already contain a value for each of the key names in merge_dict. Used to cleanly merge default and environ data into notification payload.

Parameters:

  • target_dict – The target dict to merge into and return, the user provided data for example

  • merge_dict – The data that should be merged into the target data

Returns:

A dict of merged data

notifiers.utils.helpers.dict_from_environs(prefix: str, name: str, args: list) → dict[source]

Return a dict of environment variables correlating to the arguments list, main name and prefix like so: [prefix]_[name]_[arg]

Parameters:

  • prefix – The environ prefix to use

  • name – Main part

  • args – List of args to iterate over

Returns:

A dict of found environ values

notifiers.utils.helpers.list_to_commas(list_of_args) → str[source]

Converts a list of items to a comma separated list. If list_of_args is not a list, just return it back

Parameters:

list_of_args – List of items

Returns:

A string representing a comma separated list.

notifiers.utils.helpers.snake_to_camel_case(value: str) → str[source]

Convert a snake case param to CamelCase

Parameters:

value – The value to convert

Returns:

A CamelCase value

notifiers.utils.helpers.valid_file(path: str) → bool[source]

Verifies that a string path actually exists and is a file

Parameters:

path – The path to verify

Returns:

True if path exist and is a file

class notifiers.utils.requests.RequestsHelper[source]

A wrapper around requests.Session which enables generically handling HTTP requests

classmethod request(url: str, method: str, raise_for_status: bool = True, path_to_errors: tuple | None = None, *args, **kwargs) → tuple[source]

A wrapper method for request`(), which adds some defaults and logging

Parameters:

  • url – The URL to send the reply to

  • method – The method to use

  • raise_for_status – Should an exception be raised for a failed response. Default is True

  • args – Additional args to be sent to the request

  • kwargs – Additional args to be sent to the request

Returns:

Dict of response body or original requests.Response

Schema models

Base model and helpers used to declare provider schemas, see Writing Your Own Providers.

class notifiers.models.SchemaModel(**data: Any)[source]

Base class for all provider and resource schemas.

  • Unknown arguments are rejected (extra="forbid"). Providers that pass unknown arguments through to their API override this with extra="allow".

  • Fields can be populated by their name or their alias. Python attribute names are snake_case, the alias holds the name the remote API (or the pre 2.0 argument) uses, e.g. device_id with alias deviceId.

  • Model building is deferred until first use, which keeps import notifiers fast.

Cross field rules are regular pydantic @model_validator methods. The helpers below make the common ones short.

is_set(name: str) → bool[source]

Whether the field name was passed with a non None value

require_dependencies(dependencies: dict[str, list[str]])[source]

Raises if a field was passed without the fields it depends on

Parameters:

dependencies – {"a": ["b"]} means that if a is passed, b must be passed too. Field names

notifiers.models.one_or_more(item_type: Any, *, max_items: int | None = None, unique: bool = True) → Any[source]

Builds a type that accepts either a single item_type value or a non empty list of them. The value’s shape is preserved: a single value stays a single value, a tuple becomes a list.

Parameters:

  • item_type – Type of a single item

  • max_items – Maximum allowed number of items in the list form

  • unique – Whether list items must be unique

class notifiers.models.OneOrMore[source]

OneOrMore[T] is shorthand for one_or_more(T)

notifiers.models.required_fields(model: type[SchemaModel]) → list[str][source]

Names (aliases where set) of the required fields, in declaration order: fields without a default, plus fields listed in the model’s required_with_default

notifiers.models.model_defaults(model: type[SchemaModel], keys: set[str] | None = None) → dict[source]

A dict of the non-None default values declared on a model, keyed by field_key(). Fields with a default_factory are included, the factory is called each time.

Parameters:

  • model – The model to get defaults of

  • keys – Only include these keys. Factories of other fields are not called

Schema types

Reusable annotated types for schema fields. They replace the custom JSON schema format checkers used before 2.0.

notifiers.models.types.Email

An email address. Only checks that the value contains an @

alias of Annotated[str, AfterValidator(func=_check_email)]

notifiers.models.types.Url = <class 'str'>

A URL. Kept as str and not validated, the provider’s API is the authority on what it accepts

notifiers.models.types.Hostname = <class 'str'>

A hostname. Not validated, connecting to the server is the authority on whether it’s valid

notifiers.models.types.Port

A TCP port number

alias of Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=65535)])]

notifiers.models.types.Timestamp

A non negative Unix timestamp, as an integer or a numeric string

alias of Annotated[int | str, AfterValidator(func=_check_timestamp)]

notifiers.models.types.ISO8601Datetime

An ISO 8601 date/time string

alias of Annotated[str, AfterValidator(func=_check_iso8601)]

notifiers.models.types.RFC2822Datetime

An RFC 2822 date/time string

alias of Annotated[str, AfterValidator(func=_check_rfc2822)]

notifiers.models.types.DateString

A YYYY-MM-DD date string

alias of Annotated[str, AfterValidator(func=_check_date)]

notifiers.models.types.AsciiStr

A string with only ASCII characters

alias of Annotated[str, AfterValidator(func=_check_ascii)]

notifiers.models.types.FilePath

A path to an existing file. ~ is expanded for the check, the value is kept as given

alias of Annotated[str, AfterValidator(func=_check_valid_file)]

notifiers.models.types.E164

A phone number in E.164 format

alias of Annotated[str, AfterValidator(func=_check_e164)]