Packaging ========= Packaging is the process for distributing software to guarantee that final users can use it. By packaging Python libraries, it is possible to declare which source code or binary files must be distributed, project metadata, and third-party dependencies. :ref:`Packaging style` collects the fundamentals of Python packaging and packaging style guidelines that apply to PyAnsys projects. Dependencies ------------ It is common to take advantage of third-party libraries to simplify source code. The formal way of doing so is by specifying these third-party libraries as dependencies. There are two types of dependencies: :ref:`Required dependencies` and :ref:`Optional dependencies`. Required dependencies ~~~~~~~~~~~~~~~~~~~~~ Required dependencies are third-party libraries that a software requires to properly function. If these dependencies are not installed or present, the software does not work as expected. Required dependencies must be declared in :ref:`The \`\`setup.py\`\` file` or in :ref:`The \`\`pyproject.toml\`\` file`, according to the selected :ref:`Build system`: .. tab-set:: .. tab-item:: flit .. code-block:: toml [project] dependencies = [ "ansys-api-service==X.Y.Z", "matplotlib>=3.5.2", "numpy", ] .. tab-item:: poetry .. code-block:: toml [tool.poetry.dependencies] ansys-api-service = "^X.Y.Z" matplotlib = "^3.5.2" numpy = "*" .. tab-item:: setuptools .. code-block:: python from setuptools import setup setup( ..., install_requires=[ "ansys-api-service==X.Y.Z", "matplotlib >= 3.5.2", "numpy", ..., ], ) Optional dependencies ~~~~~~~~~~~~~~~~~~~~~ Optional dependencies are third-party libraries without which a software is not able to execute particular features. This makes it convenient to declare dependencies for ancillary functions such as plotting, tests, or documentation. You can programmatically integrate dependencies that are to be installed as optional requirements rather than individual packages. You may want to have optional packages for your PyAnsys library for a variety of reasons, including: - **Not all users want to use the feature.** For example, you might want to make using `Matplotlib `_ or `PyVista `_ optional if you expect your PyAnsys library is to be used primarily for headless scripting rather than visualization. - **Not all users can install the optional package.** For certain less popular or obscure environments, some binary wheels might not be available or compatible with the user's environment. For example, if a user of CentOS 6.9 needs to have the ``manylinux1`` package but CentOS 6.9 only supports ``manylinux2014`` (CentOS 7+ and later), the user's environment wouldn't be able to run the PyAnsys library. - **Reduce dependency bloat.** Removing the package as a "required" dependency reduces the number of packages to install at installation time, speeding up the installation and reducing the possibility of dependency conflicts. The trade-off here is that any user who wants to access features that require the optional package must install it separately. If you choose to implement optional packages for your PyAnsys library, some helpful best practices follow. Implement optional packages in the build system +++++++++++++++++++++++++++++++++++++++++++++++ The following code snippets show how to implement and use optional requirements for the three most popular build systems: .. tab-set:: .. tab-item:: flit .. code-block:: toml [project.optional-dependencies] all = [ "matplotlib", "pyvista", "pyside", ] plotting = [ "matplotlib", "pyvista", ] qt = [ "pyside", ] Install ``package-name`` with the optional ``qt`` packages with this command .. code-block:: text pip install package-name --extras=all .. tab-item:: poetry .. code-block:: toml ... [tool.poetry.dependencies] matplotlib = {version = "^3.5", optional = true} pyvista = {version = "^0.32", optional = true} pyside = {version = "^1.2", optional = true} ... [tool.poetry.extras] all = [ "matplotlib", "pyvista", "pyside", ] plotting = [ "matplotlib", "pyvista", ] qt = [ "pyside", ] Install ``package-name`` with the optional ``qt`` packages with this command: .. code-block:: text poetry install --extras "plotting qt" .. tab-item:: setuptools .. code-block:: python from setuptools import setup setup( ..., extras_require={ "all": ["matplotlib", "pyvista", "pyside"], "plotting": ["matplotlib", "pyvista"], "qt": ["pyside"], }, ..., ) Install ``package-name`` with the optional ``qt`` packages with this command: .. code-block:: text pip install package-name[qt] Implement optional libraries in features ++++++++++++++++++++++++++++++++++++++++ One of the best ways to implement an optional dependency is to execute a *lazy import* at runtime for the feature in question. For example, if your library has an optional dependency on Matplotlib, you can implement it like this: .. code:: python def plot(x, y): """Plot two numpy arrays. Parameters ---------- x : numpy.ndarray Numpy array sized (n, ). y : numpy.ndarray Numpy array sized (n, ). Notes ----- This function requires ``matplotlib``. """ try: import matplotlib.pyplot as plt except ModuleNotFoundError: # pragma: no cover raise ModuleNotFoundError( "To use this feature, install 'matplotlib' with:\n\n" "pip install matplotlib" ) plt.plot(x, y) Note that the ``import`` statement is within the method and not at the module level. Normally this is a bad practice because it can cause runtime errors. However, for optional features where the user isn't expected to have the library installed, this is one of the best ways of handling it. Otherwise, the PyAnsys library might fail to import because the optional package might not be installed. Also note how this code snippet adds a helpful `ModuleNotFoundError `_ rather than simply allowing the error to be raised. This lets the user know that this error is expected because the feature relies on an optional dependency. If you have many methods that rely on an optional feature, you can implement a `decorator `_ to make it easier to add these lazy imports and helpful error messages. Here is an example: .. code:: python from functools import wraps import importlib import warnings def requires_package(package_name, raise_error=False): """ Check if a package is installed by importing it. Parameters ---------- package_name : str Name of the package. raise_error : bool, optional Raise ``ModuleNotFoundError`` if the package is not installed. The default is ``False``. Raises ------ ModuleNotFoundError Raise when a package is not installed and ``raise_error=True``. """ def decorator(function): @wraps(function) def wrapper(self, *args, **kwargs): try: importlib.import_module(package_name) return function(self, *args, **kwargs) except ModuleNotFoundError: msg = ( f"To use the method '{function.__name__}', " f"the package '{package_name}' is required.\n" f"Install '{package_name}' with:\n" f"pip install {package_name.replace('.','-') if 'ansys' in package_name else package_name}" ) if raise_error: raise ModuleNotFoundError(msg) else: warnings.warn(msg) return return wrapper return decorator You use the decorator with a method like this: .. code:: python class MyClass: def __init__(self, sz): self._a = np.arange(sz) self._b = np.arange(sz) @requires_package("emoo") def plot(self): """Plot the internal arrays ``_a`` and ``_b``. Notes ----- This method requires ``matplotlib``. """ import matplotlib.pyplot as plt plt.plot(self._a, self._b) In practice, if the user does not have Matplotlib installed, this is the behavior that the user would expect: .. code-block:: pycon >>> my_inst = MyClass(10) >>> my_inst.plot() Traceback (most recent call last): File "", line 1, in ModuleNotFoundError: To use the method 'plot', the package 'matplotlib' is required. Install 'matplotlib' with: pip install matplotlib Dependabot ---------- Dependabot is a built-in tool for keeping project dependencies updated. It informs you of the latest releases of the packages being used. The ``dependabot.yml`` file ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dependabot version updates are performed by checking a ``dependabot.yml`` configuration file into your repository. In this file, one should specify the location of the project's requirement files, so that Dependabot knows where to look. On top of that, Dependabot is also capable of updating GitHub actions versions. The following code snippets show the required configuration for Dependabot according to the type of file in which the dependencies are specified: .. tab-set:: .. tab-item:: With requirements/\*.txt .. code:: yaml version: 2 updates: - package-ecosystem: "pip" # See documentation for possible values directory: "/requirements" # Location of package manifests schedule: interval: "daily" - package-ecosystem: "github-actions" directory: "/" schedule: interval: "daily" .. tab-item:: With pyproject.toml .. code:: yaml version: 2 updates: - package-ecosystem: "pip" # See documentation for possible values directory: "pyproject.toml" # Location of package manifests schedule: interval: "daily" - package-ecosystem: "github-actions" directory: "/" schedule: interval: "daily" .. tab-item:: With setup.py .. code:: yaml version: 2 updates: - package-ecosystem: "pip" # See documentation for possible values directory: "setup.py" # Location of package manifests schedule: interval: "daily" - package-ecosystem: "github-actions" directory: "/" schedule: interval: "daily" This file should be located in the ``.github`` folder of your repository for GitHub to detect it automatically. There are several main options: * **package-ecosystem**: Lets Dependabot know what your package manager is. PyAnsys projects typically use ``pip``. However, ``conda`` could also be used. * **directory**: Lets Dependabot know where your requirement files are located. PyAnsys projects typically contain all their requirements inside a ``requirements`` directory. Other directories could be used. * **schedule**: Lets Dependabot know the frequency to perform subroutines for checking for updates. Dependabot updates ~~~~~~~~~~~~~~~~~~ Dependabot determines (using semantic versioning) whether a requirement should be updated due to the existence of a newer version. When Dependabot identifies an outdated dependency, it raises a pull request to update these requirement files. Dependabot allows for two different types of updates: * **Dependabot security updates**: Automated pull requests that help update dependencies with known vulnerabilities. * **Dependabot version updates**: Automated pull requests that keep dependencies updated, even when they don’t have any vulnerabilities. To check the status of version updates, navigate to the **Insights** tab of your repository and then select **Dependency Graph** and **Dependabot**. .. caution:: Dependabot only works for *pinned-down* versions of requirements (or, at most, versions with an *upper-limits* requirement such as ``pyvista <= 0.34.0``). However, this is not a best practice for *run-time* dependencies (that is, the usage of a package should support the oldest available version if possible). Thus, it is only recommended to fully pin **documentation** and **testing** requirements (that is, using ``==``). Having the latest dependencies available in your requirements testing files lets you test the *latest* packages against your library. Dependabot version updates ~~~~~~~~~~~~~~~~~~~~~~~~~~ To enable version updates for your repository, see `Enabling Dependabot version updates `_ in the GitHub documentation. Dependabot security updates ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dependabot security updates make it easier for you to fix vulnerable dependencies in your repository. If you enable this feature, when a Dependabot alert is raised for a vulnerable dependency in the dependency graph of your repository, Dependabot automatically tries to fix it. For information on enabling security updates and notifications for your repository, see `Enabling or disabling Dependabot security updates for an individual repository `_ in the GitHub documentation.