diff options
| -rw-r--r-- | README.rst | 84 | ||||
| -rw-r--r-- | doc/index.rst | 18 | ||||
| -rw-r--r-- | pushover.py | 17 |
3 files changed, 88 insertions, 31 deletions
@@ -1,5 +1,5 @@ -Python-pushover aims at being a comprehensive Python API implementation of the -`Pushover Notification Service`_ as documented here__. +``python-pushover`` aims at providing comprehensive Python bindings for the API +of the `Pushover Notification Service`_ as documented here__. .. _Pushover Notification Service: https://pushover.net/ .. __: https://pushover.net/api @@ -7,8 +7,11 @@ Python-pushover aims at being a comprehensive Python API implementation of the Installation ------------ -You can install python-pushover directly from Pypi_ with ``pip install -python-pushover`` or ``easy_install python-pushover``. +You can install python-pushover from Pypi_ with: + +.. code-block:: bash + + $ pip install python-pushover Or you can install it directly from GitHub_: @@ -16,14 +19,77 @@ Or you can install it directly from GitHub_: git clone https://github.com/Thibauth/python-pushover.git cd python-pushover - python setup.py install + pip install . .. _Pypi: https://pypi.python.org/pypi/python-pushover/ .. _GitHub: https://github.com/Thibauth/python-pushover -Documentation -------------- +Overview +-------- + +After being imported, the module must be initialized by calling the ``init`` +function with a valid application token. Thus, a typical use of the +``pushover`` module looks like this: + +.. code-block:: python + + from pushover import init, Client + + init("<token>") + client = Client("<user-key>").send_message("Hello!", title="Hello") + +You can also pass the ``api_token`` optional argument to ``Client`` to +initialize the module at the same time: + +.. code-block:: python + + from pushover import Client + + client = Client("<user-key>", api_token="<api-token>") + client.send_message("Hello!", title="Hello") + +Command line +~~~~~~~~~~~~ + +``python-pushover`` also comes with a command line utility ``pushover`` that +you can use as follows: + +.. code-block:: bash + + pushover --api-token <api-token> --user-key <user-key> "Hello!" + +Use ``pushover --help`` to see the list of available options. + +Configuration +~~~~~~~~~~~~~ + +Both the ``pushover`` module and the ``pushover`` command line utility support +reading arguments from a configuration file. + +The most basic configuration file looks like this: + +.. code-block:: ini + + [Default] + api_token=aaaaaa + user_key=xxxxxx + +You can have additional sections and specify a device as well: + +.. code-block:: ini + + [Sam-iPhone] + api_token=bbbbbb + user_key=yyyyyy + device=iPhone + +``python-pushover`` will attempt to read the configuration from +``~/.pushoverrc`` by default. The section to read can be specified by using the +``profile`` argument. + +API +--- -You can access the full documentation here__. +You can access the full API documentation here__. -.. __: http://pythonhosted.org/python-pushover +.. __: http://pythonhosted.org/python-pushover/#module-pushover diff --git a/doc/index.rst b/doc/index.rst index 5a0dffe..012cccc 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,23 +4,9 @@ Python-pushover documentation .. include:: ../README.rst :end-line: -7 -API documentation ------------------ +API +--- .. automodule:: pushover :members: - :undoc-members: :show-inheritance: - - -Command line -------------- - -The module can also be called from the command line for basic message sending. -The minimum invocation is: - -.. code-block:: bash - - python pushover.py --token <app-token> --client <client-id> "Hello!" - - diff --git a/pushover.py b/pushover.py index b4c788b..5a8ed4c 100644 --- a/pushover.py +++ b/pushover.py @@ -66,12 +66,12 @@ class InitError(Exception): class UserError(Exception): - """Exception which is raised when initializing a :class:Client class - without specifying a :attr:`user_key`. + """Exception which is raised when initializing a :class:`Client` class + without specifying a :attr:`user_key` attribute. """ def __str__(self): - return "No user_key provided." + return "No :attr:`user_key` attribute provided." class RequestError(Exception): @@ -163,9 +163,14 @@ class Client: user to whom messages will be sent when calling the :func:`send_message` method. - * ``user``: the Pushover's ID of the user. - * ``device``: if not ``None`` further ties the Client object to the - specified device. + * ``user_key``: the Pushover's ID of the user. + * ``device``: if provided further ties the Client object to the specified + device. + * ``api_token``: if provided and the module wasn't previously initialized, + call the :func:`init` function to initialize it. + * ``config_path``: configuration file from which to import unprovided + parameters. See Configuration_. + * ``profile``: section of the configuration file to import parameters from. """ def __init__(self, user_key=None, device=None, api_token=None, |