Metadata-Version: 2.0
Name: notifiers
Version: 0.5.1
Summary: Easily send notifications everywhere
Home-page: https://github.com/liiight/notifiers
Author: Or Carmi
Author-email: or.carmi82@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Requires-Dist: certifi (==2017.4.17)
Requires-Dist: chardet (==3.0.4)
Requires-Dist: click (==6.7)
Requires-Dist: idna (==2.5)
Requires-Dist: jsonschema (==2.6.0)
Requires-Dist: requests (==2.18.2)
Requires-Dist: urllib3 (==1.22)
Provides-Extra: dev
Requires-Dist: alabaster (==0.7.10); extra == 'dev'
Requires-Dist: babel (==2.5.1); extra == 'dev'
Requires-Dist: bumpversion (==0.5.3); extra == 'dev'
Requires-Dist: certifi (==2017.7.27.1); extra == 'dev'
Requires-Dist: chardet (==3.0.4); extra == 'dev'
Requires-Dist: click (==6.7); extra == 'dev'
Requires-Dist: codecov (==2.0.9); extra == 'dev'
Requires-Dist: coverage (==4.4.1); extra == 'dev'
Requires-Dist: docutils (==0.14); extra == 'dev'
Requires-Dist: first (==2.0.1); extra == 'dev'
Requires-Dist: idna (==2.5); extra == 'dev'
Requires-Dist: imagesize (==0.7.1); extra == 'dev'
Requires-Dist: jinja2 (==2.9.6); extra == 'dev'
Requires-Dist: markupsafe (==1.0); extra == 'dev'
Requires-Dist: pip-tools (==1.10.0); extra == 'dev'
Requires-Dist: py (==1.4.34); extra == 'dev'
Requires-Dist: pygments (==2.2.0); extra == 'dev'
Requires-Dist: pytest-cov (==2.5.1); extra == 'dev'
Requires-Dist: pytest (==3.2.2); extra == 'dev'
Requires-Dist: pytz (==2017.2); extra == 'dev'
Requires-Dist: requests (==2.18.3); extra == 'dev'
Requires-Dist: six (==1.11.0); extra == 'dev'
Requires-Dist: snowballstemmer (==1.2.1); extra == 'dev'
Requires-Dist: sphinx-autodoc-annotation (==1.0.post1); extra == 'dev'
Requires-Dist: sphinx (==1.6.4); extra == 'dev'
Requires-Dist: sphinxcontrib-websupport (==1.0.1); extra == 'dev'
Requires-Dist: urllib3 (==1.22); extra == 'dev'

Notifiers
=========
The easiest way to send notifications!

.. image:: https://img.shields.io/travis/liiight/notifiers/master.svg?style=flat-square
    :target: https://travis-ci.org/liiight/notifiers
    :alt: Travis CI

.. image:: https://img.shields.io/codecov/c/github/liiight/notifiers/master.svg?style=flat-square
    :target: https://codecov.io/gh/liiight/notifiers
    :alt: Codecov

.. image:: https://img.shields.io/gitter/room/nwjs/nw.js.svg?style=flat-square
    :target: https://gitter.im/notifiers/notifiers

.. image:: https://img.shields.io/pypi/v/notifiers.svg?style=flat-square
    :target: https://pypi.python.org/pypi/notifiers
    :alt: PyPi version

.. image:: https://img.shields.io/pypi/pyversions/notifiers.svg?style=flat-square
    :target: https://pypi.org/project/notifiers
    :alt: Supported Python versions

.. image:: https://img.shields.io/pypi/l/notifiers.svg?style=flat-square
    :target: https://choosealicense.com/licenses
    :alt: License

.. image:: https://img.shields.io/pypi/status/notifiers.svg?style=flat-square
    :target: https://pypi.python.org/pypi/notifiers
    :alt: Status

See `Changelog <CHANGELOG.md>`_ for recent changes

Got an app or service and you want to enable your users to use notification with their provider of choice? You don't need to implement ש solution yourself, or use individual provider libs. A one stop shop for all notification providers with a unified and simple interface.
See below for a list of `Supported providers`_

Advantages
----------
- Spend your precious time on your own code base, instead of chasing down 3rd party provider APIs. That's what we're here for!
- With a minimal set of well known and stable dependencies (`requests <https://pypi.python.org/pypi/requests>`_, `jsonschema <https://pypi.python.org/pypi/jsonschema/2.6.0>`_ and `click <https://pypi.python.org/pypi/click/6.7>`_) you're better off than installing 3rd party SDKs.
- A unified interface means that you already support any new providers that will be added, no more work needed!
- Thorough testing means protection against any breaking API changes. We make sure your code your notifications will always get delivered!

Basic Usage
-----------

.. code:: python

    >>> from notifiers import get_notifier
    >>> p = get_notifier('pushover')
    >>> p.required
    ['user', 'message', 'token']
    >>> p.notify(user='foo', token='bar', message='test')
    <NotificationResponse,provider=Pushover,status=Success>

Setup
-----
Install with pip::

    pip install notifiers

Usage
-----

Get a notifier:

.. code:: python

    >>> import notifiers
    >>> pushover = notifiers.get_notifier('pushover')
    >>> pushover
    <NotificationProvider:[Pushover]>

Or:

.. code:: python

    >>> from notifiers.providers.pushover import Pushover
    >>> pushover = Pushover()

Send a notification:

.. code:: python

    >>> pushover.notify(token='TOKEN', title='Foo', message='Bar')

Get notifier metadata:

.. code:: python

    >>> pushover.metadata
    {'base_url': 'https://api.pushover.net/1/messages.json', 'site_url': 'https://pushover.net/', 'provider_name': 'pushover'}

