From 7754da0d78c22822edb859772fdf3059a82a1b65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=BCrgen=20Gmach?= <juergen.gmach@googlemail.com>
Date: Tue, 30 Jun 2020 09:59:14 +0200
Subject: [PATCH] Fix docstrings to match new `FileStorage` location

When Werkzeug 1.0 was released, the import API changed.

The import for `FileStorage` was fixed, but the docstrings were
not updated.

Also, a test has been written to catch the case when not a proper
`FileStorage` was provided.

modified:   flask_uploads.py
modified:   tests.py
modified:   tox.ini
---
 flask_uploads.py | 25 ++++++++++++++++---------
 tests.py         | 13 +++++++++++++
 tox.ini          |  2 +-
 3 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/flask_uploads.py b/flask_uploads.py
index efb0243..de320ca 100644
--- a/flask_uploads.py
+++ b/flask_uploads.py
@@ -379,13 +379,16 @@ def path(self, filename, folder=None):
         return os.path.join(target_folder, filename)
 
     def file_allowed(self, storage, basename):
-        """
-        This tells whether a file is allowed. It should return `True` if the
-        given `werkzeug.FileStorage` object can be saved with the given
-        basename, and `False` if it can't. The default implementation just
-        checks the extension, so you can override this if you want.
+        """This tells whether a file is allowed.
+
+        It should return `True` if the given
+        `werkzeug.datastructures.FileStorage` object can be saved with
+        the given basename, and `False` if it can't.
 
-        :param storage: The `werkzeug.FileStorage` to check.
+        The default implementation just checks the extension,
+        so you can override this if you want.
+
+        :param storage: The `werkzeug.datastructures.FileStorage` to check.
         :param basename: The basename it will be saved under.
         """
         return self.extension_allowed(extension(basename))
@@ -405,9 +408,13 @@ def get_basename(self, filename):
         return lowercase_ext(secure_filename(filename))
 
     def save(self, storage, folder=None, name=None):
-        """
-        This saves a `werkzeug.FileStorage` into this upload set. If the
-        upload is not allowed, an `UploadNotAllowed` error will be raised.
+        """This saves the `storage` into this upload set.
+
+        A `storage` is a `werkzeug.datastructures.FileStorage`.
+
+        If the upload is not allowed,
+        an `UploadNotAllowed` error will be raised.
+
         Otherwise, the file will be saved and its name (including the folder)
         will be returned.
 
diff --git a/tests.py b/tests.py
index ebd8f7f..8114c8d 100644
--- a/tests.py
+++ b/tests.py
@@ -7,6 +7,7 @@
 
 import os.path
 
+import pytest
 from flask import Flask
 from flask import url_for
 
@@ -246,6 +247,18 @@ def test_secured_filename(self):
         assert res2 == 'myapp.wsgi'
         assert tfs2.saved == '/uploads/myapp.wsgi'
 
+    def test_storage_is_not_a_werkzeug_datastructure(self):
+        """UploadSet.save needs a valid FileStorage object.
+
+        When something different is passed in, a TypeError gets raised.
+        """
+        uset = UploadSet('files', ALL)
+        uset._config = Config('/uploads')
+        non_storage = 'this is no werkzeug.datastructure.FileStorage'
+
+        with pytest.raises(TypeError):
+            uset.save(non_storage)
+
 
 class TestConflictResolution(object):
     def setup(self):
diff --git a/tox.ini b/tox.ini
index 3621e94..9176bec 100644
--- a/tox.ini
+++ b/tox.ini
@@ -31,7 +31,7 @@ commands =
     check-python-versions {posargs}
 
 [isort]
-known_third_party = flask,setuptools,sphinx_rtd_theme,werkzeug
+known_third_party = flask,pytest,setuptools,sphinx_rtd_theme,werkzeug
 force_single_line = True
 
 [flake8]