Fix: many more great comments to address

Author: lwasser

index.md

@@ -128,35 +128,3 @@ Good meets the requirements. Going beyond the minimum can make package maintenan
 
 This guide is now a work in progress. If you have ideas of things you'd like
 to see here, [we invite you to open an issue on GitHub that details any changes or additions that you'd like to see.](https://github.com/pyOpenSci/python-package-guide/issues).
-
-<!--
-COMMENTED OUT TEXT TO BE MOVED
-
-
-# TODO LINK TO CI BUILDS FOR Documentation>
-Maybe we can curate a list of CI builds that people can use??? or is that moving too close to a cookie cutter situation
-
-The text below is being moved to the packaging infrastructure section which
-doesn't exist YET... but will soon .
-pyOpenSci packages must:
-
-- Contain full documentation for any user-facing functions.
-- Have a test suite that covers the major functionality of the package.
-- Use continuous integration.
-- Use an OSI approved software license.
-
-
-## Other recommendations
-### Python version support
-You should always be explicit about which versions of Python your package supports.
-Keeping compatibility with old Python versions can be difficult as functionality changes.
-A good rule of thumb is that the package should support, at least,
-the latest three Python versions (e.g., 3.8, 3.7, 3.6).
-
-### Code Style
-pyOpenSci encourages authors to consult [PEP 8](https://www.python.org/dev/peps/pep-0008/) for information on how to style your code.
-
-### Linting
-An automatic linter (e.g. flake8) can help ensure your code is clean and free of syntax errors. These can be integrated with your CI.
-
--->

package-structure-code/intro.md

@@ -61,21 +61,6 @@ package to be reviewed and accepted into our pyOpenSci open source ecosystem.
 Please check out our [package scope page](https://www.pyopensci.org/software-peer-review/about/package-scope.html) and [review requirements in our author guide](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#) if you are looking for pyOpenSci's Python package review requirements!
 ```
 
-<!--
-```{tip}
-### Python packaging resources that we love
-
-We think the resources below are excellent but each have particular opinions
-that you may or may not find in our packaging guide. For instance, the PyPA
-guide encourages users to store their package in a `src/package-name` directory.
-While we accept that approach many of our community members prefer to not use
-the `src` directory.
-
-* [Python packaging for research software engineers](https://merely-useful.tech/py-rse/)
-* [PyPA packaging guide](https://packaging.python.org/en/latest/)
-```
--->
-
 ```{toctree}
 :hidden:
 :caption: Package structure & code style

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

@@ -79,7 +79,7 @@ of values. It has two keys that specify the build front end and back-end for a p
 
 ```
 [build-system]
-requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2"]
+requires = ["setuptools>=45"]
 build-back-end = "setuptools.build_meta"
 
 [project]

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

@@ -168,17 +168,16 @@ questions:
 - Flit, Hatch, PDM or Poetry (read below for more)
 
 1. **Does your tool have a few C or C++ extensions?** Great, we suggest using
-   **PDM** for the time being. It is the only tool in the list below that has documented
-   workflow to support such extensions. It also supports other back-ends such as scikit-build and meson-python that will allow you to fully customize your build.
+   **PDM** for the time being. It is the only tool in the list below that has both documented
+   workflow to support such extensions and support for other back-ends in the case that build hooks are not enough for your workflow. PDM supports other back-ends such as scikit-build and meson-python that will allow you to fully customize your package's build.
 
-NOTE: You can also use Hatch for non pure python builds but you will need to
-write your own plugin for this support.
+NOTE: You can also use Hatch for non pure python builds. Hatch, similar to PDM, allows you to write your own build hooks or plugins to support custom build steps. But currently, hatch does not support other build back ends. Many of the core scientific packages are moving to meson-python to build their packages. Thus, we appreciate that PDM can work with meson-python specifically.
 
 ## Python packaging tools summary
 
-<!-- NOTE - add language around the front end means that you have less individual tools in your build - such as nox / make with hatch -->
+Below, we summarize features offered by the most popular build front end tools. It is important to keep in mind that these
+front-end tools remove the need to use other core tools in your workflow. For example if you use setuptools, you will need to also use Build and Twine to build your package and publish to PyPI. But if you use Poetry, Hatch or PDM you can do all of those things using the same tool (e.g. `hatch build`, `hatch publish` or `pdm build`, `pdm publish`).
 
-Below, we summarize features offered by the most popular build front end tools.
 Note that because setuptools does not offer a front-end interface, it is not
 included in the table.
 
@@ -313,7 +312,7 @@ using a tool like **Make** or **Nox**.
 
 Use Other Build Backends|✖| Switching out build back-ends is not currently an option when using Hatch. However this feature is coming to the package in the near future.
 Dependency management|✅|Hatch can help you add dependencies to your **pyproject.toml** metadata.
-Select your environment manager of choice (conda, venv, etc)|✅ | Hatch does allow you to select the (pip) environment that you want to use for managing and building your package. However if you want to use conda [you will need to use a plugin](https://github.com/OldGrumpyViking/hatch-conda).
+Select your environment manager of choice (conda, venv, etc)|✅ | Hatch does allow you to select the (pip) environment that you want to use for managing and building your package. However if you want to use Conda [you will need to use a plugin](https://github.com/OldGrumpyViking/hatch-conda).
 Publish to PyPI and test PyPI|✅|Hatch supports publishing to both test PyPI and PyPI
 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
@@ -336,7 +335,7 @@ These include:
 - Doesn't support dependency pinning
 - Currently doesn't support use with other build back-ends. Lack of support for other build back-ends makes Hatch less desirable for users with more complex package builds. If your package is pure
   Python, this won't be an issue. NOTE: there is a plan for this feature to be added in the upcoming months.
-- Doesn't allow you to select what environment manager you use. <!-- (is this right??) -->
+- Hatch won't by default support Conda environments. [But you can use a plugin for this!](https://github.com/OldGrumpyViking/hatch-conda).
 - Hatch doesn't provide an end to end beginning workflow in it's documentation.
 - Hatch, similar to PDM and Flit currently only has one maintainer.
 

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

@@ -26,7 +26,9 @@ 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
 built or compiled in any way. Thus, when a user installs your source
-distribution using pip, pip needs to run a build step first. Sdist is normally stored as a `.tar.gz` archive (often called a "tarball").
+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.
+
+Sdist is normally stored as a `.tar.gz` archive (often called a "tarball"). Thus, when a user installs your source distribution using pip, pip needs to run a build step first.
 
 Below is an example sdist for the stravalib Python package:
 
@@ -89,18 +91,6 @@ items including a metadata directory and if you use `setuptools_scm` or `hatch_v
 the SDist may also contain a file that stores the version.
 ```
 
-<!--
-* one of the benefits of wheel is pretty much avoiding setup.py which
-has code mixed in. makes you more vulnerable to a code injection on install.
-
-assuming this means if the package is already pre-built than setup.py isn't running anything on install because install is just moving files across to the machine to be run.
-
-And having metadata separate allows someone to view the metadata without
-running any python code as it's a machine and human readable format.
-
-https://scikit-hep.org/developer/pep621
--->
-
 ### Wheel (.whl files):
 
 A wheel file is a ZIP-format archive whose filename follows a specific format

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

@@ -1,12 +1,18 @@
 # Python Package Structure for Scientific Python Projects
 
-## Directories that should be in all Python packages
+## Directories that should be in your starting Python package repository
 
 There are several core directories that should be included in all Python packages:
 
 - **docs/:** discussed in our docs chapter, this directory contains your user-facing documentation website
 - **tests/** this directory contains the tests for your project code
-- **package-name/**: this is the directory that contains the code for your Python project. It is normally named using your project's name.
+- **src/package-name/**: this is the directory that contains the code for your Python project. It is normally named using your project's name.
+
+```{admonition} Multiple packages in a src/ folder
+:class: tip
+
+In some more advanced cases you may have more than one package in your src/ directory. See [black's GitHub repo](https://github.com/psf/black/tree/main/src) for an example of this. However for most beginners you will likely only have one sub-directory in your src/ folder.
+```
 
 ## Src vs flat layouts
 
@@ -63,6 +69,16 @@ that includes tests within the **src/package-name** directory.
 
 #### Pros of the src/ layout
 
+```{admonition} How Python discovers and prioritizes importing modules
+One of the main technical advantages of using the src/ layout, if you are just getting started with a new package,relates to how Python discovers packages. By default, Python adds a module in your current working directory to the  front of the Python module search path.
+
+This means that if you currently in your packages working directory, and your module code lives in the root e.g.: /package-name/module.py, python will discovers package-name/module.py before it the package as installed by pip or conda in a virtual environment.
+
+However, if your package lives in a directory structure that is **src/package-name** then it won't be, by default, added to the Python path. This means that when you run import package, python will be forced to first search the active environment (which has your package installed).
+
+Note that modern Python versions (3.11 and above) do have an option to adjust how the Python path finds modules (`PYTHONSAFEPATH`) however this is still a setting that a user would need to adjust in order to avoid the behavior of Python importing a module from your current working directory first.
+```
+
 The benefits of the **src/package-name** layout include:
 
 - It ensures that tests always run on the installed version of your
@@ -79,7 +95,11 @@ will want to ensure that large tests datasets are not included in your package d
 - The **src/package-name** layout is semantically more clear. Code is always found in the
   **src/package-name** directory, `tests/` and `docs/`are in the root directory.
 
-```{tip}
+```{admonition} A few notes about the src/ layout
+:class: tip
+
+It is important to note here that sometimes when using the src/package-name structure the directory name (e.g. package name) is different from the actual project or package name. What is important to take away here is that you should store your code within a sub directory within **src/**.
+
 * [Read more about reasons to use the **src/package-name** layout](https://hynek.me/articles/testing-packaging/)
 ```