Skip to content

Commit 2ffdd06

Browse files
ticosaxticosax
committed
enable coloration and enhance reStructeredText usage.
1 parent 5f69325 commit 2ffdd06

File tree

1 file changed

+54
-49
lines changed

1 file changed

+54
-49
lines changed

‎README.rst‎

Lines changed: 54 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,41 @@
11
django-push-notifications
22
=========================
3-
43
.. image:: https://api.travis-ci.org/jleclanche/django-push-notifications.png
54
:target: https://travis-ci.org/jleclanche/django-push-notifications
65

76
A minimal Django app that implements Device models that can send messages through APNS and GCM.
87

9-
The app implements two models: GCMDevice and APNSDevice. Those models share the same attributes:
10-
- name (optional): A name for the device.
11-
- is_active (default True): A boolean that determines whether the device will be sent notifications.
12-
- user (optional): A foreign key to auth.User, if you wish to link the device to a specific user.
13-
- device_id (optional): A UUID for the device obtained from Android/iOS APIs, if you wish to uniquely identify it.
14-
- registration_id (required): The GCM registration id or the APNS token for the device.
8+
The app implements two models: ``GCMDevice`` and ``APNSDevice``. Those models share the same attributes:
9+
- ``name`` (optional): A name for the device.
10+
- ``is_active`` (default True): A boolean that determines whether the device will be sent notifications.
11+
- ``user`` (optional): A foreign key to auth.User, if you wish to link the device to a specific user.
12+
- ``device_id`` (optional): A UUID for the device obtained from Android/iOS APIs, if you wish to uniquely identify it.
13+
- ``registration_id`` (required): The GCM registration id or the APNS token for the device.
1514

1615

1716
The app also implements an admin panel, through which you can test single and bulk notifications. Select one or more
1817
GCM or APNS devices and in the action dropdown, select "Send test message" or "Send test message in bulk", accordingly.
1918
Note that sending a non-bulk test message to more than one device will just iterate over the devices and send multiple
2019
single messages.
2120

22-
2321
Dependencies
2422
------------
2523
Django 1.8 is required. Support for older versions is available in the release 1.2.1.
2624

2725
Tastypie support should work on Tastypie 0.11.0 and newer.
2826

29-
3027
Setup
3128
-----
32-
You can install the library directly from pypi using pip::
29+
You can install the library directly from pypi using pip:
30+
31+
.. code-block:: shell
3332
3433
$ pip install django-push-notifications
3534
3635
37-
Edit your settings.py file::
36+
Edit your settings.py file:
37+
38+
.. code-block:: python
3839
3940
INSTALLED_APPS = (
4041
...
@@ -46,33 +47,37 @@ Edit your settings.py file::
4647
"APNS_CERTIFICATE": "/path/to/your/certificate.pem",
4748
}
4849
49-
Note: If you are planning on running your project with `DEBUG=True`, then make sure you have set the
50-
*development* certificate as your `APNS_CERTIFICATE`. Otherwise the app will not be able to connect to the correct host.
50+
.. note::
51+
If you are planning on running your project with ``DEBUG=True``, then make sure you have set the
52+
*development* certificate as your ``APNS_CERTIFICATE``. Otherwise the app will not be able to connect to the correct host. See settings_ for details.
5153

52-
You can learn more about APNS certificates here: https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ProvisioningDevelopment.html
54+
You can learn more about APNS certificates `here <https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ProvisioningDevelopment.html>`_.
5355

54-
Native Django migrations are in use. `manage.py migrate` will install and migrate all models.
56+
Native Django migrations are in use. ``manage.py migrate`` will install and migrate all models.
5557

58+
.. _settings:
5659

5760
Settings list
5861
-------------
59-
All settings are contained in a PUSH_NOTIFICATIONS_SETTINGS dict.
62+
All settings are contained in a ``PUSH_NOTIFICATIONS_SETTINGS`` dict.
6063

61-
In order to use GCM, you are required to include GCM_API_KEY.
62-
For APNS, you are required to include APNS_CERTIFICATE.
64+
In order to use GCM, you are required to include ``GCM_API_KEY``.
65+
For APNS, you are required to include ``APNS_CERTIFICATE``.
6366

64-
- APNS_CERTIFICATE: Absolute path to your APNS certificate file. Certificates with passphrases are not supported.
65-
- GCM_API_KEY: Your API key for GCM.
66-
- APNS_HOST: The hostname used for the APNS sockets. When DEBUG=True, this defaults to gateway.sandbox.push.apple.com. When DEBUG=False, this defaults to gateway.push.apple.com.
67-
- APNS_PORT: The port used along with APNS_HOST. Defaults to 2195.
68-
- GCM_POST_URL: The full url that GCM notifications will be POSTed to. Defaults to https://android.googleapis.com/gcm/send.
69-
- GCM_MAX_RECIPIENTS: The maximum amount of recipients that can be contained per bulk message. If the registration_ids list is larger than that number, multiple bulk messages will be sent. Defaults to 1000 (the maximum amount supported by GCM).
67+
- ``APNS_CERTIFICATE``: Absolute path to your APNS certificate file. Certificates with passphrases are not supported.
68+
- ``GCM_API_KEY``: Your API key for GCM.
69+
- ``APNS_HOST``: The hostname used for the APNS sockets.
70+
- When ``DEBUG=True``, this defaults to ``gateway.sandbox.push.apple.com``.
71+
- When ``DEBUG=False``, this defaults to ``gateway.push.apple.com``.
72+
- ``APNS_PORT``: The port used along with APNS_HOST. Defaults to 2195.
73+
- ``GCM_POST_URL``: The full url that GCM notifications will be POSTed to. Defaults to https://android.googleapis.com/gcm/send.
74+
- ``GCM_MAX_RECIPIENTS``: The maximum amount of recipients that can be contained per bulk message. If the ``registration_ids`` list is larger than that number, multiple bulk messages will be sent. Defaults to 1000 (the maximum amount supported by GCM).
7075