Required arguments:

.. code:: python

    >>> pushover.required
    ['user', 'message', 'token']

All arguments (in JSON schema format):

.. code:: python

    >>> pushover.arguments
    {'user': {'oneOf': [{'type': 'array', 'items': {'type': 'string', 'title': 'the user/group key (not e-mail address) of your user (or you)'}, 'minItems': 1, 'uniqueItems': True}, {'type': 'string', 'title': 'the user/group key (not e-mail address) of your user (or you)'}]}, 'message': {'type': 'string', 'title': 'your message'}, 'title': {'type': 'string', 'title': "your message's title, otherwise your app's name is used"}, 'token': {'type': 'string', 'title': "your application's API token"}, 'device': {'oneOf': [{'type': 'array', 'items': {'type': 'string', 'title': "your user's device name to send the message directly to that device"}, 'minItems': 1, 'uniqueItems': True}, {'type': 'string', 'title': "your user's device name to send the message directly to that device"}]}, 'priority': {'oneOf': [{'type': 'number', 'minimum': -2, 'maximum': 2}, {'type': 'string'}], 'title': 'notification priority'}, 'url': {'type': 'string', 'format': 'uri', 'title': 'a supplementary URL to show with your message'}, 'url_title': {'type': 'string', 'title': 'a title for your supplementary URL, otherwise just the URL is shown'}, 'sound': {'type': 'string', 'title': "the name of one of the sounds supported by device clients to override the user's default sound choice"}, 'timestamp': {'type': 'integer', 'minimum': 0, 'title': "a Unix timestamp of your message's date and time to display to the user, rather than the time your message is received by our API"}, 'retry': {'type': 'integer', 'minimum': 30, 'title': 'how often (in seconds) the Pushover servers will send the same notification to the user. priority must be set to 2'}, 'expire': {'type': 'integer', 'maximum': 86400, 'title': 'how many seconds your notification will continue to be retried for. priority must be set to 2'}, 'callback': {'type': 'string', 'format': 'uri', 'title': 'a publicly-accessible URL that our servers will send a request to when the user has acknowledged your notification. priority must be set to 2'}, 'html': {'type': 'integer', 'minimum': 0, 'maximum': 1, 'title': 'enable HTML formatting'}}

View all available providers (continuously updated):

.. code:: python

    >>> notifiers.all_providers()
    ['pushover', 'simplepush', 'slack', 'email', 'gmail']

Some provider have default values set:

.. code:: python

    >>> e = notifiers.get_notifier('gmail')
    >>> e.defaults
    {'subject': "New email from 'notifiers'!", 'from': '<USER@LOCAL_HOST>', 'host': 'smtp.gmail.com', 'port': 587, 'tls': True, 'ssl': False, 'html': False}


Environment variables
---------------------

You can set environment variable to replace any argument that the notifier can use. The default syntax to follow is ``NOTIFIERS_[PROVIDER_NAME]_[ARGUMENT_NAME]``::

    export NOTIFIERS_PUSHOVER_TOKEN=FOO
    export NOTIFIERS_PUSHOVER_USER=BAR

Then you could just use:

.. code:: python

    >>> p.notify(message='message')

Note that you can also set ``MESSAGE`` in an environment variable.
You can also change the default prefix of ``NOTIFIERS_`` by pass the ``env_prefix`` argument on notify:

.. code:: python

    >>> p.notify(message='test', env_prefix='MY_OWN_PREFIX_')

Command Line Interface
----------------------

Notifiers come with CLI support::

    (notifiers_venv) ip-192-168-1-169:notifiers $ notifiers
    Usage: notifiers [OPTIONS] COMMAND [ARGS]...

      Notifiers CLI operation

    Options:
      --help  Show this message and exit.

    Commands:
      arguments  Shows the name and schema of all the...
      defaults   Shows the provider's defaults.
      metadata   Shows the provider's metadata.
      notify     Send a notification to a passed provider.
      providers  Shows all available providers
      required   Shows the required attributes of a provider.

Because of the dynamic nature of using different provider options, those are passed in a keyword=value style to the command as so::

    $ notifiers notify pushover token=foo user=bar message=test

Environment variables are used in the CLI as well. Explicitly passing keyword values takes precedence.
You can also pipe into the command::

    $ cat file.txt | notifiers notify pushover token=foo user=bar

You can set ``NOTIFIERS_DEFAULT_PROVIDER`` environment variable which will be used by the CLI. Combining that with the other required provider arguments can lead to very succinct commands::

    $ cat file.txt | notifiers notify

Note that unlike the other environment variables, you cannot change the prefix of this one.

Provider specific CLI
---------------------

Some providers have their own CLI commands::

    $ notifiers telegram --help
    Usage: core.py telegram [OPTIONS] COMMAND [ARGS]...

      Telegram specific commands

    Options:
      --help  Show this message and exit.

    Commands:
      updates  Get a list of active chat IDs for your bot.


Supported providers
-------------------

- `Pushover <https://pushover.net/>`_
- `SimplePush <https://simplepush.io/>`_
- `Slack <https://api.slack.com/>`_
- `Gmail <https://www.google.com/gmail/about/>`_
- Email (SMTP)
- `Telegram <https://telegram.org/>`_

In the near future
------------------

-  Many more providers
-  Docs!

Why python 3 only?
~~~~~~~~~~~~~~~~~~

I wanted to avoid the whole unicode issue fiasco if possible, but
there isn't a real constraint in adding python 2 support. If there’s an
overwhelming desire for this, i’ll do it. Probably.


