Skip to content
Permalink
Browse files

README: switch to reStructuredText

  • Loading branch information...
aykevl committed Jul 8, 2017
1 parent 15c3781 commit e170dca3b3217659368af87113a293c6f063c99c
Showing with 68 additions and 62 deletions.
  1. +3 −1 .gitignore
  2. +1 −0 MANIFEST.in
  3. +0 −57 README.markdown
  4. +62 −0 README.rst
  5. +0 −2 setup.cfg
  6. +2 −2 setup.py
@@ -1,3 +1,5 @@
build/
__pycache__
*.pyc
build/
dist/
MANIFEST
@@ -0,0 +1 @@
include *.rst

This file was deleted.

@@ -0,0 +1,62 @@
Zip file streamer for HTTP
==========================

Similar systems/projects:

* The `Nginx zip module
<https://www.nginx.com/resources/wiki/modules/zip/>`_. Only for Nginx, so
can't be used with other webservers.
* `python-zipstream <https://github.com/allanlei/python-zipstream>`_. Does not
support calculating the file size beforehand or seeing through the file.

Usage:

.. code:: python
import zipseeker
# Create an index
fp = zipseeker.ZipSeeker()
fp.add('some/file.txt')
fp.add('another/file.txt', 'file2.txt')
# Calculate the total file size, e.g. for the Content-Length HTTP header.
contentLength = fp.size()
# Calculate the last-modified date, e.g. for the Last-Modified HTTP header.
lastModified = fp.lastModified()
# Send the ZIP file to the client
# Optionally add the start and end parameters for range requests.
# Note that the ZIP format doesn't support actually skipping parts of the file,
# as it needs to calculate the CRC-32 of every file at the end of the file.
fp.writeStream(outputFile)
Why?
----

While the file size of a ZIP file usually can't be calculated beforehand due to
compression, this is actually optional. The headers itself also have a pretty
constant size. That means that the whole file can have a predetermined file size
(and modtime).

This is useful when you want to provide ZIP downloads of large directories with
uncompressable files (e.g. images). The specific use case I created this media
file for was to provide downloads of whole photo albums without such
inconveniences as requesting a downloading link in an e-mail, using a lot system
resources for the creation of temporary files, and having to delete these files
afterwards.

Of course, it's possible to just stream a ZIP file, but that won't provide any
progress indication for file downloads and certainly doesn't support `Range
requests <https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests>`_.

For more information, see the `Nginx zip module
<https://www.nginx.com/resources/wiki/modules/zip/>`_.

TODO
----

* Implement actual seeking in the file - this should be doable.
* Use a CRC-32 cache that can be shared by the calling module.

This file was deleted.

@@ -4,11 +4,11 @@

setup(name='zipseeker',
packages=['zipseeker'],
version='1.0.0',
version='1.0.1',
description='Create a streamable and (somewhat) seekable .ZIP file',
author='Ayke van Laethem',
author_email='aykevanlaethem@gmail.com',
url='https://github.com/aykevl/zipseeker',
keywords=['zip', 'http', 'streaming'],
download='https://github.com/peterldowns/python-zipseeker/archive/1.0.0.tar.gz'
download='https://github.com/peterldowns/python-zipseeker/archive/1.0.1.tar.gz'
)

0 comments on commit e170dca

Please sign in to comment.
You can’t perform that action at this time.