7176
Sending messages
7277
----------------
7378
GCM and APNS services have slightly different semantics. The app tries to offer a common interface for both when using the models.
7479

75-
::
80+
.. code-block:: python
7681
7782
from push_notifications.models import APNSDevice, GCMDevice
7883
@@ -92,14 +97,14 @@ GCM and APNS services have slightly different semantics. The app tries to offer
9297
device.send_message(None, badge=5) # No alerts but with badge.
9398
device.send_message(None, badge=1, extra={"foo": "bar"}) # Silent message with badge and added custom data.
9499
95-
Note that APNS does not support sending payloads that exceed 2048 bytes (increased from 256 in 2014).
96-
The message is only one part of the payload, if
97-
once constructed the payload exceeds the maximum size, an APNSDataOverflow exception will be raised before anything is sent.
98-
100+
.. note::
101+
APNS does not support sending payloads that exceed 2048 bytes (increased from 256 in 2014).
102+
The message is only one part of the payload, if
103+
once constructed the payload exceeds the maximum size, an ``APNSDataOverflow`` exception will be raised before anything is sent.
99104

100105
Sending messages in bulk
101106
------------------------
102-
::
107+
.. code-block:: python
103108
104109
from push_notifications.models import APNSDevice, GCMDevice
105110
@@ -111,29 +116,28 @@ bulk notifications instead of single ones.
111116

112117
Administration
113118
--------------
119+
114120
APNS devices which are not receiving push notifications can be set to inactive by two methods. The web admin interface for
115-
APNS devices has a "prune devices" option. Any selected devices which are not receiving notifications will be set to inactive(*).
116-
There is also a management command to prune all devices failing to receive notifications::
121+
APNS devices has a "prune devices" option. Any selected devices which are not receiving notifications will be set to inactive [1]_.
122+
There is also a management command to prune all devices failing to receive notifications:
123+
124+
.. code-block:: shell
117125
118-
python manage.py prune_devices
126+
$ python manage.py prune_devices
119127
120128
This removes all devices which are not receiving notifications.
121129

122130
For more information, please refer to the APNS feedback service_.
123131

124132
.. _service: https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/CommunicatingWIthAPS.html
125133

126-
(*)Any devices which are not selected, but are not receiving notifications will not be deactivated on a subsequent call to "prune devices" unless another
127-
attempt to send a message to the device fails after the call to the feedback service.
128-
129134
Exceptions
130135
----------
131136

132-
- NotificationError(Exception): Base exception for all notification-related errors.
133-
- gcm.GCMError(NotificationError): An error was returned by GCM. This is never raised when using bulk notifications.
134-
- apns.APNSError(NotificationError): Something went wrong upon sending APNS notifications.
135-
- apns.APNSDataOverflow(APNSError): The APNS payload exceeds its maximum size and cannot be sent.
136-
137+
- ``NotificationError(Exception)``: Base exception for all notification-related errors.
138+
- ``gcm.GCMError(NotificationError)``: An error was returned by GCM. This is never raised when using bulk notifications.
139+
- ``apns.APNSError(NotificationError)``: Something went wrong upon sending APNS notifications.
140+
- ``apns.APNSDataOverflow(APNSError)``: The APNS payload exceeds its maximum size and cannot be sent.
137141

138142
Tastypie support
139143
----------------
@@ -142,19 +146,20 @@ The app includes tastypie-compatible resources in push_notifications.api. These
142146
for more involved APIs.
143147
The following resources are available:
144148

145-
- APNSDeviceResource
146-
- GCMDeviceResource
147-
- APNSDeviceAuthenticatedResource
148-
- GCMDeviceAuthenticatedResource
149+
- ``APNSDeviceResource``
150+
- ``GCMDeviceResource``
151+
- ``APNSDeviceAuthenticatedResource``
152+
- ``GCMDeviceAuthenticatedResource``
149153

150154
The base device resources will not ask for authentication, while the authenticated ones will link the logged in user to
151155
the device they register.
152-
Subclassing the authenticated resources in order to add a SameUserAuthentication and a user ForeignKey is recommended.
153-
154-
When registered, the APIs will show up at <api_root>/device/apns and <api_root>/device/gcm, respectively.
156+
Subclassing the authenticated resources in order to add a ``SameUserAuthentication`` and a user ``ForeignKey`` is recommended.
155157

158+
When registered, the APIs will show up at ``<api_root>/device/apns`` and ``<api_root>/device/gcm``, respectively.
156159

157160
Python 3 support
158161
----------------
159162

160-
django-push-notifications is fully compatible with Python 3.
163+
``django-push-notifications`` is fully compatible with Python 3.
164+
165+
.. [1] Any devices which are not selected, but are not receiving notifications will not be deactivated on a subsequent call to "prune devices" unless another attempt to send a message to the device fails after the call to the feedback service.

0 commit comments

Comments
 (0)