Autocompletion for python scripts in zsh

dan1994, updated 🕥 2023-02-10 23:38:56

pyzshcomplete

.. image:: https://github.com/dan1994/pyzshcomplete/workflows/Tests/badge.svg :target: https://github.com/dan1994/pyzshcomplete/workflows/Tests/badge.svg .. image:: https://github.com/dan1994/pyzshcomplete/workflows/Code%20Scanning/badge.svg :target: https://github.com/dan1994/pyzshcomplete/workflows/Code%20Scanning/badge.svg

Tab completion for arbitraty python scripts in zsh.

.. image:: https://user-images.githubusercontent.com/6225230/77791128-273dc480-7077-11ea-81b4-ea34fd9251a2.PNG :alt: pyzshcomplete_example

Introduction

This project was inspired by argcomplete <https://github.com/kislyuk/argcomplete>_, which supplies argument completion for bash.

While having a workaround for zsh (which just enables compatibility for bash completion scripts), argcomplete can't use the full power of the zsh completion system (e.g. show flag help messages).

pyzshcomplete was written to utilize as many of the features offered by zsh as possible.

Prerequisites

In order for completion to work in zsh, the autocompletion module must be enabled. If you are using Oh My Zsh <https://ohmyz.sh/>, this is probably already the case. Otherwise, please refer to the zsh manual <http://zsh.sourceforge.net/Doc/Release/Completion-System.html> for more details, or Just Google It™ since it will probably be easier.

Installation

.. code-block:: zsh

pip install pyzshcomplete
~/.local/bin/activate_pyzshcomplete

Restart zsh after the installation is complete.

NOTE 1: The path to activate_pyzshcomplete will differ depending on where pip installs packages, and it may not be in your PATH, so you will have to find it.

Note 2: Removing the package will leave residual files in your system. This is currently unavoidable, since pip is not aware of these files. For those who want to clean up their system, take a look at the source of activate_pyzshcomplete

Usage

To emphasize the similarity to argcomplete, here is the example usage shown in the argcomplete readme:

.. code-block:: python

#!/usr/bin/env python
# PYTHON_ARGCOMPLETE_OK
import argcomplete, argparse
parser = argparse.ArgumentParser()
...
argcomplete.autocomplete(parser)
args = parser.parse_args()
...

And here it is adapted to pyzshcomplete:

.. code-block:: python

#!/usr/bin/env python
# PYZSHCOMPLETE_OK
import pyzshcomplete, argparse
parser = argparse.ArgumentParser()
...
pyzshcomplete.autocomplete(parser)
args = parser.parse_args()
...

Note that the magic string PYZSHCOMPLETE_OK is required to appear at the top of the script. This is similar to the PYTHON_ARGCOMPLETE_OK magic of argcomplete.

The `autocomplete(parser)` method

This method is the interface to the autocompletion mechanism. It must be called after the parser construction is complete, but before the arguments are parsed.

It receives your parser as an argument, converts it to a zsh completion script format passes it on and exits the python program. The output is then used by the zsh completion system to generate completions.

The consequences are that your program is actually being run as part of argument completion and anything you do prior to calling autocomplete will happen every time the user attempts autocompletion. Additionally, if it takes a long time for the program to reach autocomplete, this time will be reflected as a lag that the user will experience.

Can I use both `argcomplete` and `pyzshcomplete`?

TL;DR: Yes!

example:

.. code:: python

#!/usr/bin/env python3
# PYTHON_ARGCOMPLETE_OK
# PYZSHCOMPLETE_OK

from argparse import ArgumentParser
import pyzshcomplete, argcomplete

parser = ArgumentParser()
parser.add_argument('arg')

# These lines can be in any order
argcomplete.autocomplete(parser)
pyzshcomplete.autocomplete(parser)

args = parser.parse_args()

Both argcomplete and pyzshcomplete use an environment variable set by the completion script that is unique to that shell. If that variable is not set, the autocomplete function simply returns without doing anything.

argcomplete uses _ARGCOMPLETE and pyzshcomplete uses PYZSHCOMPLETE. this means that if you're using bash, the _ARGCOMPLETE environment variable will be set, and only argcomplete.autocomplete will do completion magic, and vice versa if you're using zsh.

Smart Completion

zsh offers easy ways to complete things such as process ids, user accounts, network interfaces, bookmarks and more.

As of this moment, there is no mechanism that enables associating an argument with these options. Stay tuned, as it is a prioritized feature.

Supported Parsers

