.. image:: https://github.com/jugmac00/flask-reuploaded/workflows/CI/badge.svg?branch=master :target: https://github.com/jugmac00/flask-reuploaded/actions?workflow=CI :alt: CI Status

.. image:: https://coveralls.io/repos/github/jugmac00/flask-reuploaded/badge.svg?branch=master :target: https://coveralls.io/github/jugmac00/flask-reuploaded?branch=master

.. image:: https://img.shields.io/pypi/v/flask-reuploaded
:alt: PyPI :target: https://github.com/jugmac00/flask-reuploaded

.. image:: https://img.shields.io/pypi/pyversions/flask-reuploaded
:alt: PyPI - Python Version :target: https://pypi.org/project/Flask-Reuploaded/

.. image:: https://img.shields.io/pypi/l/hibpcli :target: https://github.com/jugmac00/flask-reuploaded/blob/master/LICENSE

Flask-Reuploaded

Flask-Reuploaded provides file uploads for Flask.

Notes on this package

This is an independently maintained version of Flask-Uploads based on the 0.2.1 version of the original, but also including four years of unreleased changes, at least not released to PyPI.

Noteworthy is the fix for the Werkzeug API change.

Goals

• provide a stable drop-in replacement for Flask-Uploads
• regain momentum for this widely used package
• provide working PyPI packages

Migration guide from Flask-Uploads

Incompatibilities between Flask-Reuploaded and Flask-Uploads

As already mentioned,
staying compatible with `Flask-Uploads` is one of this project's goals.

Nevertheless, there are the following known incompatibilities:

- the `patch_request_class` helper function has been removed;
  the function was only necessary for Flask 0.6 and earlier.
  Since then you can use Flask's own
  `MAX_CONTENT_LENGTH <https://flask.palletsprojects.com/en/1.1.x/config/#MAX_CONTENT_LENGTH>`_
  environment variable,
  so you don’t read more than this many bytes from the incoming request data.
- `autoserve` of uploaded images now has been deactivated;
  this was a poorly documented "feature",
  which even could have lead to unwanted data disclosure;
  if you want to activate the feature again,
  you need to set `UPLOADS_AUTOSERVE=True`

Uninstall and install
~~~~~~~~~~~~~~~~~~~~~

If you have used `Flask-Uploads` and want to migrate to `Flask-Reuploaded`,
you only have to install `Flask-Reuploaded` instead of `Flask-Uploads`.

That's all!

So, if you use `pip` to install your packages, instead of ...

.. code-block:: bash

    $ pip install `Flask-Uploads`  # don't do this! package is broken

... just do ...

.. code-block:: bash

    $ pip install `Flask-Reuploaded`

`Flask-Reuploaded` is a drop-in replacement.

This means you do not have to change a single line of code.


Installation
------------

.. code-block:: bash

    $ pip install Flask-Reuploaded


Getting started
---------------

create an UploadSet

.. code-block:: python

    from flask_uploads import IMAGES

    photos = UploadSet("photos", IMAGES)

configure your Flask app and this extension

.. code-block:: python

    app.config["UPLOADED_PHOTOS_DEST"] = "static/img"
    app.config["SECRET_KEY"] = os.urandom(24)
    configure_uploads(app, photos)

use `photos` in your view function

.. code-block:: python

    photos.save(request.files['photo'])

See below for a complete example.


Documentation
-------------

You can find the documentation at:

https://flask-reuploaded.readthedocs.io/en/latest/

You can generate the documentation locally:

.. code-block:: bash

    tox -e docs

You can update the dependencies for documentation generation:

.. code-block:: bash

    tox -e upgradedocs


Minimal example application
----------------------------


Application code, e.g. main.py
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    import os

    from flask import Flask, flash, render_template, request
    # please note the import from `flask_uploads` - not `flask_reuploaded`!!
    # this is done on purpose to stay compatible with `Flask-Uploads`
    from flask_uploads import IMAGES, UploadSet, configure_uploads

    app = Flask(__name__)
    photos = UploadSet("photos", IMAGES)
    app.config["UPLOADED_PHOTOS_DEST"] = "static/img"
    app.config["SECRET_KEY"] = os.urandom(24)
    configure_uploads(app, photos)


    @app.route("/", methods=['GET', 'POST'])
    def upload():
        if request.method == 'POST' and 'photo' in request.files:
            photos.save(request.files['photo'])
            flash("Photo saved successfully.")
            return render_template('upload.html')
        return render_template('upload.html')


HTML code for `upload.html`
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: html

    <!doctype html>
    <html lang=en>
    <head>
        <meta charset=utf-8>
        <title>Flask-Reuploaded Example</title>
    </head>
    <body>
        {% with messages = get_flashed_messages() %}
        {% if messages %}
        <ul class=flashes>
        {% for message in messages %}
            <li>{{ message }}</li>
        {% endfor %}
        </ul>
        {% endif %}
        {% endwith %}

    <form method=POST enctype=multipart/form-data action="{{ url_for('upload') }}">
        <input type=file name=photo>
        <button type="submit">Submit</button>
    </form>
    </body>
    </html>


