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