pyzshcomplete was written to be easy to extend for new parsers. It currently supports only argparse, but you are welcome to request or contribute support for other parsers.

Non-Supported Features

Some features of certain parsers can't be (easily enough) supported by zsh or pyzshcomplete and are listed here for public knowledge.

General

Completion for python modules (python -m <module>)

Argparse

Subparsers - Subparsers will be supported in the near future.
Custom actions - There is no way to know in advance what effect will actions have on the way the argument should be supplied (e.g. can a flag be specified multiple times?).
Non-standard flag prefixes - Only the - and + prefixes are supported, as that is what the _arguments completion utility supports.
Usage of the from_file_prefix_chars in ArgumentParser

Python Support

Official support is for Python 3 only.

Feature Requests and Bug Reports

Feature requests and bug reports are tracked on Github <https://github.com/dan1994/pyzshcomplete/issues>_.

Resources

Getting into zsh internals isn't easy. If you are interested to learn more of the inner workings, take a look at the following resources:

From Bash to Z Shell - This book is intended to teach zsh by example, and is much more easy to read than any manual or user guide I've encountered (You can find the full pdf in a simple search, but I didn't tell you that).
The Zsh Manual <http://zsh.sourceforge.net/Doc/zsh_a4.pdf>_ - After you've acquainted yourself with the basics, and want the full spec of anything particular, this is the document to go to.
Zsh Reference Card <http://www.bash2zsh.com/zsh_refcard/refcard.pdf>_ - After you know what you're doing, you can use this reference card for quick reminders.

License

Licensed under the terms of the MIT License.

Issues

Bump ipython from 7.20.0 to 8.10.0

opened on 2023-02-10 23:38:55 by dependabot[bot]

Bumps ipython from 7.20.0 to 8.10.0.

Commits

15ea1ed release 8.10.0
560ad10 DOC: Update what's new for 8.10 (#13939)
7557ade DOC: Update what's new for 8.10
385d693 Merge pull request from GHSA-29gw-9793-fvw7
e548ee2 Swallow potential exceptions from showtraceback() (#13934)
0694b08 MAINT: mock slowest test. (#13885)
8655912 MAINT: mock slowest test.
a011765 Isolate the attack tests with setUp and tearDown methods
c7a9470 Add some regression tests for this change
fd34cf5 Swallow potential exceptions from showtraceback()
Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) - `@dependabot use these labels` will set the current labels as the default for future PRs for this repo and language - `@dependabot use these reviewers` will set the current reviewers as the default for future PRs for this repo and language - `@dependabot use these assignees` will set the current assignees as the default for future PRs for this repo and language - `@dependabot use this milestone` will set the current milestone as the default for future PRs for this repo and language You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/dan1994/pyzshcomplete/network/alerts).

Bump certifi from 2020.12.5 to 2022.12.7

opened on 2022-12-08 07:45:28 by dependabot[bot]

Bumps certifi from 2020.12.5 to 2022.12.7.

Commits

9e9e840 2022.12.07
b81bdb2 2022.09.24
939a28f 2022.09.14
aca828a 2022.06.15.2
de0eae1 Only use importlib.resources's new files() / Traversable API on Python ≥3.11 ...
b8eb5e9 2022.06.15.1
47fb7ab Fix deprecation warning on Python 3.11 (#199)
b0b48e0 fixes #198 -- update link in license
9d514b4 2022.06.15
4151e88 Add py.typed to MANIFEST.in to package in sdist (#196)
Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot commands and options

Better escaping

opened on 2022-11-07 11:26:18 by nokutu

"[" and "]" characters are not being escaped in help

use non-root copy if possible

opened on 2022-06-01 15:14:51 by EdwarDu

For my setup I use custom build zsh and python3, so default install is okay for non-root cp, but I don't have root permission on the machine, so probably is better to try with cp without sudo if we can write to the target_dir already.

59-Dont-Install-in-`/usr/share/`

opened on 2021-09-17 02:45:47 by dan1994 None

Don't Install in `/usr/share/..`

opened on 2021-07-08 19:31:26 by psacawa

I've wanted zsh completions for pypi ecosystem for a long time, so I want to thank you for getting the ball rolling on this. My strong feeling, however, is that you shouldn't force the installation anywhere superuser privileges are required. Namely, find_completion_script_dir should prefer a user directory in fpath.

Completions for Python itself: _python are typically vendor-distributed, and therefore in /usr/share/zsh/functions/Completion/Unix. At least it's this way in Ubuntu Linux. For now I just trick it by writing a dummy file _python elsewhere.

dan1994

GitHub Repository