Update to pyansys-template

Author: jorgepiloto

doc/source/library_description/packaging.rst

@@ -2,64 +2,178 @@
 
 Packaging
 #########
-A Python package organizes and structures a Python library, which contains several
-modules and assets such as examples or binary extensions. A Python package
-offers an easy, reliable, and comprehensive way to distribute and install
-a Python library on a variety of platforms and environments.
+
+A Python package organizes and structures a Python library, which contains
+several modules and assets such as examples or binary extensions. A Python
+package offers an easy, reliable, and comprehensive way to distribute and
+install a Python library on a variety of platforms and environments.
+
+.. note::
+
+   If you want to create a new PyAnsys project according to the guidelines
+   presented in the following lines, consider using the `pyansys template`_.
+
+
+Python scripts, modules, sub-packages and packages
+--------------------------------------------------
+
+It is important to understand the difference between Python scripts, modules,
+sub-packages and packages:
+
+* ``Script``: any Python file holding logic source code.
+* ``Module``: any Python script hosted next to an ``__init__.py`` file.
+* ``Sub-package``: any directory holding various Python modules.
+* ``Package``: any directory which contains Python modules and sub-packages.
+
+The following structure is shown to better explain previous concepts:
+
+.. code:: bash
+
+    .
+    ├── src
+    │   └── package
+    │       ├── subpackage_a
+    │       │   ├── __init__.py
+    │       │   └── module_c.py
+    │       ├── __init__.py
+    │       ├── module_a.py
+    │       └── module_b.py
+    ├── LICENSE
+    ├── README.rst
+    └── pyproject.toml
+
 
 Namespace Packaging
 -------------------
-A PyAnsys library uses `namespace packaging`_.
-Namespace packages allow a user to easily split subpackages from a package into
-single, independent distributions.
+A PyAnsys library uses `namespace packaging`_.  Namespace packages allow a user
+to easily split sub-packages from a package into single, independent
+distributions.
+
+There are different approaches available for creating a namespace package. For
+the ``ansys`` namespace, we use the `PEP 420`_ `native namespace packages`_
+approach.
+
+Following previous namespace, the source directory of any `PyAnsys library`
+should look like this:
+
+.. code:: bash
+
+    .
+    └── src
+        └── ansys
+            └── product
+                └── library
+                    └── __init__.py
 
-There are different approaches available for creating a namespace package. For the
-``ansys`` namespace, we use the `PEP 420`_ `native namespace packages`_ approach.
 
 Required Files
 --------------
 
-* README.rst file: Describes the purpose of the package.
+* ``README.rst`` file: Describes the purpose of the package.
   *The format of this file must be reStructuredText.*
 
-* LICENSE file: Specifies copyrights and required authorization.
+* ``LICENSE`` file: Specifies copyrights and required authorization.
 
-* pyproject.toml file: Provides package information.
+* ``pyproject.toml`` file: Provides package information.
   This file provides the package metadata, and defines how it is built.
   There are different build backends available, such as `setuptools`_,
   `poetry`_ and `flit`_.
 
+* ``src/ansys/product/library/__init__.py`` file: This file usually holds the
+  version of the package in a variable named ``__version__``. The value of this
+  variable can be parsed from the `pyproject.toml` file, so it is only specified
+  in one location.
 
-Project Configuration File
---------------------------
+
+Additional Directories
+----------------------
+
+The following directories may be specified at the same level of ``src/`` one:
+
+* ``tests/``: This directory holds all unitary tests of the package. It is
+  likely that those take advantage of the `pytest`_ framework.
+
+* ``doc/``: A directory devoted to hold all documentation files and examples on
+  how to use the package.
+
+
+Project File and Build System
+------------------------------
 
 The ``pyproject.toml`` file is the standardized build configuration file for Python
 projects. It needs to at least contain a ``[build-system]`` section, which determines
 how the project is built. Some commonly used packaging tools are `setuptools`_,
-`poetry`_, or `flit`_.
+`poetry`_, or `flit`_. All these three build systems are currently supported by
+the `pyansys template`_.
+
+
+Flit
+^^^^
 
-We use `poetry`_ as a default choice in the `PyAnsys template`_, for the following reasons:
-* it supports pinning dependency versions, which we use for testing / CI
-* downstream packages can still consume a loose dependency specification
-* it integrates with `dependabot`_ to update the pinned version
+It is a modern and lightweight build system. Using this tool requires
+developers to manage virtual environments by their own, that is:
 
-Feel free to use any one of the packaging tools mentioned above that best suits
-your needs. The advantage of `flit`_ is its simplicity, while `setuptools`_ is most useful
-when custom build steps need to be implemented as Python code.
+* Creating a virtual environment and activating it.
+* Installing the package in editable mode.
 
-To use `poetry`_ as a packaging tool, the ``pyproject.toml`` should contain
+This tool is the default one for creating a new project when using the
+`pyansys template`_.
 
-.. code:: toml
+The ``[project]`` section is used for specifying project's metadata and required
+dependencies. More information can be found in the `flit pyproject.toml
+guidelines`_.
 
-  [build-system]
-  requires = ["poetry-core>=1.0.0"]
-  build-backend = "poetry.core.masonry.api"
 