Project structure
~~~~~~~~~~~~~~~~~

The project structure would look as following...

.. code-block:: bash

    ❯ tree -I "__*|h*"
    .
    ├── main.py
    ├── static
    │   └── img
    └── templates
        └── upload.html


Running the example application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In order to run the application,
you have to enter the following commands...

.. code-block:: bash

    ❯ export FLASK_APP=main.py

    ❯ flask run

Then point your browser to `http://127.0.0.1:5000/`.


Contributing
------------

Contributions are more than welcome.

Please have a look at the `open issues <https://github.com/jugmac00/flask-reuploaded/issues>`_.

There is also a `short contributing guide <https://github.com/jugmac00/flask-reuploaded/blob/master/CONTRIBUTING.rst>`_.


Changelog
=========

1.3.0 (2022.12.20)
------------------
- improve documentation
  (`#133 <https://github.com/jugmac00/flask-reuploaded/issues/133>`_)
- drop support for Python 3.6
- add support for Python 3.11
- update dependencies for building documentation


1.2.0 (2021.11.07)
------------------
- add contexts to coverage report
- pin documentation dependencies to prevent future breakage
- fix typing errors (mypy) with recently released Flask 2.0.1
- add support for Python 3.10


1.1.0 (2021.05.09)
------------------
- make type checkers aware that this library is using type annotations


1.0.0 (2021.04.07)
------------------
- raise test coverage to 100%
- use official `Pallets` theme for the documentation
- remove deprecated `patch_request_class` helper function; use `MAX_CONTENT_LENGTH` instead.
- `autoserve` now has been deactivated by default and needs explicit activation
  via the setting `UPLOADS_AUTOSERVE=True`


0.5.0
-----
- improve documentation of example app
- document surprising `autoserve` feature
- issue a warning when using `autoserve` without explicit configuration


0.4.0
-----
- add type annotations
- drop support for Python 2 and Python 3.5
  (`#8 <https://github.com/jugmac00/flask-reuploaded/issues/8>`_)
- deprecate `patch_request_class`
  (`#43 <https://github.com/jugmac00/flask-reuploaded/issues/43>`_)
- use a `src` directory for source code
  (`#21 <https://github.com/jugmac00/flask-reuploaded/issues/21>`_)
- add tox env for check-python-versions
  (`#20 <https://github.com/jugmac00/flask-reuploaded/issues/20>`_)
- add flake8-bugbear
- add short contribution guide
  (`#6 <https://github.com/jugmac00/flask-reuploaded/issues/6>`_)
- add `getting started`
  (`#59 <https://github.com/jugmac00/flask-reuploaded/issues/59>`_)
- delete broken example and add minimal example to README
  (`#15 <https://github.com/jugmac00/flask-reuploaded/issues/15>`_)
- add support for Python 3.9
- use gh actions instead of Travis CI


0.3.2
-----
- documentation update
  (`#5 <https://github.com/jugmac00/flask-reuploaded/issues/5>`_)

  * update docs/index.rst
  * use blue ReadTheDocs theme
  * update sphinx configuration
  * add documentation link to `setup.py`, so it shows on PyPi
  * add note about documentation in the README file
  * delete old theme files
- configure `isort` to force single line imports


0.3.1
-----
- add badges to README
  (`# 31 <https://github.com/jugmac00/flask-reuploaded/issues/31>`_)
- add migration guide from `Flask-Uploads` to `Flask-Reuploaded`
  (`#11 <https://github.com/jugmac00/flask-reuploaded/issues/11>`_)
- add packaging guide
  (`#28 <https://github.com/jugmac00/flask-reuploaded/issues/28>`_)
- update installation instruction in README


0.3
---

Besides including four years of unreleased changes from the original
package, most notable the fix for the Werkzeug API change, the
following changes happened since forking the original package.

- rename package from `Flask-Uploads` to `Flask-Reuploaded`
  (`#10 <https://github.com/jugmac00/flask-reuploaded/issues/10>`_)
- update `setup.py`
  (`#12 <https://github.com/jugmac00/flask-reuploaded/issues/12>`_)
- start using pre-commit.com
  (`#4 <https://github.com/jugmac00/flask-reuploaded/issues/4>`_)
- update README
  (`#14 <https://github.com/jugmac00/flask-reuploaded/issues/14>`_)
- setup CI (Travis)
  (`#3 <https://github.com/jugmac00/flask-reuploaded/issues/3>`_)
- fix broken tests
  (`#13 <https://github.com/jugmac00/flask-reuploaded/issues/13>`_)
- make use of `pytest` instead of the no longer maintained `nose`
  (`#2 <https://github.com/jugmac00/flask-reuploaded/issues/2>`_)
- add a changelog and start tracking changes
  (`#1 <https://github.com/jugmac00/flask-reuploaded/issues/1>`_)