Skip to content

Commit 4471b7e

Browse files
rogebrdrogebrd
authored
Update Readme (#189)
* Update Readme * Add Contributing and License * Fix commandline oauth examples
1 parent cc8dbb7 commit 4471b7e

File tree

5 files changed

+174
-76
lines changed

5 files changed

+174
-76
lines changed

‎CONTRIBUTING.rst‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
Contributing
2+
============
3+
4+
Contributions are more than welcome and we encourage people to help us make our SDKs better.
5+
6+
7+
Documentation
8+
-------------
9+
10+
Documentation can be compiled by running ``make html`` from the ``docs``
11+
folder. After compilation, open ``docs/_build/html/index.html``. Alternatively,
12+
you can read a hosted version from `Read the Docs <https://dropbox-sdk-python.readthedocs.org/en/stable/>`_.
13+
14+
Updating API specification
15+
--------------------------
16+
17+
A good amount of this SDK is generated using `Stone
18+
<https://www.github.com/dropbox/stone>`_. We use git submodules to pin to a
19+
specific version of `Stone` since it's under active development, and we also
20+
pin to a version of our `API spec
21+
<https://www.github.com/dropbox/dropbox-api-spec>`_.
22+
23+
To prepare the repo for generation, run these commands after cloning:
24+
25+
.. code-block:: console
26+
27+
$ git submodule init
28+
$ git submodule update
29+
30+
You can run ``git pull`` within these sub repositories to update the pinned
31+
version.
32+
33+
Now, run the included script:
34+
35+
.. code-block:: console
36+
37+
$ ./generate_base_client.py
38+
39+
Testing
40+
-------
41+
42+
We use the `tox <https://tox.readthedocs.org/>`_ package to run tests in Python
43+
2 and 3. To install, use :code:`pip install tox`. Once installed, run `tox` from the
44+
root directory. You'll need to specify a working Dropbox OAuth2 token:
45+
46+
.. code-block:: console
47+
48+
$ DROPBOX_TOKEN=YOUR_TOKEN tox -- -k "'not test_team'"
49+
50+
Note that we skip ``test_team`` which requires a team token with `Member File Access
51+
<https://www.dropbox.com/developers/documentation/http/teams#teams-member-file-access>`_.
52+
To test this functionality, specify a ``DROPBOX_TEAM_TOKEN`` environment
53+
variable.
54+
55+
.. code-block:: console
56+
57+
$ DROPBOX_TOKEN=... DROPBOX_TEAM_TOKEN=... tox

‎README.rst‎

Lines changed: 19 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Dropbox for Python
1+
Dropbox Python SDK
22
==================
33

44
.. image:: https://travis-ci.org/dropbox/dropbox-sdk-python.svg?branch=master
@@ -28,13 +28,13 @@ Dropbox for Python
2828
:target: https://pypi.python.org/pypi/dropbox
2929
:alt: [Latest Release Development Stage]
3030

31-
A Python SDK for integrating with the Dropbox API v2. Compatible with Python
32-
2.7 and 3.4+. Documentation is available on `Read the Docs
33-
<http://dropbox-sdk-python.readthedocs.org/>`_.
31+
A Python SDK for integrating with the Dropbox API v2. Compatible with Python 2.7 and 3.4+. Documentation is available on `Read the Docs <http://dropbox-sdk-python.readthedocs.org/>`_.
3432

3533
Installation
3634
------------
3735

36+
Create an app at https://dropbox.com/developers/apps
37+
3838
Install via `pip <https://pip.pypa.io/>`_:
3939

4040
.. code-block:: console
@@ -49,81 +49,29 @@ Install from source:
4949
$ cd dropbox-sdk-python
5050
$ python setup.py install
5151
52-
After installation, to get started, open a Python console:
53-
54-
.. code-block:: pycon
55-
56-
>>> import dropbox
57-
>>> dbx = dropbox.Dropbox("YOUR_ACCESS_TOKEN")
58-
>>> dbx.users_get_current_account()
59-
60-
Creating an Application
61-
-----------------------
62-
63-
You need to create an Dropbox Application to make API requests.
64-
65-
- Go to https://dropbox.com/developers/apps.
52+
After installation, to get started, follow one of our examples or read the documentation on `Read the Docs <http://dropbox-sdk-python.readthedocs.org/>`_.
6653

67-
Obtaining an Access Token
68-
-------------------------
54+
Authentication
55+
--------------
6956

70-
All requests need to be made with an OAuth 2 access token. To get started, once
71-
you've created an app, you can go to the app's console and generate an access
72-
token for your own Dropbox account.
57+
All requests need to be made with an OAuth 2 access token. To get started, once you've created an app, you can go to the app's console and generate an access
58+
token for your own Dropbox account for development. You can also find a variety of examples outlining different authorization flows under:
7359

74-
Examples
75-
--------
60+
`example/oauth <http://github.com/dropbox/dropbox-sdk-python/tree/master/example/oauth/>`_
7661

77-
``example/updown.py`` demonstrates how to sync a local directory with a Dropbox.
7862

79-
Documentation
80-
-------------
81-
82-
Documentation can be compiled by running ``make html`` from the ``docs``
83-
folder. After compilation, open ``docs/_build/html/index.html``. Alternatively,
84-
you can read a hosted version from `Read the Docs`_.
85-
86-
Updating API specification
87-
--------------------------
88-
89-
A good amount of this SDK is generated using `Stone
90-
<https://www.github.com/dropbox/stone>`_. We use git submodules to pin to a
91-
specific version of `Stone` since it's under active development, and we also
92-
pin to a version of our `API spec
93-
<https://www.github.com/dropbox/dropbox-api-spec>`_.
94-
95-
To prepare the repo for generation, run these commands after cloning:
96-
97-
.. code-block:: console
63+
Example Applications
64+
--------------------
9865

99-
$ git submodule init
100-
$ git submodule update
66+
- `updown <http://github.com/dropbox/dropbox-sdk-python/tree/master/example/updown.py>`_ - A sample application that demonstrates simple file upload and download
10167

102-
You can run ``git pull`` within these sub repositories to update the pinned
103-
version.
104-
105-
Now, run the included script:
68+
Contributing
69+
------------
10670

107-
.. code-block:: console
71+
Contributions to this SDK are always welcome and encouraged!
10872

109-
$ ./generate_base_client.py
73+
See the `CONTRIBUTING <http://github.com/dropbox/dropbox-sdk-python/blob/master/CONTRIBUTING.rst>`_ doc for more information
11074

111-
Testing
75+
License
11276
-------
113-
114-
We use the `tox <https://tox.readthedocs.org/>`_ package to run tests in Python
115-
2 and 3. To install, use :code:`pip install tox`. Once installed, run `tox` from the
116-
root directory. You'll need to specify a working Dropbox OAuth2 token:
117-
118-
.. code-block:: console
119-
120-
$ DROPBOX_TOKEN=YOUR_TOKEN tox -- -k "'not test_team'"
121-
122-
Note that we skip ``test_team`` which requires a team token with `Member File Access
123-
<https://www.dropbox.com/developers/documentation/http/teams#teams-member-file-access>`_.
124-
To test this functionality, specify a ``DROPBOX_TEAM_TOKEN`` environment
125-
variable.
126-
127-
.. code-block:: console
128-
129-
$ DROPBOX_TOKEN=... DROPBOX_TEAM_TOKEN=... tox
77+
MIT - See the `LICENSE <http://github.com/dropbox/dropbox-sdk-python/blob/master/LICENSE>`_ for more information

‎example/oauth/commandline-oauth-pkce.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,12 @@
77
This example uses PKCE, a currently beta feature.
88
If you are interested in using this, please contact
99
Dropbox support
10+
11+
Populate your app key in order to run this locally
1012
'''
1113
APP_KEY = ""
1214

13-
auth_flow = DropboxOAuth2FlowNoRedirect(APP_KEY, pkce_method='S256', token_access_type='offline')
15+
auth_flow = DropboxOAuth2FlowNoRedirect(APP_KEY, use_pkce=True, token_access_type='offline')
1416

1517
authorize_url = auth_flow.start()
1618
print("1. Go to: " + authorize_url)
@@ -20,10 +22,10 @@
2022

2123
try:
2224
oauth_result = auth_flow.finish(auth_code)
23-
print(oauth_result)
2425
except Exception as e:
2526
print('Error: %s' % (e,))
2627
exit(1)
2728

2829
dbx = dropbox.Dropbox(oauth2_refresh_token=oauth_result.refresh_token, app_key=APP_KEY)
2930
dbx.users_get_current_account()
31+
print("Successfully set up client!")

‎example/oauth/commandline-oauth-scopes.py‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
#!/usr/bin/env python3
2+
3+
import dropbox
4+
from dropbox import DropboxOAuth2FlowNoRedirect
5+
6+
'''
7+
This example uses Scopes, a currently beta feature.
8+
If you are interested in using this, please contact
9+
Dropbox support
10+
11+
It goes through an example of requesting a starting scope,
12+
and requesting more throughout the process
13+
'''
14+
APP_KEY = ""
15+
APP_SECRET = ""
16+
17+
auth_flow = DropboxOAuth2FlowNoRedirect(APP_KEY,
18+
consumer_secret=APP_SECRET,
19+
token_access_type='offline',
20+
scope=['files.metadata.read'])
21+
22+
authorize_url = auth_flow.start()
23+
print("1. Go to: " + authorize_url)
24+
print("2. Click \"Allow\" (you might have to log in first).")
25+
print("3. Copy the authorization code.")
26+
auth_code = input("Enter the authorization code here: ").strip()
27+
28+
try:
29+
oauth_result = auth_flow.finish(auth_code)
30+
# Oauth token has files.metadata.read scope only
31+
assert oauth_result.scope == 'files.metadata.read'
32+
except Exception as e:
33+
print('Error: %s' % (e,))
34+
exit(1)
35+
36+
# If an application needs write scopes now we can request the new scope with the auth flow
37+
auth_flow2 = DropboxOAuth2FlowNoRedirect(APP_KEY,
38+
consumer_secret=APP_SECRET,
39+
token_access_type='offline',
40+
scope=['files.metadata.write'])
41+
42+
authorize_url = auth_flow2.start()
43+
print("1. Go to: " + authorize_url)
44+
print("2. Click \"Allow\" (you might have to log in first).")
45+
print("3. Copy the authorization code.")
46+
auth_code = input("Enter the authorization code here: ").strip()
47+
48+
try:
49+
oauth_result = auth_flow2.finish(auth_code)
50+
# Oauth token has files.metadata.write scope only
51+
assert oauth_result.scope == 'files.metadata.write'
52+
except Exception as e:
53+
print('Error: %s' % (e,))
54+
exit(1)
55+
56+
# If an application needs a new scope but wants to keep the existing scopes,
57+
# you can add include_granted_scopes parameter
58+
auth_flow3 = DropboxOAuth2FlowNoRedirect(APP_KEY,
59+
consumer_secret=APP_SECRET,
60+
token_access_type='offline',
61+
scope=['files.content.read', 'files.content.write'],
62+
include_granted_scopes='user')
63+
64+
authorize_url = auth_flow3.start()
65+
print("1. Go to: " + authorize_url)
66+
print("2. Click \"Allow\" (you might have to log in first).")
67+
print("3. Copy the authorization code.")
68+
auth_code = input("Enter the authorization code here: ").strip()
69+
70+
try:
71+
oauth_result = auth_flow3.finish(auth_code)
72+
print(oauth_result)
73+
# Oauth token has all granted user scopes
74+
assert 'files.metadata.write' in oauth_result.scope
75+
assert 'files.metadata.read' in oauth_result.scope
76+
assert 'files.content.read' in oauth_result.scope
77+
assert 'files.content.write' in oauth_result.scope
78+
print(oauth_result.scope) # Printing for example
79+
except Exception as e:
80+
print('Error: %s' % (e,))
81+
exit(1)
82+
83+
dbx = dropbox.Dropbox(oauth2_access_token=oauth_result.access_token,
84+
oauth2_access_token_expiration=oauth_result.expires_at,
85+
oauth2_refresh_token=oauth_result.refresh_token,
86+
app_key=APP_KEY,
87+
app_secret=APP_SECRET)
88+
print("Successfully set up client!")

‎example/oauth/commandline-oauth.py‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
import dropbox
44
from dropbox import DropboxOAuth2FlowNoRedirect
55

6+
'''
7+
This example walks through a basic oauth flow using the existing long-lived token type
8+
Populate your app key and app secret in order to run this locally
9+
'''
610
APP_KEY = ""
711
APP_SECRET = ""
812

@@ -16,11 +20,10 @@
1620

1721
try:
1822
oauth_result = auth_flow.finish(auth_code)
19-
print(oauth_result)
2023
except Exception as e:
2124
print('Error: %s' % (e,))
2225
exit(1)
2326

24-
dbx = dropbox.Dropbox(oauth2_access_token=oauth_result.access_token,
25-
app_key=APP_KEY, app_secret=APP_SECRET)
27+
dbx = dropbox.Dropbox(oauth2_access_token=oauth_result.access_token)
2628
dbx.users_get_current_account()
29+
print("Successfully set up client!")

0 commit comments

Comments
 (0)