Add documentation for the packaging module.
This updates the user guide to refer to Packaging instead of Distutils.
Some files still require an update.
diff --git a/Doc/library/packaging.tests.pypi_server.rst b/Doc/library/packaging.tests.pypi_server.rst
new file mode 100644
index 0000000..f3b7720
--- /dev/null
+++ b/Doc/library/packaging.tests.pypi_server.rst
@@ -0,0 +1,105 @@
+:mod:`packaging.tests.pypi_server` --- PyPI mock server
+=======================================================
+
+.. module:: packaging.tests.pypi_server
+ :synopsis: Mock server used to test PyPI-related modules and commands.
+
+
+When you are testing code that works with Packaging, you might find these tools
+useful.
+
+
+The mock server
+---------------
+
+.. class:: PyPIServer
+
+ PyPIServer is a class that implements an HTTP server running in a separate
+ thread. All it does is record the requests for further inspection. The recorded
+ data is available under ``requests`` attribute. The default
+ HTTP response can be overridden with the ``default_response_status``,
+ ``default_response_headers`` and ``default_response_data`` attributes.
+
+ By default, when accessing the server with urls beginning with `/simple/`,
+ the server also record your requests, but will look for files under
+ the `/tests/pypiserver/simple/` path.
+
+ You can tell the sever to serve static files for other paths. This could be
+ accomplished by using the `static_uri_paths` parameter, as below::
+
+ server = PyPIServer(static_uri_paths=["first_path", "second_path"])
+
+
+ You need to create the content that will be served under the
+ `/tests/pypiserver/default` path. If you want to serve content from another
+ place, you also can specify another filesystem path (which needs to be under
+ `tests/pypiserver/`. This will replace the default behavior of the server, and
+ it will not serve content from the `default` dir ::
+
+ server = PyPIServer(static_filesystem_paths=["path/to/your/dir"])
+
+
+ If you just need to add some paths to the existing ones, you can do as shown,
+ keeping in mind that the server will always try to load paths in reverse order
+ (e.g here, try "another/super/path" then the default one) ::
+
+ server = PyPIServer(test_static_path="another/super/path")
+ server = PyPIServer("another/super/path")
+ # or
+ server.static_filesystem_paths.append("another/super/path")
+
+
+ As a result of what, in your tests, while you need to use the PyPIServer, in
+ order to isolates the test cases, the best practice is to place the common files
+ in the `default` folder, and to create a directory for each specific test case::
+
+ server = PyPIServer(static_filesystem_paths = ["default", "test_pypi_server"],
+ static_uri_paths=["simple", "external"])
+
+
+Base class and decorator for tests
+----------------------------------
+
+.. class:: PyPIServerTestCase
+
+ ``PyPIServerTestCase`` is a test case class with setUp and tearDown methods that
+ take care of a single PyPIServer instance attached as a ``pypi`` attribute on
+ the test class. Use it as one of the base classes in your test case::
+
+
+ class UploadTestCase(PyPIServerTestCase):
+
+ def test_something(self):
+ cmd = self.prepare_command()
+ cmd.ensure_finalized()
+ cmd.repository = self.pypi.full_address
+ cmd.run()
+
+ environ, request_data = self.pypi.requests[-1]
+ self.assertEqual(request_data, EXPECTED_REQUEST_DATA)
+
+
+.. decorator:: use_pypi_server
+
+ You also can use a decorator for your tests, if you do not need the same server
+ instance along all you test case. So, you can specify, for each test method,
+ some initialisation parameters for the server.
+
+ For this, you need to add a `server` parameter to your method, like this::
+
+ class SampleTestCase(TestCase):
+
+ @use_pypi_server()
+ def test_something(self, server):
+ ...
+
+
+ The decorator will instantiate the server for you, and run and stop it just
+ before and after your method call. You also can pass the server initializer,
+ just like this::
+
+ class SampleTestCase(TestCase):
+
+ @use_pypi_server("test_case_name")
+ def test_something(self, server):
+ ...