Metadata-Version: 1.1
Name: resumable
Version: 0.1.1
Summary: Python client for upload to a server supporting resumable.js
Home-page: https://acroz.github.com/acroz/resumable.py
Author: Andrew Crozier
Author-email: wacrozier@gmail.com
License: MIT
Description: resumable.py
        ============
        
        .. image:: https://travis-ci.org/acroz/resumable.py.svg?branch=master
            :target: https://travis-ci.org/acroz/resumable.py
        .. image:: https://coveralls.io/repos/github/acroz/resumable.py/badge.svg?branch=master
            :target: https://coveralls.io/github/acroz/resumable.py?branch=master
        
        resumable.py provides chunked uploading of files to a compatible server,
        emulating the popular resumable.js_ JavaScript library.
        
        Installation
        ------------
        
        resumable.py can be installed from PyPI with ``pip``:
        
        .. code-block:: bash
        
            $ pip install resumable
        
        Usage
        -----
        
        Construct a ``Resumable`` object with the URL of the upload target server, and
        use ``add_file()`` to queue files for upload. It's recommended to use it as a
        context manager:
        
        .. code-block:: python
        
            from resumable import Resumable
        
            with Resumable('https://example.com/upload') as session:
                session.add_file('my_file.dat')
        
        You can queue mutiple files for upload in a single session, and the ``with``
        block will not complete until the upload is finished (or an exception is
        raised).
        
        It's also possible to use a ``Resumable`` session without a ``with`` block, and
        manually ``join()`` the session:
        
        .. code-block:: python
        
            session = Resumable('https://example.com/upload')
            session.add_file('my_file.dat')
            do_something_else()
            session.join()
        
        Backend
        +++++++
        
        resumable.py handles most of the logic needed for resumable file uploads on the
        client side, but the files still need to be reassembled from chunks on the
        server side, as in resumable.js_. For details on how to set up a compatible
        backend, please see the resumable.js_ documentation or the backend samples
        `on GitHub <resumable.js-samples>`_.
        
        Configuration
        +++++++++++++
        
        resumable.py supports a subset of the options provided by resumable.js_:
        
        * ``target`` The target URL for the multipart POST request (required)
        * ``chunk_size`` The size in bytes of each uploaded chunk of data (default:
          ``1*1024*1024``)
        * ``simultaneous_uploads`` Number of simultaneous uploads (default: ``3``)
        * ``headers`` Extra headers to include in the multipart POST with data
          (default: ``{}``)
        * ``test_chunks`` Make a GET request to the server for each chunks to see if it
          already exists. If implemented on the server-side, this will allow for upload
          resumes even after a browser crash or even a computer restart. (default:
          ``True``)
        
        Some additional low level options are available - these are documented in the
        docstring of the ``Resumable`` class.
        
        Callbacks and Progress Reporting
        ++++++++++++++++++++++++++++++++
        
        resumable.py provides the ability to register arbitrary functions as callbacks
        in response to certain events. These are:
        
        On the ``Resumable`` object:
        
        * ``file_added`` Triggered when a file is added, with the file object
        * ``file_completed`` Triggered when a file is completed, with the file object
        * ``chunk_completed`` Triggered when a chunk is completed, with the file and
          chunk objects
        
        On a ``ResumableFile`` (returned by ``Resumable.add_file()``):
        
        * ``completed`` Triggered when the file is completed, without arguments
        * ``chunk_completed`` Triggered when a chunk is completed, with the chunk
          object
        
        Each of these callback dispatchers has a ``register()`` method that you can use
        to register callbacks. For example, to print a simple progress message that
        updates as chunks are uploaded:
        
        .. code-block:: python
        
            with Resumable('https://example.com/upload') as session:
                file = session.add_file('my_file.dat')
        
                def print_progress(chunk):
                    template = '\rPercent complete: {:.1%}'
                    print(template.format(file.fraction_completed), end='')
        
                file.chunk_completed.register(print_progress)
        
            print()  # new line
        
        Contribute
        ----------
        
        resumable.py's design is informed by resumable.js_, however only a core subset
        of features have yet been implemented. Patches implementing resumable.js
        features are welcome, and contributors should attempt to retain consistency
        with the resumable.js interface, mapping JavaScript style and idioms to Python
        equivalents as appropriate (for example, the ``simultaneousUploads``
        configuration parameter becomes ``simultaneous_uploads`` in Python).
        
        .. _resumable.js: http://resumablejs.com
        .. _resumable.js-samples: https://github.com/23/resumable.js/tree/master/samples
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
