Skip to content

Add setuptools entry point #156

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Add setuptools entry point #156

wants to merge 2 commits into from

Conversation

Freed-Wu
Copy link
Contributor

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",
]
  1. 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).

Copy link
Collaborator

@casperdcl casperdcl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My biggest concern is:

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

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

os.makedirs("sdist", exist_ok=True)
argv = sys.argv
for shell, filename in shells.items():
sys.argv = [prog, "--print-completion", shell]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@casperdcl casperdcl added enhancement New feature or request help-wanted We need help external-request You asked, we did labels Dec 1, 2023
@Freed-Wu
Copy link
Contributor Author

Freed-Wu commented Dec 2, 2023

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
Copy link
Contributor Author

What is your opinion about this dirty trial? 😄

@casperdcl
Copy link
Collaborator

casperdcl commented Jul 15, 2025

pull[bot] definitely did something wrong.

Copy link

codecov bot commented Jul 15, 2025

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.

@Freed-Wu Freed-Wu closed this by deleting the head repository Jul 15, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request external-request You asked, we did help-wanted We need help
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants