some packaging improvements

Author: ucodery

package-structure-code/intro.md

@@ -58,8 +58,7 @@ simple. However, some scientific packages have complex requirements as they may
 need to support extensions or tools written in other languages such as C or C++.
 
 To support the many different uses of Python, there are many ways to create a
-Python package. In this guide, we suggest approaches for packaging approaches
-and tools based on:
+Python package. In this guide, we suggest packaging approaches and tools based on:
 
 1. What we think will be best and easiest to adopt for those who are newer to
    packaging.

package-structure-code/pyproject-toml-python-package-metadata.md

@@ -77,14 +77,14 @@ In this example package setup you use:
 - **setuptools_scm** to manage package version updates using version control tags
 
 In the example below `[build-system]` is the first table
-of values. It has two keys that specify the build frontend and backend for a package:
+of values. It has two keys that specify the build backend API and containing package:
 
 1. `requires =`
 1. `build-back-end =`
 
 ```
 [build-system]
-requires = ["setuptools>=45"]
+requires = ["setuptools>=61"]
 build-backend = "setuptools.build_meta"
 
 [project]

package-structure-code/python-package-build-tools.md

@@ -68,7 +68,7 @@ to a package build that does not have extensions that are written in another
 programming language (such as `C` or `C++`).
 
 Other packages that have C and C++ extensions (or that wrap other languages such as fortran) require additional code compilation steps when built.
-Back-ends such as and **setuptools.build**, **meson.build**
+Back-ends such as **setuptools.build**, **meson.build**
 and **scikit-build** support complex builds with custom steps. If your
 build is particularly complex (i.e. you have more than a few `C`/`C++`
 extensions), then we suggest you use **meson.build** or **scikit-build**.
@@ -78,7 +78,7 @@ extensions), then we suggest you use **meson.build** or **scikit-build**.
 A packaging front-end tool refers to a tool that makes it easier for you to
 perform common packaging tasks using similar commands. These tasks include:
 
-- [Build your packages (create the sdist and wheel distributions](python-package-distribution-files-sdist-wheel)
+- [Build your packages (create the sdist and wheel distributions)](python-package-distribution-files-sdist-wheel)
 - Installing your package in a development mode (so it updates when you update your code)
 - Publishing to PyPI
 - Running tests
@@ -260,6 +260,14 @@ Build your sdist and wheel distributions|✅| Similar to all of the other tools
 ✨Optional use of PEP 582 / local environment directory✨|✅| PDM is currently the only tool that optionally supports PEP 582 (having a local environment configuration stored within a `__pypackages__` directory in your working directory).
 ```
 
+```{admonition} PEP 582 was rejected
+:class: important
+
+While [PEP 582](https://peps.python.org/pep-0582), use of local packages directory `__pypackages__`,
+sought to implement a more lightweight form of Python environment management it currently stands
+as a rejected standard in the broader Python community.
+```
+
 ```{admonition} PDM vs. Poetry
 The functionality of PDM is similar to Poetry. However, PDM also offers
 additional, documented support for C extensions and version control based
@@ -349,7 +357,7 @@ Publish to PyPI and test PyPI|✅|Hatch supports publishing to both test PyPI an
 Version Control based versioning|✅ | Hatch offers `hatch_vcs` which is a plugin that uses setuptools_scm to support versioning using git tags. The workflow with `hatch_vcs` is the same as that with `setuptools_scm`.
 Version bumping| ✅ | Hatch supports you bumping the version of your package using standard semantic version terms patch; minor; major
 Follows current packaging standards|✅|Hatch supports current packaging standards for adding metadata to the **pyproject.toml** file.
-Install your package in editable mode|✖✅| You can install your package in editable mode using `pip install -e .` Hatch mentions [editable installs](https://hatch.pypa.io/latest/config/build/#dev-mode) but refers to pip in its documentation.
+Install your package in editable mode|✔️| You can install your package in editable mode using `pip install -e .` Hatch mentions [editable installs](https://hatch.pypa.io/latest/config/build/#dev-mode) but refers to pip in its documentation.
 Build your sdist and wheel distributions|✅| Hatch will build the sdist and wheel distributions
 ✨Matrix environment creation to support testing across Python versions✨|✅| The matrix environment creation is a feature that is unique to Hatch in the packaging ecosystem. This feature is useful if you wish to test your package locally across Python versions (instead of using a tool such as tox).
 ✨[Nox / MAKEFILE like functionality](https://hatch.pypa.io/latest/environment/#selection)✨| ✅| This feature is also unique to Hatch. This functionality allows you to create workflows in the **pyproject.toml** configuration to do things like serve docs locally and clean your package build directory. This means you may have one less tool in your build workflow.
@@ -395,7 +403,7 @@ Lock files| ✅ | Poetry creates a **poetry.lock** file that you can use if you
 Publish to PyPI and test PyPI|✅|Poetry supports publishing to both test PyPI and PyPI
 Version Control based versioning|✅ | The plugin [Poetry dynamic versioning](https://github.com/mtkennerly/poetry-dynamic-versioning) supports versioning using git tags with Poetry.
 Version bumping| ✅ | Poetry supports you bumping the version of your package using standard semantic version terms patch; minor; major
-Follows current packaging standards|✖✅|Poetry does not quite support current packaging standards for adding metadata to the **pyproject.toml** file but plans to fix this in an upcoming release.
+Follows current packaging standards|✔️|Poetry does not quite support current packaging standards for adding metadata to the **pyproject.toml** file but plans to fix this in an upcoming release.
 Install your package in editable mode|✅|Poetry supports installing your package in editable mode using `--editable`
 Build your sdist and wheel distributions|✅|Poetry will build your sdist and wheel distributions using `poetry build`
 ```
