Add setuptools entry point

[Freed-Wu]

This is a dirty experimental trial. It may not satisfy code style, etc.

I want to use this branch to demo and discuss the issue about can we add a setuptool entry point to generate shell completion scripts during building python package not after installing python package.

An example project is https://github.com/Freed-Wu/requirements-language-server/tree/fbc2a773d3c4de7bf442fd5096f7916592717e27.

git clone --depth=2 https://github.com/Freed-Wu/requirements-language-server --branch=dev
git checkout fbc2a773d3c4de7bf442fd5096f7916592717e27

It has a script:

pyproject.toml:

# ...
[project.scripts]
requirements-language-server = "requirements_language_server.__main__:main"
# ...

requirements_language_server.__main__:main have used shtab: After
installing this package, users use requirements-language-server --print-completion XXsh can generate completion scripts for XXsh. Then users can move these scripts to correct path to make them work.

I hope an out-of-box experiences. That is during building package, shell
completion scripts will be generated (we assume they are generated in sdist/) and packaged to python wheel. Users install the compiled wheel will get them to be installed in correct paths.

1. Add shtab to build requires:

pyproject.toml:

[build-system]
requires = [
  # ...
  "git+https://github.com/Freed-Wu/shtab",
]

2. Add generated files to tool.setuptools.data-files to make them are packaged to python wheel.

pyproject.toml:

[tool.setuptools.data-files]
"share/bash-completion/completions" = ["sdist/requirements-language-server"]
"share/zsh/site-functions" = ["sdist/_requirements-language-server"]

That's all.

Then pip install --user dist/requirements_language_server-*-py3-none-any.whl will get:

• ~/.local/lib/python3.10/site-packages/requirements_language_server
• ~/.local/share/bash-completion/completions/requirements_language_server
• ~/.local/share/zsh/site-functions/_requirements_language_server

Or without --user:

• /usr/lib/python3.10/site-packages/requirements_language_server
• /usr/share/bash-completion/completions/requirements_language_server
• /usr/share/zsh/site-functions/_requirements_language_server

bash-completion and zsh will search completion scripts in these directories.

Pro:

• Users don't need generate shell completion scripts by themselves, And avoid the bug that they move generated shell completion scripts to a wrong path.
• For packagers of all Linux distributors, same as above.

Con:

• Increase the complexity
• generate completion scripts during building, means we must run the source code during building. It increase the probability of bug. For example, Run
  requirements_language_server.__main__:main must source requirements_language_server/__main__.py. If requirements_language_server/__main__.py or requirements_language_server/__init__.py has a import XXX but XXX is not declared in. Perhaps we should disable this feature by default, only enable it when user add enable-setuptools-entry-point = true in pyproject.toml?

[build-system]
requires = [
  # ...
  "XXX",
]

import XXX will fail.

It's only my 2c. I just throw a bad thought to attract good ideas. 😄

PS: In fact, this thought is the continuation of the thought huggingface/huggingface_hub#1207 (comment).

[casperdcl]

My biggest concern is:

[tool.setuptools.data-files]
"share/bash-completion/completions" = ["..."]

afaik this is discouraged by @pypa - related to #122 (comment)

[casperdcl]

not all programs use this. It may be e.g.:

Suggested change

	sys.argv = [prog, "--print-completion", shell]
	sys.argv = [prog, "complete", shell]

[Freed-Wu]

Yes, It's a fast dirty trial 😄 How can we get the command option about print completion or get the completion content directly from python?

[Freed-Wu]

It's not encouraged because if one package want to attach some files, install them in /usr/lib/python3.11/site-packages/package_name/a_file is better than /usr/XXX/YYY/ZZZ/a_file. However, we must put these files outside /usr/lib/python3.11. I think discourage is different from forbidding.

[Freed-Wu]

What is your opinion about this dirty trial? 😄

[casperdcl]

pull[bot] definitely did something wrong.

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 61 lines in your changes missing coverage. Please review.

Project coverage is 76.00%. Comparing base (1d7a36b) to head (61d97ef).

Files with missing lines	Patch %	Lines
shtab/setuptools.py	0.00%	61 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (1d7a36b) and HEAD (61d97ef). Click for more details.

HEAD has 26 uploads less than BASE

Flag	BASE (1d7a36b)	HEAD (61d97ef)
	28	2

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #156       +/-   ##
===========================================
- Coverage   88.88%   76.00%   -12.88%     
===========================================
  Files           3        4        +1     
  Lines         360      421       +61     
===========================================
  Hits          320      320               
- Misses         40      101       +61     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.