python pyproject.toml settings for use with hatchling to target command line app

Question

I have a python command line app I want to package for pypi. I have followed this: https://packaging.python.org/en/latest/tutorials/packaging-projects/. The key point being that the package files are located @ <package>\src\<package>. The goal is to obtain a .exe that would be installed into the pythonXX\Scripts directory with pip. This line added to pyproject.toml does just that:

[project.scripts]

<exe_basename> = '<package>.<script_module>:main'

First, the only information I can find on this behavior is here: Specifying command line scripts in pyproject.toml. And, while not stated there, I can confirm this also works for Hatchling. How it works is opaque to me. The exe file that is installed in pythonXX\Scripts IS NOT part of distribution *.tar.gz file so I assume pip generates it during the installation. Can anyone confirm this and/or point me to additional information on how this works?

Second, I'm not able to make this work for <script_module> not part of <package>. Why would I not want it part of the package? Because in order to import other modules from the package the <script_module> does this: import <package>.<module_x>

And because my development environment is pyCharm, I can't configure my sys.path during development so that it recognizes the package in the <project>\src directory (sys.path is set to <project>\src\<project>, one directory below where is would recognize the package). So, I really want to do this:

[project.scripts]

<exe_basename> = '<script_module>:main'

where Hatchling/pip knows to look for this in the <project>\src, NOT <project>\src\<project>.

Any clues and crumbs to follow appreciated.

I was hoping the [project.scripts] allowed the <script_module> to be located some place other that embedded along with the package.

Answer 1

You can leverage the Forced Inclusion feature of Hatch to move your script into the nested package directory.

So let's say your script is called cli.py and it has a function main. Let's further assume you'd like the executable to be called executive, and your project is called project_name.

You would add the following lines to your pyproject.toml:

[tool.hatch.build.target.sdist.force-include]
"src/cli.py" = "src/project_name/cli.py"

[project.scripts]
executive = "project_name.cli:main"

---

By the way, once your package is installed having a file nested within the package which does import package.module... is fine, because it's highly unlikely that you're importing your script within the package itself. There is no need to move it outside for that reason alone.

Here's a reference on Console Scripts that you might find useful.