hatch-project-name

CI/CD
Package
Meta

This provides a build hook plugin for Hatch that writes the project name defined in pyproject.toml to a file.

Table of Contents

• Configuration
  • Build hook options
  • Editable installs
• Rationale
• License

Configuration

The build hook plugin name is project-name.

Define your project name in pyproject.toml:

[project]
name = "my-project"

Then configure the build hook:

• pyproject.toml

  [tool.hatch.build.hooks.project-name]
  dependencies = ["hatch-project-name"]
  name-file = "src/my_project/_name.py"
  

• hatch.toml

  [build.hooks.project-name]
  dependencies = ["hatch-project-name"]
  name-file = "src/my_project/_name.py"
  

Building the project will generate the file

• _name.py

  project_name = __project_name__ = distribution_name = __distribution_name__ = "my-project"
  

[!NOTE] This file is generated and should not be committed to version control. Remember to add it to your .gitignore. The plugin will automatically include it in your project’s built sdists and wheels.

Now you can import the project name:

from my_project._name import project_name

print(project_name)

Build hook options

Editable installs

The name file is only updated upon install or build. Thus the name in an editable install (Hatch's dev mode) will be incorrect if the name is changed in pyproject.toml and the project is not rebuilt.

Rationale

The Hatch project name is a required field defined in the [project] table in pyproject.toml:

[project]
name = "my-project"

The [project] table specifies the project’s core metadata. The name project metadata field corresponds to the distribution package Name.

A distribution package is a piece of software that you can install. Most of the time, this is synonymous with “project”. When you type pip install pkg, or when you write dependencies = ["pkg"] in your pyproject.toml, pkg is the name of a distribution package. [...]

Most of the time, a distribution package provides one single import package (or non-package module), with a matching name. For example, pip install numpy lets you import numpy.

However, this is only a convention. PyPI and other package indices do not enforce any relationship between the name of a distribution package and the import packages it provides. [...]

Source: Distribution package vs. import package

The project/distribution name might be needed in code for various reasons. One might be that you are using the importlib.metadata standard library module to access project metadata. For instance:

from importlib import metadata

distribution_name = "my-project"
version = metadata.version(distribution_name)

Or you might simply want to log the name.

project_name = "my-project"
print(f"Project name: {project_name}")

The Python standard library does not provide a standardized function to programmatically access the current project/distribution name that works without limitations. This is because, as quoted above, no relationship is enforced between the name of a distribution package and the importable import packages it provides. You can of course just hardcode the project/distribution name as in the examples above, but this is not ideal since it is preferable to maintain pyproject.toml as the single source of truth for your project metadata.

The following method (originally posted here) is the best you can achieve with the standard library importlib.metadata module, but it has important limitations.

Say one top-level module or import package name in your project is my_tool. Then you can do:

from importlib import metadata

def get_project_name() -> str:
    pkg_name = "my_tool"
    pkg_to_dists = metadata.packages_distributions()
    return pkg_to_dists[pkg_name][0]

This uses importlib.metadata.packages_distributions() to map one of the top-level names to the project/distribution name.

This method has the following limitations:

1. It does not work for namespace packages as the top-level namespace will map to potentially multiple distributions.
2. It does not work with an editable install (unless you are using setuptools, see more details here and here). The main reason is that importlib.metadata "operates on third-party distribution packages installed into Python’s site-packages directory".

Alternatively, Hatch provides a CLI command hatch project metadata name that outputs the project name. However, this is cumbersome to use in Python code as you need to use something like subprocess.run to invoke the command in a working directory that contains the project source code. It additonally requires that Hatch is installed.

An even better alternative then is to generate a file containing the project name on-the-fly and include it in the distribution—and this is exactly what the hatch-project-name build hook does! Since the file is generated, you should exclude it from version control. This maintains pyproject.toml as the source of truth for the project name. Furthermore, Python project templates built with tools like cookiecutter and Copier will not need to parameterize the project name in Python source files.

License

hatch-project-name is distributed under the terms of the MIT license.