id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
30695	Fix an example of Storage objects in Managing files docs.	Tobias McNulty	Harrison Morgan	"This section of the docs (https://docs.djangoproject.com/en/2.2/topics/files/#storage-objects) suggests that one should use absolute paths when calling storage API methods, but executing this sample code on a fresh Django 2.2 project raises a `SuspiciousFileOperation` error:

{{{
(filestorage-test) $ pip freeze
Django==2.2.4
pytz==2019.2
sqlparse==0.3.0
(filestorage-test) $ django-admin startproject filestorage_test
(filestorage-test) $ cd filestorage_test/
(filestorage-test) $ python manage.py shell
Python 3.7.3 (default, Mar 27 2019, 09:23:15) 
[Clang 10.0.1 (clang-1001.0.46.3)] on darwin
Type ""help"", ""copyright"", ""credits"" or ""license"" for more information.
(InteractiveConsole)
>>> from django.core.files.base import ContentFile
>>> from django.core.files.storage import default_storage
>>> default_storage.save('/path/to/file', ContentFile('new content'))
Traceback (most recent call last):
  File ""<console>"", line 1, in <module>
  File ""/Users/tobias/.virtualenvs/filestorage-test/lib/python3.7/site-packages/django/core/files/storage.py"", line 51, in save
    name = self.get_available_name(name, max_length=max_length)
  File ""/Users/tobias/.virtualenvs/filestorage-test/lib/python3.7/site-packages/django/core/files/storage.py"", line 75, in get_available_name
    while self.exists(name) or (max_length and len(name) > max_length):
  File ""/Users/tobias/.virtualenvs/filestorage-test/lib/python3.7/site-packages/django/core/files/storage.py"", line 310, in exists
    return os.path.exists(self.path(name))
  File ""/Users/tobias/.virtualenvs/filestorage-test/lib/python3.7/site-packages/django/core/files/storage.py"", line 323, in path
    return safe_join(self.location, name)
  File ""/Users/tobias/.virtualenvs/filestorage-test/lib/python3.7/site-packages/django/utils/_os.py"", line 46, in safe_join
    'component ({})'.format(final_path, base_path))
django.core.exceptions.SuspiciousFileOperation: The joined path (/path/to/file) is located outside of the base path component (/Users/tobias/tmp/filestorage_test)
}}}

I realize one could prepend the path to `MEDIA_ROOT` to work around that, but I'm not sure that's the right convention to establish when relative paths work just as well (not to mention that prepending `MEDIA_ROOT` would be the wrong approach for a remote storage).

I think the convention is or should be to use relative paths when interacting with the Django file storage API. The other related section of the docs (https://docs.djangoproject.com/en/2.2/ref/files/storage/#the-storage-class) doesn't say either way whether the path should be relative or absolute.

Creating this ticket to look through the file storage-related docs at some point to clarify what is a ""path"" when interacting with the file storage API (however we want to do that, if not how I've proposed here). At least, the sample code linked first above needs be updated so that someone can run it and see the results described in the docs."	Cleanup/optimization	closed	Documentation	2.2	Normal	fixed		Harrison Morgan	Accepted	1	0	0	0	1	0