| Name | hatch-project-name JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | Hatch build hook plugin that writes the project name to a file |
| upload_time | 2025-08-27 12:06:09 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
git
hatch
mercurial
plugin
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# hatch-project-name
| | |
| --- | --- |
| CI/CD | [](https://github.com/valentinoli/hatch-project-name/actions/workflows/test.yml) [](https://github.com/valentinoli/hatch-project-name/actions/workflows/build.yml) |
| Package | [](https://pypi.org/project/hatch-project-name/) [](https://pypi.org/project/hatch-project-name/) |
| Meta | [](https://github.com/pypa/hatch) [](https://docs.astral.sh/uv/) [](https://docs.astral.sh/ruff/) [](https://mypy.readthedocs.io/en/stable/) [](https://spdx.org/licenses/) |
-----
This provides a build hook plugin for [Hatch](https://github.com/pypa/hatch) that writes the project name defined in `pyproject.toml` to a file.
**Table of Contents**
- [Configuration](#configuration)
- [Build hook options](#build-hook-options)
- [Editable installs](#editable-installs)
- [Rationale](#rationale)
- [License](#license)
## Configuration
The [build hook plugin](https://hatch.pypa.io/latest/plugins/build-hook/reference/) name is `project-name`.
Define your project name in `pyproject.toml`:
```toml
[project]
name = "my-project"
```
Then configure the build hook:
- ***pyproject.toml***
```toml
[tool.hatch.build.hooks.project-name]
dependencies = ["hatch-project-name"]
name-file = "src/my_project/_name.py"
```
- ***hatch.toml***
```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***
```python
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:
```py
from my_project._name import project_name
print(project_name)
```
### Build hook options
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name-file` | `str` | ***REQUIRED*** | The relative path to the Python file that gets updated with the project name. |
### Editable installs
The name file is only updated upon install or build. Thus the name in an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs) (Hatch's [dev mode](https://hatch.pypa.io/latest/config/build/#dev-mode)) will be incorrect if the name is changed in `pyproject.toml` and the project is not rebuilt.
## Rationale
The [Hatch project name](https://hatch.pypa.io/latest/config/metadata/#name) is a required field defined in the `[project]` table in `pyproject.toml`:
```toml
[project]
name = "my-project"
```
The [`[project]`](https://packaging.python.org/en/latest/specifications/pyproject-toml/#declaring-project-metadata-the-project-table) table specifies the project’s [core metadata](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata). The [`name`](https://packaging.python.org/en/latest/specifications/pyproject-toml/#name) project metadata field corresponds to the distribution package [`Name`](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-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](https://packaging.python.org/en/latest/discussions/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:
```py
from importlib import metadata
distribution_name = "my-project"
version = metadata.version(distribution_name)
```
Or you might simply want to log the name.
```py
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](https://github.com/pypa/hatch/issues/2019)) is the best you can achieve with the standard library [`importlib.metadata`](https://docs.python.org/3/library/importlib.metadata.html) 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:
```py
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()`](https://docs.python.org/3/library/importlib.metadata.html#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](https://github.com/pypa/packaging-problems/issues/609) and [here](https://github.com/python/importlib_metadata/issues/402)). 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](https://spdx.org/licenses/MIT.html) license.
Raw data
{
"_id": null,
"home_page": null,
"name": "hatch-project-name",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "git, hatch, mercurial, plugin",
"author": null,
"author_email": "Valentin Oliver Melberg Loftsson <valentin.loftsson@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/62/81/830e0b5735ddfd4a1df616c8f1ac1136d3d318ecf50ee9345cc4d5240742/hatch_project_name-1.0.2.tar.gz",
"platform": null,
"description": "# hatch-project-name\n\n| | |\n| --- | --- |\n| CI/CD | [](https://github.com/valentinoli/hatch-project-name/actions/workflows/test.yml) [](https://github.com/valentinoli/hatch-project-name/actions/workflows/build.yml) |\n| Package | [](https://pypi.org/project/hatch-project-name/) [](https://pypi.org/project/hatch-project-name/) |\n| Meta | [](https://github.com/pypa/hatch) [](https://docs.astral.sh/uv/) [](https://docs.astral.sh/ruff/) [](https://mypy.readthedocs.io/en/stable/) [](https://spdx.org/licenses/) |\n\n-----\n\nThis provides a build hook plugin for [Hatch](https://github.com/pypa/hatch) that writes the project name defined in `pyproject.toml` to a file.\n\n**Table of Contents**\n\n- [Configuration](#configuration)\n - [Build hook options](#build-hook-options)\n - [Editable installs](#editable-installs)\n- [Rationale](#rationale)\n- [License](#license)\n\n## Configuration\n\nThe [build hook plugin](https://hatch.pypa.io/latest/plugins/build-hook/reference/) name is `project-name`.\n\nDefine your project name in `pyproject.toml`:\n\n```toml\n[project]\nname = \"my-project\"\n```\n\nThen configure the build hook:\n\n- ***pyproject.toml***\n\n ```toml\n [tool.hatch.build.hooks.project-name]\n dependencies = [\"hatch-project-name\"]\n name-file = \"src/my_project/_name.py\"\n ```\n\n- ***hatch.toml***\n\n ```toml\n [build.hooks.project-name]\n dependencies = [\"hatch-project-name\"]\n name-file = \"src/my_project/_name.py\"\n ```\n\nBuilding the project will generate the file\n\n- ***_name.py***\n\n ```python\n project_name = __project_name__ = distribution_name = __distribution_name__ = \"my-project\"\n ```\n\n> [!NOTE]\n> 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\u2019s built sdists and wheels.\n\nNow you can import the project name:\n\n```py\nfrom my_project._name import project_name\n\nprint(project_name)\n```\n\n### Build hook options\n\n| Option | Type | Default | Description |\n| --- | --- | --- | --- |\n| `name-file` | `str` | ***REQUIRED*** | The relative path to the Python file that gets updated with the project name. |\n\n### Editable installs\n\nThe name file is only updated upon install or build. Thus the name in an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs) (Hatch's [dev mode](https://hatch.pypa.io/latest/config/build/#dev-mode)) will be incorrect if the name is changed in `pyproject.toml` and the project is not rebuilt.\n\n## Rationale\n\nThe [Hatch project name](https://hatch.pypa.io/latest/config/metadata/#name) is a required field defined in the `[project]` table in `pyproject.toml`:\n\n```toml\n[project]\nname = \"my-project\"\n```\n\nThe [`[project]`](https://packaging.python.org/en/latest/specifications/pyproject-toml/#declaring-project-metadata-the-project-table) table specifies the project\u2019s [core metadata](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata). The [`name`](https://packaging.python.org/en/latest/specifications/pyproject-toml/#name) project metadata field corresponds to the distribution package [`Name`](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-name).\n\n> A distribution package is a piece of software that you can install. Most of the time, this is synonymous with \u201cproject\u201d. When you type `pip install pkg`, or when you write `dependencies = [\"pkg\"]` in your `pyproject.toml`, pkg is the name of a distribution package. [...]\n\n> 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`.\n\n> 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. [...]\n\nSource: [Distribution package vs. import package](https://packaging.python.org/en/latest/discussions/distribution-package-vs-import-package/)\n\nThe 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:\n\n```py\nfrom importlib import metadata\n\ndistribution_name = \"my-project\"\nversion = metadata.version(distribution_name)\n```\n\nOr you might simply want to log the name.\n\n```py\nproject_name = \"my-project\"\nprint(f\"Project name: {project_name}\")\n```\n\nThe 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.\n\nThe following method (originally [posted here](https://github.com/pypa/hatch/issues/2019)) is the best you can achieve with the standard library [`importlib.metadata`](https://docs.python.org/3/library/importlib.metadata.html) module, but it has important limitations.\n\nSay one top-level module or import package name in your project is `my_tool`. Then you can do:\n\n```py\nfrom importlib import metadata\n\ndef get_project_name() -> str:\n pkg_name = \"my_tool\"\n pkg_to_dists = metadata.packages_distributions()\n return pkg_to_dists[pkg_name][0]\n```\n\nThis uses [`importlib.metadata.packages_distributions()`](https://docs.python.org/3/library/importlib.metadata.html#importlib.metadata.packages_distributions) to map one of the top-level names to the project/distribution name.\n\nThis method has the following limitations:\n\n1. It does not work for namespace packages as the top-level namespace will map to potentially multiple distributions.\n2. It does not work with an editable install (unless you are using `setuptools`, see more details [here](https://github.com/pypa/packaging-problems/issues/609) and [here](https://github.com/python/importlib_metadata/issues/402)). The main reason is that `importlib.metadata` \"operates on third-party distribution packages installed into Python\u2019s site-packages directory\".\n\nAlternatively, 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.\n\nAn even better alternative then is to generate a file containing the project name on-the-fly and include it in the distribution\u2014and 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.\n\n## License\n\n`hatch-project-name` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Hatch build hook plugin that writes the project name to a file",
"version": "1.0.2",
"project_urls": {
"History": "https://github.com/valentinoli/hatch-project-name/blob/main/HISTORY.md",
"Issues": "https://github.com/valentinoli/hatch-project-name/issues",
"Source": "https://github.com/valentinoli/hatch-project-name"
},
"split_keywords": [
"git",
" hatch",
" mercurial",
" plugin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb2d5f1b1f41d59d2666986c92b14f694f90adf4b7c1be37140281dc00933094",
"md5": "0ba7e88ffede9f0dda8c2c4291238155",
"sha256": "af32ac9a9c9cd608bbea2e5c899aa9b471a62c3120bb4b95b101eaf4ea270b3e"
},
"downloads": -1,
"filename": "hatch_project_name-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0ba7e88ffede9f0dda8c2c4291238155",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 6653,
"upload_time": "2025-08-27T12:06:08",
"upload_time_iso_8601": "2025-08-27T12:06:08.136807Z",
"url": "https://files.pythonhosted.org/packages/eb/2d/5f1b1f41d59d2666986c92b14f694f90adf4b7c1be37140281dc00933094/hatch_project_name-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6281830e0b5735ddfd4a1df616c8f1ac1136d3d318ecf50ee9345cc4d5240742",
"md5": "be50e146fa6bd3ed96c673a791d87fea",
"sha256": "9c2aa9ce5c7865414f74f42d753f6d458d0e3ae40855d00719fcb56f4ec9c695"
},
"downloads": -1,
"filename": "hatch_project_name-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "be50e146fa6bd3ed96c673a791d87fea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 5757,
"upload_time": "2025-08-27T12:06:09",
"upload_time_iso_8601": "2025-08-27T12:06:09.700207Z",
"url": "https://files.pythonhosted.org/packages/62/81/830e0b5735ddfd4a1df616c8f1ac1136d3d318ecf50ee9345cc4d5240742/hatch_project_name-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 12:06:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "valentinoli",
"github_project": "hatch-project-name",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hatch-project-name"
}
