Added help entry for File already exists error

tests/unit/forklift/test_legacy.py

@@ -1609,7 +1609,8 @@ def test_upload_fails_with_previously_used_filename(self, pyramid_config,
         assert resp.status_code == 400
         assert resp.status == (
             "400 This filename has previously been used, you should use a "
-            "different version."
+            "different version. "
+            "See https://pypi.org/help/#file-name-reuse"
         )
 
     def test_upload_noop_with_existing_filename_same_content(self,
@@ -1714,7 +1715,10 @@ def test_upload_fails_with_existing_filename_diff_content(self,
         resp = excinfo.value
 
         assert resp.status_code == 400
-        assert resp.status == "400 File already exists."
+        assert resp.status == (
+            "400 File already exists. "
+            "See https://pypi.org/help/#file-name-reuse"
+        )
 
     def test_upload_fails_with_wrong_filename(self, pyramid_config,
                                               db_request):

warehouse/forklift/legacy.py

@@ -1023,7 +1023,10 @@ def file_upload(request):
         if is_duplicate:
             return Response()
         elif is_duplicate is not None:
-            raise _exc_with_message(HTTPBadRequest, "File already exists.")
+            raise _exc_with_message(
+                HTTPBadRequest, "File already exists. "
+                                "See https://pypi.org/help/#file-name-reuse"
+            )
 
         # Check to see if the file that was uploaded exists in our filename log
         if (request.db.query(
@@ -1033,7 +1036,8 @@ def file_upload(request):
             raise _exc_with_message(
                 HTTPBadRequest,
                 "This filename has previously been used, you should use a "
-                "different version.",
+                "different version. "
+                "See https://pypi.org/help/#file-name-reuse",
             )
 
         # Check to see if uploading this file would create a duplicate sdist

warehouse/templates/pages/help.html

@@ -37,7 +37,7 @@
 {% macro mirroring() %}How can I run a mirror of PyPI?{% endmacro %}
 {% macro private_indices() %}How can I publish my private packages to PyPI?{% endmacro %}
 {% macro admin_intervention() %}Why did my package or user registration get blocked?{% endmacro %}
-
+{% macro file_name_reuse() %}Why am I getting "File already exists" error?{% endmacro %}
 {% block title %}Help{% endblock %}
 
 {% block content %}
@@ -63,6 +63,7 @@ <h1 class="page-title">Common Questions</h1>
         <li><a href="#mirroring">{{ mirroring() }}</a></li>
         <li><a href="#private-indices">{{ private_indices() }}</a></li>
         <li><a href="#admin-intervention">{{ admin_intervention() }}</a></li>
+        <li><a href="#file-name-reuse">{{ file_name_reuse() }}</a></li>
       </ul>
 
       <section id="packages" class="common-question">
@@ -268,6 +269,19 @@ <h2>{{ admin_intervention() }}</h2>
           When the PyPI Administrators are overwhelmed by spam <b>or</b> determine that there is some other threat to PyPI, new user registration and/or new project registration may be disabled. Check <a href="https://status.python.org">our status page</a> for more details, as we'll likely have updated it with reasoning for the intervention.
         </p>
       </section>
+      <section id="file-name-reuse" class="common-question">
+        <h2>{{ file_name_reuse() }}</h2>
+        <p>
+          The error <i>HTTPError: 400 Client Error: File already exists</i> happens for one of two reasons:
+        </p>
+        <ul>
+          <li>Filename has been used and file exists</li>
+          <li>Filename has been used but file no longer exists</li>
+        </ul>
+        <p>
+          PyPI does not allow for a filename to be reused, even once a project has been deleted and recreated.
+        </p>
+      </section>
     </div>
   </section>