kieran-ryan / python-package-template Goto Github PK

Maintaining and keeping templates consistent across repositories can be challenging; though is very important for maintaining a clean git history, reducing merge conflicts, automating repeated tedious work, and maintaining alignment to ensure elements are in a format all developers expect.

pyprojectsort ensures consistent formatting of pyproject.toml files - a common file across most Python projects - automating check against that style and realising some of the aforementioned benefits.

The project is currently packaged and published in each of the deployment jobs: to PyPI and TestPyPI. This slows down the pipeline as the package build process runs twice. As the project is only built on release - when the package would be deployed - build failures are not detected in the pipeline until a release is created.

To resolve these issues, the build process can be extracted from the deployment tasks into its own individual task, of which other tasks can use its distribution.

typing.TYPE_CHECKING blocks allow us to include package imports for type hinting, but have them only be imported by type checkers, and not during the execution of the source code. This is more efficient as it prevents unnecessary package imports at run time.

As such, they will not be imported when the source code is executed through the package test suite and should not be included in test coverage as they will reduce it hike not represented executable code.

This can be achieved by configuring coverage in a pyproject.toml as follows:

[tool.coverage.report]
exclude_lines =
    if typing.TYPE_CHECKING:

Expected Result

Type-checking blocks are excluded from test coverage.

Actual Result

Type-checking blocks are included in test coverage.

Reproduction Steps

make coverage

Standard GitHub issue templates are very useful to provide a template for raising new issues. One of their drawbacks, however, is the user will typically have to clear placeholders or help text and it may be argued that as they ultimately allow free text entry in any structure, it can lead to less-specific and less-structured issues.

GitHub issue forms resolve these issues. Acting as one would expect from a web form, it can: clear placeholders on text entry, provide better help text (which we can exclude from the output), provide dropdowns of pre-defined values; it provides both a better user experience and a more targeted output which will assist project developers.

As part of this work, label assignment should also be automated based on the selected template i.e. selecting a bug report issue will automatically assign the "bug" label and "enhancement" will be assigned for a feature request issue.

Once repositories have been created from a template, it is typically difficult to keep those repositories synchronised with new changes to the template. Synchronisation can be important to keep alignment and ensure deployment of the latest standards. To manually align can take significant effort and be infeasible.

The 'actions-template-sync' Action provides the automated functionality to support this, with configurability to define elements for synchronisation. This will ensure template changes are reflected in templated repositories with an automated, low-effort solution.

From the GitHub documentation:

Development containers, or dev containers, are Docker containers that are specifically configured to provide a fully featured development environment. Whenever you work in a codespace, you are using a dev container on a virtual machine.

Currently the template, and packages created from it; are using the default devcontainer when a GitHub codespace is opened; and thus install the project dependencies and VSCode setup when they start using that space. To define the container in which to develop a project, and also to be able to do that locally, we can defined a devcontainer configuration. This can then be utilised to configured codespace initialisation and for local development - saving valuable time that could be spent developing and also reducing environment-related issues from developing in non-configured, non-isolated local environments.

To ensure packages created from the template have aligned formatting with every commit, and to automate its application, pyprojectsort's pre-commit can be integrated. This will prevent commits to version control with an unformatted pyproject.toml, and also automate the process of applying it when a developer has forgotten.

Adding a test coverage badge to the project's README would provide greater transparency of the project's test coverage, without the need to delve into the coverage artifacts or checkout the project locally. This will provide a better indicator of the project's health, which will be useful for first-time viewers or to developers who want to keep track of how their coverage is trending.

The test coverage of this project is already being calculated in it's GitHub workflow using the pytest and coverage packages respectively. A coverage badge can be implemented through GitHub using the coverage-badge Action.

The docstring unit tests of the pipeline are executed twice within the pipeline. They are first executed as a single task to execute all unit tests (docstring and module level) and thereafter in isolation in their own task. While there may be a degree of benefit from a reporting perspective that a pipeline task failure will specifically indicate a docstring unit test failure rather than simply an overall unit test failure (docstring or module level), it is more efficient to run them as a single test suite in terms of run time and to keep the command to execute the unit tests as simple as possible (just pytest) which is desirable to ensure they are executed in their entirety regularly.

Expected Result

Docstring unit tests are executed once.

Actual Result

Docstring unit tests are executed alongside the task to execute unit tests, and again separately in their own job.

Reproduction Steps

Trigger template CICD pipeline.

"cookiecutter" is a Python-based command-line utility that facilitates project creation using customisable project templates. These templates allow users to input predefined configuration options for their projects. By defining configurable elements within the template, template owners can guide users in modifying the initial project according to their needs.

However, there is a tradeoff when using "cookiecutter" with GitHub templates. The top level of the repository contains the "cookiecutter" scaffold, which includes the template directory and supporting infrastructure, rather than solely the template directory. Additionally, the files within the template directory include template-engine logic that applies user-entered configurations when generating the project. As a result, the template is not in a usable state if someone tries to create a new project using the GitHub UI. Substantial modifications would be required to make it functional.

Consideration should be made to migrate to "cookiecutter". Although, if the template serves a broader purpose and there is limited value in providing configuration options, it may be more desirable to continue support for project creation through the GitHub UI.

Sphinx documentation is inaccessible through GitHub Pages.

Expected Result

The project Sphinx documentation is successfully built and deployed to the project's documentation URL: https://kieran-ryan.github.io/python-package-template/.

Actual Result

Despite the project Sphinx documentation being built successfully GitHub Pages deployment Action executing successfully, the GitHub Pages URL renders a 404 error code. This is most likely attributed to the action looking in the docs directory for an index.html, however the project output directory for this project is docs/builds/html. The HTML documentation for this repository is also not committed with the repository and is instead generated from documentation build files through the pipeline; which may be a requirement for the Action.

A CONTRIBUTING.md file is an important element of every repository. It provides visitors with an overview of how they can set up, work with and contribute to the repository. Writing this documentation, also provides repository owners with a useful opportunity to assess usability issues and to examine the project from a fresh perspective, with a mindset of 'What issues might someone seeing this for the first time encounter?' or 'Is there any way I could make this implementation more explicit and reduce its "unknown unknowns"?'.

As this is a template that will form the basis of other repositories, it is important that it provides a well-documented contributing guide that captures questions and issues that a new visitor may encounter. This will allow them to act with autonomy and to not be dependant on direct support and answers from the original authors.