Skip to content

Commit bce38f9

Browse files
aschuman0aschuman0
authored
7.0 docs update (#212)
1 parent c6d6073 commit bce38f9

File tree

4 files changed

+156
-74
lines changed

4 files changed

+156
-74
lines changed

‎README.rst‎

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ center messages, email, and SMS.
1010
Requirements
1111
============
1212

13-
Python 2.7, 3.6, 3.7, 3.8, or 3.9 is required. Other requirements can be found in requirements.txt.
13+
Python 3.6 or higher is required. Other requirements can be found in requirements.txt.
1414

1515
Questions
1616
=========
@@ -26,45 +26,49 @@ See the `full documentation for this library
2626
`Airship API Documentation
2727
<https://docs.airship.com/api/ua/>`_.
2828

29-
Simple iOS Push
30-
---------------
29+
Simple Push Notification
30+
-----------------------
3131

3232
>>> import urbanairship as ua
33-
>>> airship = ua.Airship('application_key', 'master_secret')
33+
>>> airship = ua.client.BasicAuthClient('application_key', 'master_secret')
3434
>>> push = airship.create_push()
35-
>>> push.audience = ua.or_(ua.alias('adam'), ua.ios_channel('some_ios_channel'))
36-
>>> push.notification = ua.notification(alert='Hello')
37-
>>> push.device_types = ua.device_types('ios')
35+
>>> push.audience = ua.all_
36+
>>> push.notification = ua.notification(alert='Hello, world!')
37+
>>> push.device_types = ua.device_types('ios', 'android')
3838
>>> push.send()
3939

40-
Broadcast to iOS and Android devices
41-
------------------------------------
40+
Using OAuth2 Authentication
41+
-------------------------
42+
>>> import urbanairship as ua
43+
>>> airship = ua.client.OAuthClient(
44+
... key='application_key',
45+
... client_id='client_id',
46+
... private_key='private_key',
47+
... scope=['push:write']
48+
... )
4249
>>> push = airship.create_push()
4350
>>> push.audience = ua.all_
44-
>>> push.notification = ua.notification(
45-
... ios=ua.ios(alert='Hello iOS'),
46-
... android=ua.android(alert='Hello Android'))
51+
>>> push.notification = ua.notification(alert='Hello, world!')
4752
>>> push.device_types = ua.device_types('ios', 'android')
4853
>>> push.send()
4954

50-
Sending a message center message to a single iOS device
51-
--------------------------------------------------------
55+
Sending a Message Center Message
56+
------------------------------
5257
>>> import urbanairship as ua
53-
>>> airship = ua.Airship('application_key', 'master_secret')
58+
>>> airship = ua.client.BasicAuthClient('application_key', 'master_secret')
5459
>>> push = airship.create_push()
55-
>>> push.audience = ua.ios_channel('some_ios_channel')
60+
>>> push.audience = ua.ios_channel('channel_id')
5661
>>> push.notification = ua.notification(alert='Hello')
5762
>>> push.device_types = ua.device_types('ios')
5863
>>> push.message = ua.message(
5964
... 'Hello, message center user',
6065
... '<html><h1>Hello!</h1><p>Goodbye.</p></html>')
6166
>>> push.send()
6267

63-
Web Push to a tag
64-
-----------------
65-
68+
Web Push to a Tag
69+
----------------
6670
>>> import urbanairship as ua
67-
>>> airship = ua.Airship('application_key', 'master_secret')
71+
>>> airship = ua.client.BasicAuthClient('application_key', 'master_secret')
6872
>>> push = airship.create_push()
6973
>>> push.audience = ua.tag('web_tag')
7074
>>> push.notification = ua.notification(alert='Hello')
@@ -74,6 +78,7 @@ Web Push to a tag
7478
History
7579
=======
7680

81+
* 7.0 Update to client classes and authentication methods
7782
* 6.3 Support for OAuth2 Authentication. Adds new clients module and class.
7883
* 6.0 Support for Bearer Token Authentication. Removes support for Python 2.
7984
* 5.0 Support for SMS and Email messages. See changelog for other updates.

‎docs/client.rst‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
Client Classes and Authentication
2+
********************************
3+
4+
The Airship Python Library supports multiple authentication methods through different client classes. Each client class inherits from :py:class:`BaseClient` and provides specific authentication functionality.
5+
6+
Base Client
7+
===========
8+
9+
.. autoclass:: urbanairship.client.BaseClient
10+
:members:
11+
:exclude-members: _request, request
12+
13+
Basic Authentication
14+
===================
15+
16+
The :py:class:`BasicAuthClient` is used for traditional key/secret authentication. This is the same as the deprecated `Airship` client class.
17+
18+
.. autoclass:: urbanairship.client.BasicAuthClient
19+
:members:
20+
:exclude-members: _request, request
21+
22+
Example usage:
23+
24+
.. code-block:: python
25+
26+
import urbanairship as ua
27+
airship = ua.client.BasicAuthClient('<app key>', '<master secret>')
28+
29+
# Create and send a push notification
30+
push = airship.create_push()
31+
push.audience = ua.all_
32+
push.notification = ua.notification(alert='Hello, world!')
33+
push.device_types = ua.device_types('ios', 'android')
34+
push.send()
35+
36+
Bearer Token Authentication
37+
=========================
38+
39+
The :py:class:`BearerTokenClient` is used when you have an Airship-generated bearer token. This is useful when you want to manage token refresh yourself or when using tokens from other sources.
40+
41+
.. autoclass:: urbanairship.client.BearerTokenClient
42+
:members:
43+
:exclude-members: _request, request
44+
45+
Example usage:
46+
47+
.. code-block:: python
48+
49+
import urbanairship as ua
50+
airship = ua.client.BearerTokenClient('<app key>', '<bearer token>')
51+
52+
# Create and send a push notification
53+
push = airship.create_push()
54+
push.audience = ua.all_
55+
push.notification = ua.notification(alert='Hello, world!')
56+
push.device_types = ua.device_types('ios', 'android')
57+
push.send()
58+
59+
OAuth2 Authentication
60+
====================
61+
62+
The :py:class:`OAuthClient` handles OAuth2 authentication using JWT assertions. It automatically manages token refresh and is recommended for production use.
63+
64+
.. autoclass:: urbanairship.client.OAuthClient
65+
:members:
66+
:exclude-members: _request, request, _update_session_oauth_token
67+
68+
Example usage:
69+
70+
.. code-block:: python
71+
72+
import urbanairship as ua
73+
74+
# Initialize with OAuth credentials
75+
airship = ua.client.OAuthClient(
76+
key='<app key>',
77+
client_id='<client id>',
78+
private_key='<private key>',
79+
scope=['push:write', 'channels:read'] # Optional scopes
80+
)
81+
82+
# Create and send a push notification
83+
push = airship.create_push()
84+
push.audience = ua.all_
85+
push.notification = ua.notification(alert='Hello, world!')
86+
push.device_types = ua.device_types('ios', 'android')
87+
push.send()
88+
89+
EU Data Center Support
90+
=====================
91+
92+
All client classes support the EU data center through the `location` parameter:
93+
94+
.. code-block:: python
95+
96+
# For EU data center
97+
eu_airship = ua.client.BasicAuthClient(
98+
key='<app key>',
99+
secret='<master secret>',
100+
location='eu'
101+
)

‎docs/index.rst‎

Lines changed: 16 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -16,47 +16,34 @@ Using the library
1616
==================
1717

1818
The library is intended to be used with the small footprint of a single
19-
import. To get started, import the package, and create an
20-
:py:class:`Airship` object representing a single Airship project.
19+
import. To get started, import the package, and create an appropriate client object
20+
representing a single Airship project.
2121

2222
.. code-block:: python
2323
2424
import urbanairship as ua
2525
airship = ua.client.BasicAuthClient('<app key>', '<master secret>')
2626
27-
push = airship.Push(airship=airship)
28-
push.audience = ua.ios_channel('074e84a2-9ed9-4eee-9ca4-cc597bfdbef3')
29-
push.notification = ua.notification(ios=ua.ios(alert='Hello from Python', badge=1))
30-
push.device_types = ua.device_types('ios')
27+
push = airship.create_push()
28+
push.audience = ua.all_
29+
push.notification = ua.notification(alert='Hello, world!')
30+
push.device_types = ua.device_types('ios', 'android')
3131
push.send()
3232
3333
The library uses `requests`_ for communication with the Airship API,
34-
providing connection pooling and strict SSL checking. The ``Airship``
35-
object is threadsafe, and can be instantiated once and reused in
36-
multiple threads.
34+
providing connection pooling and strict SSL checking. All client objects are
35+
threadsafe, and can be instantiated once and reused in multiple threads.
3736

38-
Authentication Clients
39-
----------------------
37+
Authentication
38+
-------------
4039

41-
The library supports authentication via 1 of 3 client classes:
40+
The library supports three authentication methods:
4241

43-
* BasicAuthClient - This is the same as the deprecated `Airship` client class for using Key/Secret authentication.
44-
* BearerTokenClient - This client takes a `token` argument with an Airship-generated bearer token in addition to the key and other configuration options.
45-
* OAuthClient - This client requests an OAuth bearer token using the `client_id` and JWT assertion and automatically refreshes tokens as needed from the Airship OAuth2 provider. Please see the OAuth2 section of the Airship API documentation for more on this authentication method. If you prefer to handle token refresh yourself, the `access_token` returned from the Airship OAuth2 proivder can be used with the `BearerTokenClient`.
42+
* Basic Authentication - Using app key and master secret
43+
* Bearer Token Authentication - Using app key and Airship-generated bearer token
44+
* OAuth2 Authentication - Using JWT assertions with automatic token refresh
4645

47-
More about these methods, including examples of instantiation can be found on the Airship docs site.
48-
49-
EU Base URL
50-
-----------
51-
52-
When creating an instance of ``urbanairship.Airship``, an optional argument
53-
may be added to specify use of Airship's EU data center. This is required for projects
54-
based in our EU data center. If no location argument is passed, the US data center will be used.
55-
56-
.. code-block:: python
57-
58-
import urbanairship as ua
59-
eu_airship = ua.Airship(key='<app_key>', secret='<master_secret>', location='eu')
46+
For more details on each authentication method, see the :doc:`client` documentation.
6047

6148
Logging
6249
-------
@@ -77,15 +64,6 @@ logging.
7764
7865
logging.getLogger('urbanairship').setLevel(logging.DEBUG)
7966
80-
As of Python 2.7, ``DeprecationWarning`` warnings are silenced by
81-
default. To enable them, use the ``warnings`` module:
82-
83-
.. code-block:: python
84-
85-
import warnings
86-
warnings.simplefilter('default')
87-
88-
8967
Exceptions
9068
==========
9169

@@ -112,6 +90,7 @@ Contents
11290
.. toctree::
11391
:maxdepth: 3
11492

93+
client
11594
push.rst
11695
devices.rst
11796
audience.rst

0 commit comments

Comments
 (0)