Merge branch 'master' of https://github.com/pypa/setuptools

5 files changed, 123 insertions, 0 deletions

diff --git a/changelog.d/1698.doc.rst b/changelog.d/1698.doc.rst
new file mode 100644
index 00000000..90dc14c1
--- /dev/null
+++ b/changelog.d/1698.doc.rst
@@ -0,0 +1 @@
+Added documentation for ``build_meta`` (a bare minimum, not completed).
diff --git a/changelog.d/2040.change.rst b/changelog.d/2040.change.rst
new file mode 100644
index 00000000..b8f36f6f
--- /dev/null
+++ b/changelog.d/2040.change.rst
@@ -0,0 +1 @@
+Deprecated the ``bdist_wininst`` command. Binary packages should be built as wheels instead.
diff --git a/docs/build_meta.txt b/docs/build_meta.txt
new file mode 100644
index 00000000..ef9fb2ac
--- /dev/null
+++ b/docs/build_meta.txt
@@ -0,0 +1,89 @@
+=======================================
+Build System Support
+=======================================
+
+What is it?
+-------------
+
+Python packaging has come `a long way <https://www.bernat.tech/pep-517-518/>`_.
+
+The traditional ``setuptools`` way of packgaging Python modules
+uses a ``setup()`` function within the ``setup.py`` script. Commands such as
+``python setup.py bdist`` or ``python setup.py bdist_wheel`` generate a 
+distribution bundle and ``python setup.py install`` installs the distribution. 
+This interface makes it difficult to choose other packaging tools without an 
+overhaul. Because ``setup.py`` scripts allowed for arbitrary execution, it
+proved difficult to provide a reliable user experience across environments
+and history.
+
+`PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_ therefore came to
+rescue and specified a new standard to 
+package and distribute Python modules. Under PEP 517:
+
+    a ``pyproject.toml`` file is used to specify what program to use
+    for generating distribution. 
+
+    Then, two functions provided by the program, ``build_wheel(directory: str)`` 
+    and ``build_sdist(directory: str)`` create the distribution bundle at the 
+    specified ``directory``. The program is free to use its own configuration 
+    script or extend the ``.toml`` file. 
+
+    Lastly, ``pip install *.whl`` or ``pip install *.tar.gz`` does the actual
+    installation. If ``*.whl`` is available, ``pip`` will go ahead and copy
+    the files into ``site-packages`` directory. If not, ``pip`` will look at
+    ``pyproject.toml`` and decide what program to use to 'build from source' 
+    (the default is ``setuptools``)
+
+With this standard, switching between packaging tools becomes a lot easier. ``build_meta``
+implements ``setuptools``' build system support.
+
+How to use it?
+--------------
+
+Starting with a package that you want to distribute. You will need your source
+scripts, a ``pyproject.toml`` file and a ``setup.cfg`` file::
+
+    ~/meowpkg/
+        pyproject.toml
+        setup.cfg
+        meowpkg/__init__.py
+
+The pyproject.toml file is required to specify the build system (i.e. what is 
+being used to package your scripts and install from source). To use it with 
+setuptools, the content would be::
+
+    [build-system]
+    requires = ["setuptools", "wheel"]
+    build-backend = "setuptools.build_meta" 
+
+Use ``setuptools``' `declarative config`_ to specify the package information::
+
+    [metadata]
+    name = meowpkg
+    version = 0.0.1
+    description = a package that meows
+    
+    [options]
+    packages = find:
+
+Now generate the distribution. Although the PyPA is still working to
+`provide a recommended tool <https://github.com/pypa/packaging-problems/issues/219>`_
+to build packages, the `pep517 package <https://pypi.org/project/pep517`_
+provides this functionality. To build the package::
+
+    $ pip install -q pep517
+    $ mkdir dist
+    $ python -m pep517.build .
+
+And now it's done! The ``.whl`` file  and ``.tar.gz`` can then be distributed 
+and installed::
+
+    dist/
+        meowpkg-0.0.1.whl
+        meowpkg-0.0.1.tar.gz
+
+    $ pip install dist/meowpkg-0.0.1.whl
+
+or::
+
+    $ pip install dist/meowpkg-0.0.1.tar.gz
diff --git a/setuptools/command/bdist_wininst.py b/setuptools/command/bdist_wininst.py
index 073de97b..ff4b6345 100644
--- a/setuptools/command/bdist_wininst.py
+++ b/setuptools/command/bdist_wininst.py
@@ -1,4 +1,7 @@
 import distutils.command.bdist_wininst as orig
+import warnings
+
+from setuptools import SetuptoolsDeprecationWarning
 
 
 class bdist_wininst(orig.bdist_wininst):
@@ -14,6 +17,12 @@ class bdist_wininst(orig.bdist_wininst):
         return cmd
 
     def run(self):
+        warnings.warn(
+            "bdist_wininst is deprecated and will be removed in a future "
+            "version. Use bdist_wheel (wheel packages) instead.",
+            SetuptoolsDeprecationWarning
+        )
+
         self._is_running = True
         try:
             orig.bdist_wininst.run(self)
diff --git a/setuptools/tests/test_bdist_deprecations.py b/setuptools/tests/test_bdist_deprecations.py
new file mode 100644
index 00000000..704164aa
--- /dev/null
+++ b/setuptools/tests/test_bdist_deprecations.py
@@ -0,0 +1,23 @@
+"""develop tests
+"""
+import mock
+
+import pytest
+
+from setuptools.dist import Distribution
+from setuptools import SetuptoolsDeprecationWarning
+
+
+@mock.patch("distutils.command.bdist_wininst.bdist_wininst")
+def test_bdist_wininst_warning(distutils_cmd):
+    dist = Distribution(dict(
+        script_name='setup.py',
+        script_args=['bdist_wininst'],
+        name='foo',
+        py_modules=['hi'],
+    ))
+    dist.parse_command_line()
+    with pytest.warns(SetuptoolsDeprecationWarning):
+        dist.run_commands()
+
+    distutils_cmd.run.assert_called_once()