Library that works with Flask & SqlAlchemy to store files in your database and server.
Project description
Library that works with Flask (version 1 or 2) and SqlAlchemy to store files on your server & in your database
Read the docs: Documentation
Installation
Please install the latest release:
pip install flask-file-upload
If you are updating from >=0.1 then please read the upgrading instruction
General Flask config options
(Important: The below configuration variables need to be set before initiating FileUpload
)
from flask_file_upload.file_upload import FileUpload
from os.path import join, dirname, realpath
# This is the directory that flask-file-upload saves files to. Make sure the UPLOAD_FOLDER is the same as Flasks's static_folder or a child. For example:
app.config["UPLOAD_FOLDER"] = join(dirname(realpath(__file__)), "static/uploads")
# Other FLASK config varaibles ...
app.config["ALLOWED_EXTENSIONS"] = ["jpg", "png", "mov", "mp4", "mpg"]
app.config["MAX_CONTENT_LENGTH"] = 1000 * 1024 * 1024 # 1000mb
app.config["SQLALCHEMY_DATABASE_URI"] = "postgresql://localhost:5432/blog_db"
Setup
We can either pass the instance to FileUpload(app) or to the init_app(app) method:
from flask_file_upload import FileUpload
app = Flask(__name__, static_folder="static") # IMPORTANT: This is your root directory for serving ALL static content!
db = SQLAlchemy()
file_upload = FileUpload()
# An example using the Flask factory pattern
def create_app():
db.init_app(app)
# Pass the Flask app instance as the 1st arg &
# the SQLAlchemy object as the 2nd arg to file_upload.init_app.
file_upload.init_app(app, db)
# If you require importing your SQLAlchemy models then make sure you import
# your models after calling `file_upload.init_app(app, db)` or `FileUpload(app, db)`.
from .model import *
# Or we can pass the Flask app instance directly & the Flask-SQLAlchemy instance:
db = SQLAlchemy(app)
# Pass the Flask app instance as the 1st arg &
# the SQLAlchemy object as the 2nd arg to FileUpload
file_upload = FileUpload(app, db)
app: Flask = None
Decorate your SqlAlchemy models
Flask-File-Upload (FFU) setup requires each SqlAlchemy model that wants to use FFU
library to be decorated with @file_upload.Model
.This will enable FFU to update your
database with the extra columns required to store files in your database.
Declare your attributes as normal but assign a value of file_upload.Column
.
This is easy if you are using Flask-SqlAlchemy:
from flask_sqlalchemy import SqlAlchemy
db = SqlAlchemy()
Full example:
from my_app import file_upload
@file_upload.Model
class blogModel(db.Model):
__tablename__ = "blogs"
id = db.Column(db.Integer, primary_key=True)
# Use flask-file-upload's `file_upload.Column()` to associate a file with a SQLAlchemy Model:
my_placeholder = file_upload.Column()
my_video = file_upload.Column()
define files to be uploaded:
# A common scenario could be a video with placeholder image.
# So first lets grab the files from Flask's request object:
my_video = request.files["my_video"]
placeholder_img = request.files["placeholder_img"]
Save files
To add files to your model, pass a dict of keys that reference the attribute name(s) defined in your SqlAlchemy model & values that are your files. For Example:
file_upload.add_files(blog_post, files={
"my_video": my_video,
"placeholder_img": placeholder_img,
})
# Now commit the changes to your db
db.session.add(blog_post)
db.session.commit()
It's always good practise to commit the changes to your db as close to the end
of your view handlers as possible (we encourage you to use add_files
over the save_files
method for this reason).
If you wish to let flask-file-upload handle adding & committing to
the current session then use file_upload.save_files
- this method is only recommended
if you are sure nothing else needs committing after you have added you files.
For example:
file_upload.save_files(blog_post, files={
"my_video": my_video,
"placeholder_img": placeholder_img,
})
If you followed the setup above you will see the following structure saved to your app:
Update files
blog_post = file_upload.update_files(blog_post, files={
"my_video": new_my_video,
"placeholder_img": new_placeholder_img,
})
Delete files
Deleting files from the db & server can be non trivial, especially to keep
both in sync. The file_upload.delete_files
method can be called with a
kwarg of clean_up
& then depending of the string value passed it will
provide 2 types of clean up functionality:
files
will clean up files on the server but not update the modelmodel
will update the model but not attempt to remove the files from the server. See delete_files Docs for more details
# Example using a SqlAlchemy model with an appended
# method that fetches a single `blog`
blogModel = BlogModel()
blog_results = blogModel.get_one()
# We pass the blog & files
blog = file_upload.delete_files(blog_result, files=["my_video"])
# If parent kwarg is set to True then the root primary directory & all its contents will be removed.
# The model will also get cleaned up by default unless set to `False`.
blog_result = file_upload.delete_files(blog_result, parent=True, files=["my_video"])
# If the kwarg `commit` is not set or set to True then the updates are persisted.
# to the session. And therefore the session has been commited.
blog = file_upload.delete_files(blog_result, files=["my_video"])
# Example of cleaning up files but not updating the model:
blog = file_upload.delete_files(blog_result, files=["my_video"], clean_up="files")
Stream a file
file_upload.stream_file(blog_post, filename="my_video")
File Url paths
file_upload.get_file_url(blog_post, filename="placeholder_img")
Example for getting file urls from many objects:
# If blogs_model are many blogs:
for blog in blog_models:
blog_image_url = file_upload.get_file_url(blog, filename="blog_image")
setattr(blog, "blog_image", blog_image_url)
Set file paths to multiple objects - Available in 0.1.0-rc.6
& v0.1.0
The majority of requests will require many entities to be returned
& these entities may have SQLAlchemy backrefs
with
relationships that may also contain Flask-File-Upload (FFU) modified SQLAlchemy
models. To make this trivial, this method will set the appropriate
filename urls to your SQLAlchemy model objects (if the transaction
hasn't completed then add_file_urls_to_models will complete the
transaction by default).
The first argument required by this method is models
- the SQLAlchemy model(s).
Then pass in the required kwarg filenames
which references the parent's
FFU Model values - this is the file_upload.Model
decorated SQLALchemy model
file_upload.Column()
method.
Important! Also take note that each attribute set by this method postfixes
a _url
tag. e.g blog_image
becomes blog_image_url
Example for many SQLAlchemy entity objects (or rows in your table)::
@file_upload.Model
class BlogModel(db.Model):
blog_image = file_upload.Column()
Now we can use the file_upload.add_file_urls_to_models
to add file urls to
each SQLAlchemy object. For example::
blogs = add_file_urls_to_models(blogs, filenames="blog_image")
# Notice that we can get the file path `blog_image` + `_url`
assert blogs[0].blog_image_url == "path/to/blogs/1/blog_image_url.png"
To set filename attributes to a a single or multiple SQLAlchemy parent models with backrefs
to multiple child SQLAlchemy models, we can assign to the optional backref
kwarg the name of the backref model & a list of the file attributes we set
with the FFU Model decorated SQLAlchemy model.
To use backrefs we need to declare a kwarg of backref
& pass 2 keys:
- name: The name of the backref relation
- filenames: The FFU attribute values assigned to the backref model
For example::
# Parent model
@file_upload.Model
class BlogModel(db.Model):
# The backref:
blog_news = db.relationship("BlogNewsModel", backref="blogs")
blog_image = file_upload.Column()
blog_video = file_upload.Column()
# Model that has a foreign key back up to `BlogModel
@file_upload.Model
class BlogNewsModel(db.Model):
# The foreign key assigned to this model:
blog_id = db.Column(db.Integer, db.ForeignKey("blogs.blog_id"))
news_image = file_upload.Column()
news_video = file_upload.Column()
The kwarg backref
keys represent the backref model or entity (in the above example
this would be the BlogNewsModel
which we have named blog_news
. Example::
blogs = add_file_urls_to_models(blogs, filenames=["blog_image, blog_video"],
backref={
"name": "blog_news",`
"filenames": ["news_image", "news_video],
})
WARNING: You must not set the relationship kwarg: lazy="dynamic"
!
If backref
is set to "dynamic" then back-referenced entity's
filenames will not get set. Example::
# This will work
blog_news = db.relationship("BlogNewsModel", backref="blog")
# this will NOT set filenames on your model class
blog_news = db.relationship("BlogNewsModel", backref="blog", lazy="dynamic")
Running Flask-Migration After including Flask-File-Upload in your project
The arguments below will also run if you're using vanilla Alembic.
export FLASK_APP=flask_app.py # Path to your Flask app
# with pip
flask db stamp head
flask db migrate
flask db upgrade
# with pipenv
pipenv run flask db stamp head
pipenv run flask db migrate
pipenv run flask db upgrade
Upgrading from v0.1 to v0.2
You will need to create a migration script with the below column name changes:
[you_file_name]__file_type
becomes[you_file_name]__mime_type
[you_file_name]__mime_type
becomes[you_file_name]__ext
[you_file_name]__file_name
stays the same
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file flask-file-upload-0.2.1.tar.gz
.
File metadata
- Download URL: flask-file-upload-0.2.1.tar.gz
- Upload date:
- Size: 18.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.7.1 importlib_metadata/4.8.2 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 11a9c15fd63463e8d74f5349fcc09257469db4a2f7c813ab0e3adc0d6d24825e |
|
MD5 | a6192d05128308fab5ffe51826b68ff7 |
|
BLAKE2b-256 | 2967d5abdfd20bce1b322faceb6169a45952e881e1eebf27a510a20af2731446 |
File details
Details for the file flask_file_upload-0.2.1-py3-none-any.whl
.
File metadata
- Download URL: flask_file_upload-0.2.1-py3-none-any.whl
- Upload date:
- Size: 19.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.7.1 importlib_metadata/4.8.2 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0732a3188bb23c12d35510c123a779b4c4f609f3d33cf8b63550ad6198fc0474 |
|
MD5 | 3b962c5a969e5dfcd633e6a3ed236c21 |
|
BLAKE2b-256 | 9492bb52d8eeca255db59ab3dd092f883b608c00e72b30e25092b41eeeafad23 |