From 578d2eca7232d429225d7de55f934ab303ad6f3f Mon Sep 17 00:00:00 2001 From: alvyjudy Date: Sun, 29 Mar 2020 21:40:38 -0400 Subject: [PATCH 1/7] initial draft for build_meta documentation --- docs/build_meta.txt | 88 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/build_meta.txt diff --git a/docs/build_meta.txt b/docs/build_meta.txt new file mode 100644 index 0000000000..bfba118193 --- /dev/null +++ b/docs/build_meta.txt @@ -0,0 +1,88 @@ +======================================= +Documentation to setuptools.build_meta +======================================= + +What is it? +------------- + +Setuptools, or Python packaging in general, has faced many +`criticism `_ and +`PEP517 `_ attempts to fix this +issue by ``get distutils-sig out of the business of being a gatekeeper for +Python build system``. + +A quick overview on the `current state of Python packaging +`_. The ``distutils`` +package specified the de facto standard way to bundle up your packages:: + + setup.py + mypkg/__init__.py + +And then you run ``python setup.py bdist`` and compressed ``.tar.gz`` will be +available for distribution. + +Following this tradition, several other enhancements have been made: ``pip`` +was created and user can run ``pip install`` on their downloaded distribution +file and it will be installed. ``wheel`` format was created to minimize the +build process for C extension. ``PyPI`` and ``twine`` then made it easier to +upload and download the distribution and finally ``setuptools`` extends the +original ``distutils`` and emcompass everything else and become the standard +way for Python packaging. (check the timeline for accuracy) + +I'll skip the many downsides and complexity that came with the development +of setuptools. PEP517 aims to solve these issues by specifying a new +standardized way to distribute your packages which is not as compatible as +the setuptools module. + +``build_meta.py`` therefore acts as an adaptor to the PEP517 and the existing +setuptools. + +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 + src/meowpkg/__init__.py + + +The pyproject.toml file is required by PEP517 and PEP518 to specify the build +system (i.e. what is being used to package your scripts). To use it with +setuptools, the content would be:: + + [build-system] + requires = ["setuptools", "wheel"] + build-backend = "setuptools.build-meta" + +The setup.cfg is used to specify your package information (essentially +replacing setup.py), specified on setuptools `documentation `_ :: + + [metadata] + name = meowpkg + version = 0.0.1 + description = a package that meows + + [options] + package_dir= + =src + packages = find: + + [options.packages.find] + where=src + +Now it's time to actually generate the distribution. PEP517 specifies two +mandatory functions, ``build_wheel`` and ``build_sdist``, implemented in +this module. Currently, it has to be done in the interpreter:: + + >>> import setuptools.build_meta + >>> setuptools.build_meta.build_wheel('wheel_dist') + 'meowpkg-0.0.1-py3-none-any.whl' + +And now it's done! The ``.whl`` file and ``.tar.gz`` can then be distributed +and installed! + From cc7186cde4238e9269beb2b19720380990759299 Mon Sep 17 00:00:00 2001 From: alvyjudy Date: Mon, 30 Mar 2020 13:25:17 -0400 Subject: [PATCH 2/7] First draft for build_meta documentation --- docs/build_meta.txt | 98 ++++++++++++++++++++++++--------------------- 1 file changed, 53 insertions(+), 45 deletions(-) diff --git a/docs/build_meta.txt b/docs/build_meta.txt index bfba118193..47e0aa7485 100644 --- a/docs/build_meta.txt +++ b/docs/build_meta.txt @@ -5,37 +5,39 @@ Documentation to setuptools.build_meta What is it? ------------- -Setuptools, or Python packaging in general, has faced many -`criticism `_ and -`PEP517 `_ attempts to fix this -issue by ``get distutils-sig out of the business of being a gatekeeper for -Python build system``. - -A quick overview on the `current state of Python packaging -`_. The ``distutils`` -package specified the de facto standard way to bundle up your packages:: - - setup.py - mypkg/__init__.py - -And then you run ``python setup.py bdist`` and compressed ``.tar.gz`` will be -available for distribution. - -Following this tradition, several other enhancements have been made: ``pip`` -was created and user can run ``pip install`` on their downloaded distribution -file and it will be installed. ``wheel`` format was created to minimize the -build process for C extension. ``PyPI`` and ``twine`` then made it easier to -upload and download the distribution and finally ``setuptools`` extends the -original ``distutils`` and emcompass everything else and become the standard -way for Python packaging. (check the timeline for accuracy) - -I'll skip the many downsides and complexity that came with the development -of setuptools. PEP517 aims to solve these issues by specifying a new -standardized way to distribute your packages which is not as compatible as -the setuptools module. - -``build_meta.py`` therefore acts as an adaptor to the PEP517 and the existing -setuptools. +Python packaging has come `a long way `_. + +The traditional ``setuptools``'s 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. Additionally, the ``setup.py`` scripts hasn't been the most user +friendly tool. + +PEP517 therefore came to rescue and specified a new standard to +package and distribute Python modules. Under PEP517: + + 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 and +in the case of ``setuptools``, ``setup.py`` becomes optional. + +``build_meta`` is ``setuptools``'s implementation of PEP517. It provides the +two functions, ``build_wheel`` and ``build_sdist``, amongst others and uses +a ``setup.cfg`` to specify the information about the package. How to use it? ------------- @@ -46,21 +48,20 @@ scripts, a ``pyproject.toml`` file and a ``setup.cfg`` file. ~/meowpkg/ pyproject.toml setup.cfg - src/meowpkg/__init__.py + meowpkg/__init__.py -The pyproject.toml file is required by PEP517 and PEP518 to specify the build -system (i.e. what is being used to package your scripts). To use it with +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" + build-backend = "setuptools.build_meta" -The setup.cfg is used to specify your package information (essentially -replacing setup.py), specified on setuptools `documentation `_ :: +``setup.cfg`` is used to specify your package information, specified +`here `_ :: [metadata] name = meowpkg @@ -68,13 +69,8 @@ using-setup-cfg-files>`_ :: description = a package that meows [options] - package_dir= - =src packages = find: - [options.packages.find] - where=src - Now it's time to actually generate the distribution. PEP517 specifies two mandatory functions, ``build_wheel`` and ``build_sdist``, implemented in this module. Currently, it has to be done in the interpreter:: @@ -82,7 +78,19 @@ this module. Currently, it has to be done in the interpreter:: >>> import setuptools.build_meta >>> setuptools.build_meta.build_wheel('wheel_dist') 'meowpkg-0.0.1-py3-none-any.whl' + >>> setuptools.build_meta.build_sdist('sdist') + 'meowpkg-0.0.1.tar.gz' And now it's done! The ``.whl`` file and ``.tar.gz`` can then be distributed -and installed! +and installed:: + + ~/newcomputer/ + meowpkg-0.0.1.whl + meowpkg-0.0.1.tar.gz + + $ pip install meowpkg-0.0.1.whl + +or:: + + $ pip install meowpkg-0.0.1.tar.gz From b5697f4458e0a2bbdb0d5a46222bb7e7adad8071 Mon Sep 17 00:00:00 2001 From: alvyjudy <53921639+alvyjudy@users.noreply.github.com> Date: Mon, 30 Mar 2020 13:27:31 -0400 Subject: [PATCH 3/7] deleted blank lines and fixed underline --- docs/build_meta.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/build_meta.txt b/docs/build_meta.txt index 47e0aa7485..8d92d80462 100644 --- a/docs/build_meta.txt +++ b/docs/build_meta.txt @@ -40,7 +40,7 @@ two functions, ``build_wheel`` and ``build_sdist``, amongst others and uses a ``setup.cfg`` to specify the information about the package. 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. @@ -49,8 +49,7 @@ scripts, a ``pyproject.toml`` file and a ``setup.cfg`` file. 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:: From 71af92d2e1f00162e46fe9c72370cad7e9bd0c5f Mon Sep 17 00:00:00 2001 From: alvyjudy <53921639+alvyjudy@users.noreply.github.com> Date: Mon, 30 Mar 2020 13:30:30 -0400 Subject: [PATCH 4/7] fixed some RST syntax --- docs/build_meta.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build_meta.txt b/docs/build_meta.txt index 8d92d80462..4467dddacb 100644 --- a/docs/build_meta.txt +++ b/docs/build_meta.txt @@ -21,7 +21,7 @@ package and distribute Python modules. Under PEP517: 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)`` + 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. @@ -43,7 +43,7 @@ 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. +scripts, a ``pyproject.toml`` file and a ``setup.cfg`` file:: ~/meowpkg/ pyproject.toml From 19e45c14e49fa3e6cc849b69b3a83f85f316441c Mon Sep 17 00:00:00 2001 From: alvyjudy Date: Mon, 30 Mar 2020 13:49:29 -0400 Subject: [PATCH 5/7] added changelog file --- changelog.d/1698.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/1698.doc.rst diff --git a/changelog.d/1698.doc.rst b/changelog.d/1698.doc.rst new file mode 100644 index 0000000000..9b61fccb4c --- /dev/null +++ b/changelog.d/1698.doc.rst @@ -0,0 +1 @@ +Added documentation for ``build_meta`` (a bare minimum, not completed) From d2a64aebe4fd7b02c9d05a0cac30faac38f18977 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 3 May 2020 05:51:59 -0400 Subject: [PATCH 6/7] Apply suggestions from code review --- changelog.d/1698.doc.rst | 2 +- docs/build_meta.txt | 42 ++++++++++++++++++++-------------------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/changelog.d/1698.doc.rst b/changelog.d/1698.doc.rst index 9b61fccb4c..90dc14c1f4 100644 --- a/changelog.d/1698.doc.rst +++ b/changelog.d/1698.doc.rst @@ -1 +1 @@ -Added documentation for ``build_meta`` (a bare minimum, not completed) +Added documentation for ``build_meta`` (a bare minimum, not completed). diff --git a/docs/build_meta.txt b/docs/build_meta.txt index 4467dddacb..6749789148 100644 --- a/docs/build_meta.txt +++ b/docs/build_meta.txt @@ -1,5 +1,5 @@ ======================================= -Documentation to setuptools.build_meta +Build System Support ======================================= What is it? @@ -7,16 +7,18 @@ What is it? Python packaging has come `a long way `_. -The traditional ``setuptools``'s way of packgaging Python modules +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. Additionally, the ``setup.py`` scripts hasn't been the most user -friendly tool. +overhaul. Because ``setup.py`` scripts allowed for arbitrary execution, it +proved difficult to provide a reliable user experience across environments +and history. -PEP517 therefore came to rescue and specified a new standard to -package and distribute Python modules. Under PEP517: +`PEP 517 `_ 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. @@ -35,8 +37,8 @@ package and distribute Python modules. Under PEP517: With this standard, switching between packaging tools becomes a lot easier and in the case of ``setuptools``, ``setup.py`` becomes optional. -``build_meta`` is ``setuptools``'s implementation of PEP517. It provides the -two functions, ``build_wheel`` and ``build_sdist``, amongst others and uses +``build_meta`` is ``setuptools``'s implementation of PEP 517. It provides the +two functions, ``build_wheel`` and ``build_sdist`` amongst others, and uses a ``setup.cfg`` to specify the information about the package. How to use it? @@ -58,7 +60,7 @@ setuptools, the content would be:: requires = ["setuptools", "wheel"] build-backend = "setuptools.build_meta" -``setup.cfg`` is used to specify your package information, specified +Use ``setup.cfg`` to specify your package information, specified `here `_ :: @@ -70,26 +72,24 @@ setuptools, the content would be:: [options] packages = find: -Now it's time to actually generate the distribution. PEP517 specifies two -mandatory functions, ``build_wheel`` and ``build_sdist``, implemented in -this module. Currently, it has to be done in the interpreter:: +Now generate the distribution. Although the PyPA is still working to +`provide a recommended tool `_ +to build packages, the `pep517 package >> import setuptools.build_meta - >>> setuptools.build_meta.build_wheel('wheel_dist') - 'meowpkg-0.0.1-py3-none-any.whl' - >>> setuptools.build_meta.build_sdist('sdist') - 'meowpkg-0.0.1.tar.gz' + $ 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:: - ~/newcomputer/ + dist/ meowpkg-0.0.1.whl meowpkg-0.0.1.tar.gz - $ pip install meowpkg-0.0.1.whl + $ pip install dist/meowpkg-0.0.1.whl or:: - $ pip install meowpkg-0.0.1.tar.gz - + $ pip install dist/meowpkg-0.0.1.tar.gz From cc5b5ec305100ecd897edfc7918f184ffc93c197 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 3 May 2020 05:59:41 -0400 Subject: [PATCH 7/7] Apply suggestions from code review --- docs/build_meta.txt | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/build_meta.txt b/docs/build_meta.txt index 6749789148..ef9fb2ac5d 100644 --- a/docs/build_meta.txt +++ b/docs/build_meta.txt @@ -34,12 +34,8 @@ package and distribute Python modules. Under PEP 517: ``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 and -in the case of ``setuptools``, ``setup.py`` becomes optional. - -``build_meta`` is ``setuptools``'s implementation of PEP 517. It provides the -two functions, ``build_wheel`` and ``build_sdist`` amongst others, and uses -a ``setup.cfg`` to specify the information about the package. +With this standard, switching between packaging tools becomes a lot easier. ``build_meta`` +implements ``setuptools``' build system support. How to use it? -------------- @@ -60,9 +56,7 @@ setuptools, the content would be:: requires = ["setuptools", "wheel"] build-backend = "setuptools.build_meta" -Use ``setup.cfg`` to specify your package information, specified -`here `_ :: +Use ``setuptools``' `declarative config`_ to specify the package information:: [metadata] name = meowpkg