-The ``[tool.poetry]`` section contains metadata, and defines the project's dependencies. Refer to the
-`poetry pyproject.toml documentation`_ for details.
+Poetry
+^^^^^^
+
+Poetry is known because of its strong dependency pinning thanks to the
+``poetry.lock`` file. When installing a package, poetry creates a virtual
+environment, thus ensuring an isolated package development environment.
+
+It is possible to avoid previous behavior by executing the following command:
+
+.. code:: bash
+
+   poetry config virtualenvs.create false --local
+
+Therefore, `poetry`_ may be chosen due to the following reasons:
+
+* It supports pinning dependency versions via a ``poetry.lock`` file, which we
+  use for testing / CI.
+* Downstream packages can still consume a loose dependency specification.
+* It integrates with `dependabot`_ to update the pinned version.
+
+The ``[tool.poetry]`` section contains metadata, and defines the project's
+dependencies. Refer to the `poetry pyproject.toml documentation`_ for details.
+
+
+Setuptools
+^^^^^^^^^^
+
+Setuptools is a very well known build system in the Python ecosystem. It is used
+in projects requiring a ``setup.py``. Setuptools can be used with projects using
+the ``pyproject.toml`` too, although not all metadata is fully supported yet.
+
+The main advantage of this build system is the ability of creating custom build
+steps in the form of Python code.
+
+
+Specifying Package Version
+--------------------------
+
+It is very common for packages to specify their current version in the
+``__version__`` variable. This variable is usually declared in the
+``__init__.py`` file included in the ``library`` directory.
+
+However, it is also required to specify the version in the ``pyproject.toml`` or
+``setup.py``. This leads to a duplicate declaration of the project's version,
+which could lead to a potential mismatch between both.
+
+Therefore, a good practice is to take advantage of the `importlib.metadata package`_,
+for parsing the version from package metadata. This guarantees no mismatch
+between both version declarations.
 
-Since poetry cannot automatically determine a package's version, we instead specify it in the ``[tool.poetry]``
-section, and add code to ``__init__.py`` which obtains the version from the installation metadata:
 
 .. code:: python
 
@@ -71,14 +185,26 @@ section, and add code to ``__init__.py`` which obtains the version from the inst
   __version__ = importlib_metadata.version(__name__.replace(".", "-"))
 
 
-Where supported, we aim to put all tooling-related configuration into ``pyproject.toml``.
-For example, it can also be used to configure the code formatter `black`_ or the static
-type checker `mypy`_.
+Extra Tools Configuration
+-------------------------
+
+There are plenty of tools in the Python ecosystem which enable developers to
+write clean code according to different coding style guidelines. Some of these
+tools are `black`_, `isort`_, `flake8`_, `mypy`_...
+
+Some of these tools can be configured. This configuration might be specified in
+custom files required by the tool or in the ``pyproject.toml`` reducing thus the
+amount of files in the project directory.
 
 .. note::
 
-  When using `setuptools`_ as a build backend, providing the metadata in ``pyproject.toml`` is not yet fully supported.
-  Instead, it also requires a ``setup.cfg`` and / or ``setup.py`` file.
+  When using `setuptools`_ as a build backend, providing the metadata in
+  ``pyproject.toml`` is not yet fully supported.  Instead, it also requires a
+  ``setup.cfg`` and / or ``setup.py`` file.
+
+In the `pyansys template`, all these configurations are included by default in
+the `.pre-commit-config.yaml`, as `pre-commit` is not able to parse the
+``pyproject.toml`` file neither the ``setup.py`` one.
 
 
 Generate the Package and Upload It on PyPI
@@ -94,15 +220,28 @@ Create the python package.
   pip install build
   python -m build
 
+If using flit or poetry, you can also run:
+
+.. code::
+
+   flit build
+   poetry build
+
 Verify the distribution's long description rendering with ``twine``.
 
 .. code::
 
   pip install twine
   twine check dist/*
 
-Upload the package to PyPI using ``twine`` and the upload token generated for the ``ansys`` PyPI account.
-Contact [email protected] for the token.
+
+Upload the package to PyPI using ``twine`` and the upload token generated for
+the ``ansys`` PyPI account.  As soon as the package has been released for the
+first time, it is possible to create an independent token dedicated to this
+package.  This way the token stored in the GitHub secrets and used in the
+release's workflow is only related to that specific package.  This limits the
+exposure to any potential token security flaws.  Contact
+[email protected] for the token.
 
 .. code::
 
@@ -169,12 +308,17 @@ To create a package complying with the above standards, here is the minimal cont
 .. _PEP 420: https://www.python.org/dev/peps/pep-0420/
 .. _setuptools: https://setuptools.pypa.io
 .. _poetry: https://python-poetry.org/docs/
+.. _flit pyproject.toml guidelines: https://flit.readthedocs.io/en/latest/pyproject_toml.html
 .. _flit: https://flit.readthedocs.io
 .. _dependabot: https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates
-.. _PyAnsys template: https://github.com/pyansys/template
+.. _pyansys template: https://github.com/pyansys/pyansys-template
 .. _poetry pyproject.toml documentation: https://python-poetry.org/docs/pyproject/
 .. _black: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file
 .. _mypy: https://mypy.readthedocs.io/en/stable/config_file.html#the-mypy-configuration-file
 .. _trunk-based development: https://trunkbaseddevelopment.com/
 .. _secret: https://docs.github.com/en/actions/reference/encrypted-secrets
 .. _setup.py: https://packaging.python.org/tutorials/packaging-projects/#configuring-metadata
+.. _importlib.metadata package: https://docs.python.org/3/library/importlib.metadata.html
+.. _isort: https://github.com/PyCQA/isort
+.. _flake8: https://flake8.pycqa.org/en/latest/
+.. _pytest: https://docs.pytest.org/en/latest/