diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..cbbe3244 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,31 @@ +--- +name: "\U0001F41B Bug report" +about: Create a report to help us improve the SDK +title: '' +labels: bug +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of the bug. + +**To Reproduce** +The steps to reproduce the behavior + +**Expected Behavior** +A clear description of what you expected to happen. + +**Actual Behavior** +A clear description of what actually happened + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Versions** +* What version of the SDK are you using? +* What version of the language are you using? +* What platform are you using? (if applicable) + +**Additional context** +Add any other context about the problem here. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..ec4bb386 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..243d51b3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: "\U0001F680 Feature Request" +about: Suggest an idea for this SDK +title: '' +labels: enhancement +assignees: '' + +--- + +**Why is this feature valuable to you? Does it solve a problem you're having?** +A clear and concise description of why this feature is valuable. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. (if applicable) + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/question_help.md b/.github/ISSUE_TEMPLATE/question_help.md new file mode 100644 index 00000000..b5db6e69 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question_help.md @@ -0,0 +1,25 @@ +--- +name: "\U0001F4AC Questions / Help" +about: Get help with issues you are experiencing +title: '' +labels: help-wanted, question +assignees: '' + +--- + +**Before you start** +Have you checked StackOverflow, previous issues, and Dropbox Developer Forums for help? + +**What is your question?** +A clear and concise description the question. + +**Screenshots** +If applicable, add screenshots to help explain your question. + +**Versions** +* What version of the SDK are you using? +* What version of the language are you using? +* What platform are you using? (if applicable) + +**Additional context** +Add any other context about the question here. \ No newline at end of file diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..15f7908a --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,16 @@ +# To get started with Dependabot version updates, you'll need to specify which +# package ecosystems to update and where the package manifests are located. +# Please see the documentation for all configuration options: +# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates + +version: 2 +updates: + - package-ecosystem: "pip" # See documentation for possible values + directory: "/" # Location of package manifests + schedule: + interval: "daily" + + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "daily" \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..45b4cae8 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,18 @@ + + +## **Checklist** + + +**General Contributing** +- [ ] Have you read the Code of Conduct and signed the [CLA](https://opensource.dropbox.com/cla/)? + +**Is This a Code Change?** +- [ ] Non-code related change (markdown/git settings etc) +- [ ] SDK Code Change +- [ ] Example/Test Code Change + +**Validation** +- [ ] Does `tox` pass? +- [ ] Do the tests pass? \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..0492b588 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,5 @@ +# Dropbox Code Of Conduct + +*Dropbox believes that an inclusive development environment fosters greater technical achievement. To encourage a diverse group of contributors we've adopted this code of conduct.* + +Please read the Official Dropbox [Code of Conduct](https://opensource.dropbox.com/coc/) before contributing. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..e1ad63af --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contributing to the Dropbox SDK for Python +We value and rely on the feedback from our community. This comes in the form of bug reports, feature requests, and general guidance. We welcome your issues and pull requests and try our hardest to be timely in both response and resolution. Please read through this document before submitting issues or pull requests to ensure we have the necessary information to help you resolve your issue. + +## Filing Bug Reports +You can file a bug report on the [GitHub Issues][issues] page. + +1. Search through existing issues to ensure that your issue has not been reported. If it is a common issue, there is likely already an issue. + +2. Please ensure you are using the latest version of the SDK. While this may be a valid issue, we only will fix bugs affecting the latest version and your bug may have been fixed in a newer version. + +3. Provide as much information as you can regarding the language version, SDK version, and any other relevant information about your environment so we can help resolve the issue as quickly as possible. + +## Submitting Pull Requests + +We are more than happy to recieve pull requests helping us improve the state of our SDK. You can open a new pull request on the [GitHub Pull Requests][pr] page. + +1. Please ensure that you have read the [License][license], [Code of Conduct][coc] and have signed the [Contributing License Agreement (CLA)][cla]. + +2. Please add tests confirming the new functionality works. Pull requests will not be merged without passing continuous integration tests unless the pull requests aims to fix existing issues with these tests. + +## Updating Generated Code + +Generated code can be updated by running the following code: + +``` +$ pip install -r requirements.txt +$ git submodule init +$ git submodule update --remote --recursive +$ python generate_base_client.py +``` + +Note: Stone updates must be made by updating `requirements.txt` as it is no longer a submodule. + +## Testing the Code + +We use the [`tox`](https://tox.readthedocs.org/) package to run tests. To install and run the unit tests, you can use: + +``` +$ pip install tox +$ tox +``` + +Or if you would like to specify a specific target to run you can run this: + +``` +$ tox -e {TARGET} +``` + +If you want to run the integration tests, you can use the following: + +``` +$ export DROPBOX_REFRESH_TOKEN={fill in refresh token} +$ export DROPBOX_APP_KEY={fill in app key} +$ export DROPBOX_APP_SECRET={fill in app secret} +$ export DROPBOX_TEAM_TOKEN={fill in team token} +$ export DROPBOX_TOKEN={fill in access token} +$ tox -e test_integration +``` +Note: If you do not have all of these tokens available, we run integration tests as a part of pull request validation and you are able to rely on those if you are unable to obtain yourself. + +We do recommend developing in a virtual environment in order to ensure you have a clean testing environment. + +[issues]: https://github.com/dropbox/dropbox-sdk-python/issues +[pr]: https://github.com/dropbox/dropbox-sdk-python/pulls +[coc]: https://github.com/dropbox/dropbox-sdk-python/blob/master/CODE_OF_CONDUCT.md +[license]: https://github.com/dropbox/dropbox-sdk-python/blob/master/LICENSE +[cla]: https://opensource.dropbox.com/cla/ \ No newline at end of file diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 66be6a4b..00000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,57 +0,0 @@ -Contributing -============ - -Contributions are more than welcome and we encourage people to help us make our SDKs better. - - -Documentation -------------- - -Documentation can be compiled by running ``make html`` from the ``docs`` -folder. After compilation, open ``docs/_build/html/index.html``. Alternatively, -you can read a hosted version from `Read the Docs `_. - -Updating API specification --------------------------- - -A good amount of this SDK is generated using `Stone -`_. We use git submodules to pin to a -specific version of `Stone` since it's under active development, and we also -pin to a version of our `API spec -`_. - -To prepare the repo for generation, run these commands after cloning: - -.. code-block:: console - - $ git submodule init - $ git submodule update - -You can run ``git pull`` within these sub repositories to update the pinned -version. - -Now, run the included script: - -.. code-block:: console - - $ ./generate_base_client.py - -Testing -------- - -We use the `tox `_ package to run tests in Python -2 and 3. To install, use :code:`pip install tox`. Once installed, run `tox` from the -root directory. You'll need to specify a working Dropbox OAuth2 token: - -.. code-block:: console - - $ DROPBOX_TOKEN=YOUR_TOKEN tox -- -k "'not test_team'" - -Note that we skip ``test_team`` which requires a team token with `Member File Access -`_. -To test this functionality, specify a ``DROPBOX_TEAM_TOKEN`` environment -variable. - -.. code-block:: console - - $ DROPBOX_TOKEN=... DROPBOX_TEAM_TOKEN=... tox \ No newline at end of file diff --git a/LICENSE b/LICENSE index 3e2fc660..9f5dd937 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2015-2017 Dropbox Inc., http://www.dropbox.com/ +Copyright (c) 2020 Dropbox Inc., http://www.dropbox.com/ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -17,4 +17,4 @@ Copyright (c) 2015-2017 Dropbox Inc., http://www.dropbox.com/ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION - WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/README.rst b/README.rst index 07eb28ba..e8a3e916 100644 --- a/README.rst +++ b/README.rst @@ -1,39 +1,23 @@ -Dropbox Python SDK -================== - -.. image:: https://travis-ci.org/dropbox/dropbox-sdk-python.svg?branch=master - :target: https://travis-ci.org/dropbox/dropbox-sdk-python - -.. image:: https://readthedocs.org/projects/dropbox-sdk-python/badge/?version=stable - :target: https://dropbox-sdk-python.readthedocs.org/en/stable/ - :alt: [Latest Release Documentation] - -.. image:: https://img.shields.io/pypi/v/dropbox.svg - :target: https://pypi.python.org/pypi/dropbox - :alt: [Latest Release Version] - -.. image:: https://img.shields.io/pypi/l/dropbox.svg - :target: http://opensource.org/licenses/MIT - :alt: [Latest Release License] +.. image:: https://cfl.dropboxstatic.com/static/images/sdk/python_banner.png + :target: https://github.com/dropbox/dropbox-sdk-python .. image:: https://img.shields.io/pypi/pyversions/dropbox.svg :target: https://pypi.python.org/pypi/dropbox - :alt: [Latest Release Supported Python Versions] -.. image:: https://img.shields.io/pypi/implementation/dropbox.svg +.. image:: https://img.shields.io/pypi/v/dropbox.svg :target: https://pypi.python.org/pypi/dropbox - :alt: [Latest Release Supported Python Implementations] -.. image:: https://img.shields.io/pypi/status/dropbox.svg - :target: https://pypi.python.org/pypi/dropbox - :alt: [Latest Release Development Stage] +.. image:: https://codecov.io/gh/dropbox/dropbox-sdk-python/branch/master/graph/badge.svg + :target: https://codecov.io/gh/dropbox/dropbox-sdk-python + +The offical Dropbox SDK for Python. -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 `_. +Documentation can be found on `Read The Docs`_. Installation ------------- +============ -Create an app at https://dropbox.com/developers/apps +Create an app via the `Developer Console`_. Install via `pip `_: @@ -49,30 +33,41 @@ Install from source: $ cd dropbox-sdk-python $ python setup.py install -After installation, to get started, follow one of our examples or read the documentation on `Read the Docs `_. - -Authentication --------------- - -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 -token for your own Dropbox account for development. You can also find a variety of examples outlining different authorization flows under: +After installation, follow one of our `Examples`_ or read the documentation on `Read The Docs`_. -`example/oauth `_ +You can also view our `OAuth Guide`_. -You can also view our OAuth `guide `_ +Examples +======== -Example Applications --------------------- +We provide `Examples`_ to help get you started with a lot of the basic functionality in the SDK. -- `updown `_ - A sample application that demonstrates simple file upload and download +- **OAuth** + - `Commandline OAuth Basic `_ - Shows a simple example of commandline oauth (no redirect). + - `Commandline OAuth Scopes `_ - Shows a simple example of commandline oauth using scopes. + - `Commandline OAuth PKCE `_ - Shows a simple example of commandline oauth using PKCE. +- **Other Examples** + - `Updown `_ - Sample application that uploads the contents of your ``Downloads`` folder to Dropbox. + - `Backup and Restore `_ - Sample application that shows how you can backup a file and restore previous versions if the file was modified/corrupted in any way. -Contributing ------------- +Getting Help +============ -Contributions to this SDK are always welcome and encouraged! +If you find a bug, please see `CONTRIBUTING.md`_ for information on how to report it. -See the `CONTRIBUTING `_ doc for more information +If you need help that is not specific to this SDK, please reach out to `Dropbox Support`_. License -------- -MIT - See the `LICENSE `_ for more information +======= + +This SDK is distributed under the MIT license, please see `LICENSE`_ for more information. + +.. _logo: {logo_link} +.. _repo: https://github.com/dropbox/dropbox-sdk-python +.. _`Read The Docs`: http://dropbox-sdk-python.readthedocs.org +.. _`Examples`: https://github.com/dropbox/dropbox-sdk-python/tree/master/example +.. _LICENSE: https://github.com/dropbox/dropbox-sdk-python/blob/master/LICENSE +.. _CONTRIBUTING.md: https://github.com/dropbox/dropbox-sdk-python/blob/master/CONTRIBUTING.md +.. _Developer Console: https://dropbox.com/developers/apps +.. _OAuth Guide: https://www.dropbox.com/lp/developers/reference/oauth-guide +.. _`Dropbox Support`: https://www.dropbox.com/developers/contact \ No newline at end of file