@@ -477,6 +485,6 @@ when using setuptools. For instance:
 
 - setuptools will build a project without a name or version if you are not using a **pyproject.toml** file
   to store metadata.
-  \*Setuptools also will include all of the files in your package
+- setuptools also will include all of the files in your package
   repository if you do not explicitly tell it to exclude files using a
   **MANIFEST.in** file

package-structure-code/python-package-distribution-files-sdist-wheel.md

@@ -24,7 +24,7 @@ Also note that we are not discussing conda build workflows in this section.
 package. These are the "raw / as-is" files that you store on GitHub or whatever
 platform you use to manage your code.
 
-**S**ource **D**istributions are referred to as sdist. As the name implies, a SDIST contains the source code; it has not been
+**S**ource **Dist**ributions are referred to as sdist. As the name implies, a SDIST contains the source code; it has not been
 built or compiled in any way. Thus, when a user installs your source
 distribution using pip, pip needs to run a build step first. For this reason, you could define a source distribution as a compressed archive that contains everything required to build a wheel (except for project dependencies) without network access.
 
@@ -103,7 +103,7 @@ distribution.
 The wheel (.whl) is your built binary distribution. **Binary files** are the built / compiled source files. These files are ready to be installed. A wheel (**.whl**) is a **zip** file containing all of the files needed to directly install your package. All of the files in a wheel are binaries - this means that code is already compiled / built. Wheels are thus faster to install - particularly if you have a package that requires build steps.
 
 The wheel does not contain any of your
-packages configuration files such as **setup.cfg** or **pyproject.toml**. This
+package's configuration files such as **setup.cfg** or **pyproject.toml**. This
 distribution is already built so it's ready to install.
 
 Because it is built, the wheel file will be faster to install for pure Python

package-structure-code/python-package-structure.md

@@ -16,7 +16,7 @@ We understand that it would be tremendous effort for existing
 maintainers to move to a new layout.
 
 The overview on this page presents recommendations that we think are best for
-something getting started with Python packaging or someone who's package is
+someone getting started with Python packaging or someone who's package
 has a simple build and might be open to moving to a more fail-proof approach.
 ```
 
@@ -32,10 +32,10 @@ myPackageRepoName
 │   └── ...                    │
 ├── LICENSE                    │
 ├── README.md                  ┘
-├── pyproject.toml             ┐
-├── src                        │
-│   └── myPackage              │ Package source code, metadata,
-│       ├── __init__.py        │ and build instructions
+├── pyproject.toml             ] Package metadata and build configuration
+├── src                        ┐
+│   └── myPackage              │
+│       ├── __init__.py        │ Package source code
 │       ├── moduleA.py         │
 │       └── moduleB.py         ┘
 └── tests                      ┐
@@ -58,6 +58,8 @@ include:
 - LICENSE.txt
 - README.md
 
+<!-- TODO: CHANGELOG is not mentioned in either documentation nor peer review -->
+
 ```{button-link} https://www.pyopensci.org/python-package-guide/documentation
 :color: primary
 :class: sd-rounded-pill
@@ -213,9 +215,9 @@ There are some benefits to the scientific community in using the flat layout.
 
 - This structure has historically been used across the ecosystem and packages
   using it are unlikely to change.
-- You can directly import the package directly from the root directory. For
-  some this is engrained in their respective workflows. However, for a beginner
-  the danger of doing this is that you are not developing and testing against the
+- You can import the package directly from the root directory. For some this
+  is engrained in their respective workflows. However, for a beginner the
+  danger of doing this is that you are not developing and testing against the
   installed version of your package. Rather, you are working directly with the
   flat files.