Package: drf_to_s3
drf-to-s3=========`Django REST Framework <http://django-rest-framework.org/>`__ interfacefor direct upload to S3. Designed for browser-based clients using `FineUploader <http://fineuploader.com/>`__ and API clients.Features--------Handles browser-based uploads~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1. Signs `policydocuments <http://docs.aws.amazon.com/AmazonS3/latest/dev/HTTPPOSTForms.html#HTTPPOSTConstructPolicy>`__for the `POSTAPI <http://docs.aws.amazon.com/AmazonS3/latest/dev/HTTPPOSTForms.html>`__.2. Provides an empty response to use as a success action redirect withold browsers (IE 9 and Android 2.3.x) which do not support the FileAPI, instead using a dynamically generated iframe.3. Provides a framework for your upload-complete callback, which shouldcopy the file to storage and take whatever other action is needed,such as creating model objects.See this `Fine Uploader blogpost <http://blog.fineuploader.com/2013/08/16/fine-uploader-s3-upload-directly-to-amazon-s3-from-your-browser/>`__for a long explanation of these responsibilities.Handles API-client uploads~~~~~~~~~~~~~~~~~~~~~~~~~~The library provides a streamlined interface suitable for programmaticuploads by non-browser-based API clients:1. Provides signed URIs for the `REST PUT ObjectAPI <http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html>`__.2. Provides an upload-complete callback.Designed for security---------------------This library's design goal is to be secure by default. To that end, itmakes two recommendations:1. Send your uploads to an "uploads" bucket, and make them private. Thissimplifies the namespacing used to segregate uploads by user, anddiscourages read-write ACLs.2. Create an account which has the minimum permission required on youruploads bucket, and use that account to sign users' policy documents.3. Move the files into a storage bucket during the completion callback,with either private or read-only ACLs. The library provides a viewand serializer you can subclass to accomplish this easily.4. Use Fine Uploader's```objectProperties.key`` <http://docs.fineuploader.com/api/options-s3.html#objectProperties.key>`__property to incorporate the username as a prefix in the key. If youdon't already have access to the username in the client, you can usethe library's middleware to set a cookie with the prefix.5. Be sure to specify an ``https`` endpoint url when you configure FineUploader.6. Set a one-day expiration policy which automatically deletes stale,incomplete uploads. This step is mainly to save you money.If you're willing to take what hopefully is sensible-sounding advice, goon to the next section. If you want to know *why*, see the discussion inSECURITY.md.If you don't want to use it as designed, you can use the utility classesand naive serializers to create your own components.Status------This project is functional pre-alpha. Most significantly it needs betterdocumentation.|Build Status|Installation------------Requires `Django REST Framework <http://django-rest-framework.org/>`__,a great toolkit for building Web APIs in Django.::pip install drf_to_s3This will install the remaining dependencies:`boto <https://github.com/boto/boto>`__, and`querystring\_parser <https://github.com/bernii/querystring-parser>`__which handles nested keys within ``uploadSuccess.params``.How to use----------1. Include ``drf_to_s3.urls`` in your site (or if you prefer, redefinethem).2. If you want to use nested dictionaries in your success callback, youmust disable Django REST Framework's options for overriding the HTTPmethod and content. You probably aren't using these options, and they`interfere with the view's use of a custom formparser <https://github.com/tomchristie/django-rest-framework/issues/1346>`__.::REST_FRAMEWORK = {'FORM_METHOD_OVERRIDE': None,'FORM_CONTENT_OVERRIDE': None,}3. Create an temporary bucket for uploads.4. Set the CORS policy on that bucket.5. Create a user which only has PutObject access to that bucket.6. Add Fine Uploader to your front end.7. Configure Fine Uploader:-  Keys-  ``request.key``-  access keyLimitations-----------Users must be logged in to upload. Anonymous uploads currently aren'tsupported.Deletes during upload are not supported, but would be easy to add.Contributing-------------  Issue Tracker: https://github.com/bodylabs/drf-to-s3/issues-  Source Code: https://github.com/bodylabs/drf-to-s3Unit tests:~~~~~~~~~~~::rake create_venv. .venv/bin/activaterake installrake testUnit tests against S3:~~~~~~~~~~~~~~~~~~~~~~1. If it's not already installed on your system, install ``foreman``.You can get it from RubyGems with ``gem install foreman`` or install`Heroku Toolbelt <https://toolbelt.heroku.com/>`__.2. Create an S3 bucket to use for testing.3. Create a ``.env`` file at the project root with the following threelines:-  AWS\_TEST\_BUCKET=...-  AWS\_ACCESS\_KEY\_ID=...-  AWS\_SECRET\_ACCESS\_KEY=...4. Run the tests:::source venv/bin/activateforeman run drf_to_s3/runtests/runtests.pyIntegration tests:~~~~~~~~~~~~~~~~~~1. Install ``foreman``, create an S3 bucket, and set up your ``.env``file as described above.2. Install Node, NPM, the build dependences for Fine Uploader, andChromium Driver:::rake install_integration3. If you're not using Mac OS / Homebrew, you need to install ChromiumDriver some other way.4. Choose a version of Fine Uploader to test:::rake install_fine5. Build it into ``drf_to_s3/integration/static``:::rake install_fine[4.2.2]6. Run the tests::rake integrationRunning integration tests on Sauce Labs:~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1. Create a `Sauce Labs <https://saucelabs.com/>`__ account.2. In .env, set ``SAUCE_USERNAME`` and ``SAUCE_ACCESS_KEY``.3. Install `SauceConnect <http://saucelabs.com/downloads/Sauce-Connect-latest.zip>`__.4. Start Sauce Connect:foreman run sh -c 'java -jar~/code/Sauce-Connect-latest/Sauce-Connect.jar:math:`SAUCE_USERNAME `\ SAUCE\_ACCESS\_KEY'5. Run the tests:WITH\_SAUCE=1 rake integrationBuilding the package for PyPi:~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~This readme is written in Markdown, so there are dependencies forconverting it to reStructuredText. You only need this if you want togenerate the PyPi package with long\_description intact. Without it,you'll just get a warning.::rake install_distIf you're not using MacOS / Homebrew, you'll need to install Pandoc someother way.License-------This project is licensed under the MIT license... |Build Status| image:: https://travis-ci.org/bodylabs/drf-to-s3.png?branch=master:target: https://travis-ci.org/bodylabs/drf-to-s3