Added help entry for File already exists error (#2997)

* Added help entry for File already exists error

* Rephrased help entry. Included link in error message. Made changes to test as well

* Addressed code reviews

* Addressed linting issues

tests/unit/forklift/test_legacy.py

@@ -1615,16 +1615,23 @@ def test_upload_fails_with_previously_used_filename(self, pyramid_config,
         })
 
         db_request.db.add(Filename(filename=filename))
+        db_request.route_url = pretend.call_recorder(
+            lambda route, **kw: "/the/help/url/"
+        )
 
         with pytest.raises(HTTPBadRequest) as excinfo:
             legacy.file_upload(db_request)
 
         resp = excinfo.value
 
+        assert db_request.route_url.calls == [
+            pretend.call('help', _anchor='file-name-reuse')
+        ]
         assert resp.status_code == 400
         assert resp.status == (
             "400 This filename has previously been used, you should use a "
-            "different version."
+            "different version. "
+            "See /the/help/url/"
         )
 
     def test_upload_noop_with_existing_filename_same_content(self,
@@ -1722,14 +1729,22 @@ def test_upload_fails_with_existing_filename_diff_content(self,
                 ),
             ),
         )
-
+        db_request.route_url = pretend.call_recorder(
+            lambda route, **kw: "/the/help/url/"
+        )
         with pytest.raises(HTTPBadRequest) as excinfo:
             legacy.file_upload(db_request)
 
         resp = excinfo.value
 
+        assert db_request.route_url.calls == [
+            pretend.call('help', _anchor='file-name-reuse')
+        ]
         assert resp.status_code == 400
-        assert resp.status == "400 File already exists."
+        assert resp.status == (
+            "400 File already exists. "
+            "See /the/help/url/"
+        )
 
     def test_upload_fails_with_wrong_filename(self, pyramid_config,
                                               db_request):

warehouse/forklift/legacy.py

@@ -1027,7 +1027,13 @@ 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 " +
+                                request.route_url(
+                                    'help', _anchor='file-name-reuse'
+                                )
+            )
 
         # Check to see if the file that was uploaded exists in our filename log
         if (request.db.query(
@@ -1037,7 +1043,10 @@ def file_upload(request):
             raise _exc_with_message(
                 HTTPBadRequest,
                 "This filename has previously been used, you should use a "
-                "different version.",
+                "different version. "
+                "See " + request.route_url(
+                    'help', _anchor='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>