A WSGI middleware to get some stats on large files upload
Project description
The Sphinx version of this documentation can be found here.
A demo page is also available.
Description
gp.fileupload is a wsgi middleware to get the stat of large files uploaded to the server.
The principle is to write the size read to a temporary file and get the stats from the temporary file.
Low level usage
Middleware
Wrap your wsgi application with the middleware:
>>> from gp.fileupload import FileUpload
>>> def my_application(environ, start_response):
... start_response('200 OK', [('Content-Type', 'txt/html')])
... return ['<html><body>My app</body></html>
>>> app = FileUpload(my_application, tempdir='/tmp/fileupload',
... max_size=None)
>>> def application(environ, start_response):
... return app(environ, start_response)
The FileUpload middleware has the following options:
tempdir: A path to a temporary folder
max_size: Max allowed size. If the file size is larger than max_size a RuntimeError is raised.
include_files: A list of static files to include to the html body. See below.
Application code
Write a html form like this:
<form enctype="multipart/form-data"
method="POST"
action=".?gp.fileupload.id=1">
<input type="file" name="file" />
<input type="submit" />
</form>
Where 1 is the session id. The session id must be a digit.
When the form is submitted, you can use some ajax stuff to get the stats of the upload with the url:
http://yourhost/gp.fileupload.stat/1
This will return some JSON data like:
{'state': 1, 'percent': 69}
state can have the following values:
0: nothing done yet.
1: upload is active
-1: file is larger than max_size.
You can use this to display the upload progress.
Paste factories
The package provide a filter factory usable in PasteDeploy configuration files.
The factory provides the middleware itself:
[pipeline:main] pipeline = fileupload egg:myapp [filter:fileupload] use = egg:gp.fileupload # temporary directory to write streams to tempdir = %(here)s/data/fileupload # file to inject in the html code include_files = fileupload.css jquery.* # if you already have jquery in your application, use this line #include_files = fileupload.css jquery.fileupload.* # max upload size is 50Mo max_size = 50
Then you can access the javascript stuff at /gp.fileupload.static/.
The include_files parameters will inject those tags in your application:
<link type="text/css" rel="Stylesheet" media="screen"
href="/gp.fileupload.static/fileupload.css"/>
<script type="text/javascript"
src="/gp.fileupload.static/jquery.js"/>
<script type="text/javascript"
src="/gp.fileupload.static/jquery.fileupload.js"/>
<script type="text/javascript"
src="/gp.fileupload.static/jquery.fileupload.auto.js"/>
And feel free to use ajax stuff. Notice that those tags are included at the end of the html body.
Available files are:
jquery.js: jquery 1.2.6
jquery.fileupload.js: the jQuery().fileUpload plugin.
jquery.fileupload.auto.js: auto bind form tags with a multipart/form-data enctype.
fileupload.css: a few css to display the progress bar.
Ajax stuff
Description
A jQuery plugin is provided as a helper.
To use it, you only need to add a script tag to your html head section:
<script type="text/javascript">
jQuery(document).ready(function() { jQuery('#sample').fileUpload(); });
</script>
The fileUpload plugin has the following options:
add_link: Add a link to add more than one file.
link_label: Label of the link.
submit_label: The label of the button.
field_name: A string to use as file field names. Default to file.
submit_empty_forms: if true, submit forms with empty file fields. Default: true.
use_iframes: If set to false the form will be submitted as a normal form. If true the form target become an iframe and the page is not reloaded.
stat_delay: stat request delay. Default: 300.
success: A javascript function evaluated when all files are uploaded. The default one does nothing.
Examples
If you want multiple file forms:
<div id="forms"></div>
<script type="text/javascript">
jQuery(document).ready(function() {
jQuery('#forms').fileUpload({action:'/upload', field_name:'file_field'})
});
</script>
This will show a form with addable file field and upload them to /upload. The forms are submitted in iframes as target so the page does not change after uploading.
If you already have forms. This is what is done in the jquery.fileupload.auto.js:
<script type="text/javascript">
jQuery(document).ready(function() {
jQuery('form[enctype^='mulitpart/form-data]')
.fileUpload({use_iframes: false});
});
</script>
This will show a progress bar when the form is uploaded, then redirect to the application page when the upload is completed. So the usage is totally transparent for you.
Contributors
Gael Pasgrimaud <gael@gawel.org>
Christophe Combelles
News
0.3 (2008-07-27)
fix Content-Length header sent after code injection.
add e.stopPropagation() to the Add more file link
0.2 (2008-07-25)
add docs/ folder to auto generate documentation with sphinx
use jquery packed version
IE javascript fixes
0.1 (2008-07-24)
first version
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
