1 2.. image:: https://raw.github.com/amol-/depot/master/docs/_static/logo.png 3 4DEPOT - File Storage Made Easy 5============================== 6 7.. image:: https://travis-ci.org/amol-/depot.png?branch=master 8 :target: https://travis-ci.org/amol-/depot 9 10.. image:: https://coveralls.io/repos/amol-/depot/badge.png?branch=master 11 :target: https://coveralls.io/r/amol-/depot?branch=master 12 13.. image:: https://img.shields.io/pypi/v/filedepot.svg 14 :target: https://pypi.python.org/pypi/filedepot 15 16DEPOT is a framework for easily storing and serving files in 17web applications on Python2.6+ and Python3.2+. 18 19DEPOT supports storing files in multiple backends, like: 20 21 * Local Disk 22 * In Memory (for tests) 23 * On GridFS 24 * On Amazon S3 (or compatible services) 25 26and integrates with database by providing files 27attached to your **SQLAlchemy** or **Ming/MongoDB** models 28with respect to transactions behaviours (files are rolled back too). 29 30Installing 31---------- 32 33Installing DEPOT can be done from PyPi itself by installing the ``filedepot`` distribution:: 34 35 $ pip install filedepot 36 37Getting Started 38--------------- 39 40To start using Depot refer to `Documentation <https://depot.readthedocs.io/en/latest/>`_ 41 42DEPOT was `presented at PyConUK and PyConFR <http://www.slideshare.net/__amol__/pyconfr-2014-depot-story-of-a-filewrite-gone-wrong>`_ in 2014 43 44standalone 45~~~~~~~~~~ 46 47Here is a simple example of using depot standalone to store files on MongoDB:: 48 49 from depot.manager import DepotManager 50 51 # Configure a *default* depot to store files on MongoDB GridFS 52 DepotManager.configure('default', { 53 'depot.backend': 'depot.io.gridfs.GridFSStorage', 54 'depot.mongouri': 'mongodb://localhost/db' 55 }) 56 57 depot = DepotManager.get() 58 59 # Save the file and get the fileid 60 fileid = depot.create(open('/tmp/file.png')) 61 62 # Get the file back 63 stored_file = depot.get(fileid) 64 print stored_file.filename 65 print stored_file.content_type 66 67models 68~~~~~~ 69 70Or you can use depot with SQLAlchemy to store attachments:: 71 72 from depot.fields.sqlalchemy import UploadedFileField 73 from depot.fields.specialized.image import UploadedImageWithThumb 74 75 76 class Document(Base): 77 __tablename__ = 'document' 78 79 uid = Column(Integer, autoincrement=True, primary_key=True) 80 name = Column(Unicode(16), unique=True) 81 content = Column('content_col', UploadedFileField) # plain attached file 82 83 # photo field will automatically generate thumbnail 84 photo = Column(UploadedFileField(upload_type=UploadedImageWithThumb)) 85 86 87 # Store documents with attached files, the source can be a file or bytes 88 doc = Document(name=u'Foo', 89 content=b'TEXT CONTENT STORED AS FILE', 90 photo=open('/tmp/file.png')) 91 DBSession.add(doc) 92 DBSession.flush() 93 94 # DEPOT is session aware, commit/rollback to keep or delete the stored files. 95 DBSession.commit() 96 97ChangeLog 98--------- 99 1000.8.0 101~~~~~ 102 103- Replaced ``unidecode`` dependency with ``anyascii`` to better cope with MIT License. 104 1050.7.1 106~~~~~ 107 108- Fix a bug in AWS-S3 support for unicode filenames. 109 1100.7.0 111~~~~~ 112 113- Support for ``storage_class`` option in ``depot.io.boto3.S3Storage`` backend. Detaults to ``STANDARD`` 114 1150.6.0 116~~~~~ 117 118- Officially support Python 3.7 119- Fix DEPOT wrongly serving requests for any url that starts with the mountpoint. (IE: ``/depotsomething`` was wrongly served for ``/depot`` mountpoint) 120- In SQLAlchemy properly handle deletion of objects deleted through ``Relationship.remove`` (IE: ``parent.children.remove(X)``) 121- In SQLAlchemy properly handle entities deleted through ``cascade='delete-orphan'`` 122 1230.5.2 124~~~~~ 125 126- Fixed an *start_response called a second time without providing exc_info* error with storages supporting plublic urls 127 128 1290.5.1 130~~~~~ 131 132- URLs generated by ``DepotMiddleware`` are now guaranteed to be plain ascii 133- [Breaking change]: Bucket existance with S3 storages should now be more reliable when the 134 bucket didn't already exist, but it requires an additional AWS policy: `s3:ListAllMyBuckets` that wasn't required on 0.5.0 135 1360.5.0 137~~~~~ 138 139- ``depot.io.boto3.S3Storage`` now provides support for accessing S3 with ``boto3``. 140 The previously existing ``depot.io.awss3.S3Storage`` can still be used to store 141 files on S3 using ``boto``. 142- SQLAlchemy integration now handles deletion of files on rollback when session 143 is not flushed. Previously flushing the session was required before a rollback too. 144- It is now possible to run tests through ``tox`` and build docs through ``tox -e docs`` 145- DEPOT is now tested against Python 3.6 146 1470.4.1 148~~~~~ 149 150- Fixed installation error on non-UTF8 systems 151- Improved support for polymorphic subtypes in SQLAlchemy 152 1530.4.0 154~~~~~ 155 156- Support for Python 3.5 157- Fixed ``Content-Disposition`` header for filenames including a comma 158 1590.3.2 160~~~~~ 161 162- ``MemoryFileStorage`` now accepts any option, for easier testing configuration 163 1640.3.1 165~~~~~ 166 167* Fixed ``Content-Disposition`` header when serving from S3 directly 168* Fixed size of SQLAlchemy field on Oracle (was bigger than the allowed maximum) 169 1700.3.0 171~~~~~ 172 173- ``MemoryFileStorage`` provides in memory storage for files. This is meant to provide a 174 convenient way to speed up test suites and avoid fixture clean up issues. 175- S3Storage can now generate public urls for private files (expire in 1 year) 176- Files created from plain bytes are now named "unnamed" instead of missing a filename. 177 1780.2.1 179~~~~~ 180 181- ``S3Storage`` now supports the ``prefix`` option to store files in a subpath 182 1830.2.0 184~~~~~ 185 186- Storages now provide a ``list`` method to list files available on the store (This is not meant to be used to retrieve files uploaded by depot as it lists all the files). 187- ``DepotExtension`` for Ming is now properly documented 188 1890.1.2 190~~~~~ 191 192- It is now possible to use multiple ``WithThumbnailFilter`` to generate multiple thumbnails 193 with different resolutions. 194- Better documentation for MongoDB ``UploadedFileProperty`` 195 1960.1.1 197~~~~~ 198 199- Fixed a bug with Ming support when acessing ``UploadedFileProperty`` as a class property 200- Improved support for DEPOT inside TurboGears admin when using MongoDB 201 2020.1.0 203~~~~~ 204 205- Added ``DepotManager.alias`` to configure aliases to storage. 206 This allows easy migration from one storage to another by switching where the alias points. 207- Now ``UploadedFileField`` permits to specify ``upload_storage`` to link a Model Column to a specific storage. 208- Added ``policy`` and ``encrypt_key`` options to `S3Storage` to upload private and encrypted files. 209 2100.0.6 211~~~~~ 212 213- Added `host` option to `S3Storage` to allow using providers different from *AWS*. 214 2150.0.5 216~~~~~ 217 218- Added `FileIntent` to explicitly provide `content_type` and `filename` to uploaded content. 219 2200.0.4 221~~~~~ 222 223- Added Content-Disposition header with original filename in WSGI middleware 224 2250.0.3 226~~~~~ 227 228- Work-Around for issue with `wsgi.file_wrapper` provided by Waitress WSGI Server 229 2300.0.2 231~~~~~ 232 233- Official Support for AWS S3 on Python3 234