Document upload_to method behavior when duplicate file is present

[Matthew Pava]

I have a FileField with a custom upload_to method that generates a completely new path and filename. In my unit tests, I discovered that the default behavior of adding random characters to the end of the file name was enabled when the file name already existed. It took me a week to figure this out. Documenting this fact would have been incredibly helpful.

​https://docs.djangoproject.com/en/3.0/ref/models/fields/#django.db.models.FileField.upload_to

[Matthew Pava]

So I just discovered that this detail is documented in ​Storage.save(), which is mentioned in the documentation for that method. So maybe this isn't completely necessary, but it still feels like this documentation could be improved here somewhat. But I also understand if we just mark this as invalid.

[Mariusz Felisiak]

Replying to Matthew Pava:

So I just discovered that this detail is documented in ​Storage.save(), which is mentioned in the documentation for that method. So maybe this isn't completely necessary, but it still feels like this documentation could be improved here somewhat. But I also understand if we just mark this as invalid.

Yes, exactly. It's ​documented "that the value is passed to the Storage.save() method" and in the Storage.save() ​documentation we have:

If there already exists a file with this name name, the storage system may modify the filename as necessary to get a unique name. The actual name of the stored file will be returned.

I think it's sufficient.