Merge pull request #212 from HeyItsGilbert/main

Author: casperdcl

.github/workflows/test.yml

@@ -9,21 +9,24 @@ jobs:
     if: github.event_name != 'pull_request' || !contains('OWNER,MEMBER,COLLABORATOR', github.event.pull_request.author_association)
     strategy:
       matrix:
-        python: [3.9, 3.14]
-    runs-on: ubuntu-latest
+        python: ['3.x']
+        os: [ubuntu, macos, windows]
+        include: [{python: 3.9, os: ubuntu}] # min supported (see pyproject.toml)
+    runs-on: ${{ matrix.os }}-latest
     steps:
     - uses: actions/checkout@v7
       with: {fetch-depth: 0}
     - uses: actions/setup-python@v7
       with:
         python-version: ${{ matrix.python }}
-    - run: sudo apt-get update && sudo apt-get install -y zsh fish tcsh # generated-script tests
+    - if: matrix.os == 'ubuntu'
+      run: sudo apt-get update && sudo apt-get install -y zsh fish tcsh # generated-script tests
     - run: pip install -e .[dev]
-    - run: env PYTHONPATH=. pytest --cov-report=xml --cov-report=term
+    - run: env PYTHONPATH=. pytest --cov-report=xml --cov-report=term ${{ matrix.os == 'windows' && '-k "not bash" --cov-fail-under=75' || '' }}
     - uses: codecov/codecov-action@v7
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
-        flags: ${{ matrix.python }}
+        flags: ${{ matrix.python }}-${{ matrix.os }}
   diff:
     if: (github.event_name != 'pull_request' || !contains('OWNER,MEMBER,COLLABORATOR', github.event.pull_request.author_association)) && github.ref != 'refs/heads/main'
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -41,6 +41,7 @@ Most of the magic lives in [`shtab/__init__.py`](./shtab/__init__.py).
     - `complete_zsh()`
     - `complete_tcsh()`
     - `complete_fish()`
+    - `complete_powershell()`
     - ...
     - `add_argument_to()` - convenience function for library integration
     - `Optional()`, `Required()`, `Choice()` - legacy helpers for advanced completion (e.g. dirs, files, `*.txt`)

README.rst

@@ -20,7 +20,7 @@ Features
 
 - Outputs tab completion scripts for multiple shells
 
-  - ``bash``, ``zsh``, ``fish``, ``tcsh``
+  - ``bash``, ``zsh``, ``fish``, ``tcsh``, ``powershell``
 
 - Supports
 
@@ -61,8 +61,8 @@ There are two ways of using ``shtab``:
 - `Library Usage <https://tqdm.github.io/shtab/use/#library-usage>`_: as a library integrated into your CLI application
 
   - adds a couple of lines to your application
-  - argument mode: end-users execute ``your_cli_app --print-completion {bash,zsh,tcsh,fish}``
-  - subparser mode: end-users execute ``your_cli_app completion {bash,zsh,tcsh,fish}``
+  - argument mode: end-users execute ``your_cli_app --print-completion {bash,zsh,tcsh,fish,powershell}``
+  - subparser mode: end-users execute ``your_cli_app completion {bash,zsh,tcsh,fish,powershell}``
 
 Examples
 --------
@@ -88,8 +88,7 @@ Contributions
 
 Please do open `issues <https://github.com/tqdm/shtab/issues>`_ & `pull requests <https://github.com/tqdm/shtab/pulls>`_! Some ideas:
 
-- support ``powershell`` (#212)
-- support ``python -m`` prefix (#55)
+- support ``python -m`` prefix (`#55 <https://github.com/tqdm/shtab/issues/55>`_)
 
 See
 `CONTRIBUTING.md <https://github.com/tqdm/shtab/blob/main/CONTRIBUTING.md>`_

docs/index.md

@@ -17,7 +17,7 @@
 ## Features
 
 - Outputs tab completion scripts for multiple shells
-    - `bash`, `zsh`, `fish`, `tcsh`
+    - `bash`, `zsh`, `fish`, `tcsh`, `powershell`
 - Supports
     - [`argparse`](https://docs.python.org/library/argparse)
     - [`docopt`](https://pypi.org/project/docopt) (via [`argopt`](https://pypi.org/project/argopt))
@@ -42,6 +42,7 @@ shell | location
 [`zsh`](https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org) | `/usr/local/share/zsh/site-functions/_NAME`
 [`tcsh`](https://github.com/tcsh-org/tcsh/blob/master/complete.tcsh) | `/etc/profile.d/completion_NAME.csh`, source in `~/.cshrc` or `~/.tcshrc`
 [`fish`](https://fishshell.com/docs/current/completions.html#where-to-put-completions) | `~/.config/fish/completions/NAME.fish`
+[`powershell`](https://learn.microsoft.com/en-us/powershell/scripting/learn/shell/creating-profiles#adding-customizations-to-your-profile) | `~\.config\powershell\completions\NAME.ps1`, source in `$PROFILE`
 
 For more information, click on the shells above, and/or see [CLI Usage](use.md#cli-usage).
 

docs/use.md

@@ -7,8 +7,8 @@ There are two ways of using `shtab`:
     - end-users execute `shtab your_cli_app.your_parser_object`
 - [Library Usage](#library-usage): as a library integrated into your CLI application
     - adds a couple of lines to your application
-    - argument mode: end-users execute `your_cli_app --print-completion {bash,zsh,tcsh}`
-    - subparser mode: end-users execute `your_cli_app completion {bash,zsh,tcsh}`
+    - argument mode: end-users execute `your_cli_app --print-completion {bash,zsh,tcsh,fish,powershell}`
+    - subparser mode: end-users execute `your_cli_app completion {bash,zsh,tcsh,fish,powershell}`
 
 ## CLI Usage
 
@@ -52,8 +52,8 @@ Below are various examples of enabling `shtab`'s own tab completion scripts.
 
 === "zsh"
 
-    Note that `zsh` requires completion script files to be named `_{EXECUTABLE}`
-    (with an underscore prefix).
+    !!! info
+        `zsh` requires completion script files to be named `_{EXECUTABLE}` (with an underscore prefix).
 
     ```sh
     # note the underscore `_` prefix
@@ -103,6 +103,39 @@ Below are various examples of enabling `shtab`'s own tab completion scripts.
       | sudo tee /usr/share/fish/vendor_completions.d/shtab.fish
     ```
 
+=== "powershell"
+
+    !!! info
+        PowerShell 7+ (`pwsh`) is fully supported, while
+        Windows PowerShell 5 (`powershell.exe`) is only partially supported.
+
+    ```powershell
+    New-Item -Path ~\.config\powershell\completions -ItemType Directory -Force
+    shtab --shell=powershell shtab.main.get_main_parser --error-unimportable `
+      | Out-File -FilePath ~\.config\powershell\completions\shtab.ps1
+    # Add to $PROFILE:
+    . ~\.config\powershell\completions\shtab.ps1
+    ```
+
+    Eager:
+
+    Add the following to your PowerShell profile (`$PROFILE`):
+
+    ```powershell
+    shtab --shell=powershell shtab.main.get_main_parser `
+      | Out-String | Invoke-Expression
+    ```
+
+    Or save to a file and dot-source it from your profile:
+
+    ```powershell
+    New-Item -Path ~\.config\powershell\completions -ItemType Directory -Force
+    shtab --shell=powershell shtab.main.get_main_parser `
+      | Out-File -FilePath ~\.config\powershell\completions\shtab.ps1
+    # Add to $PROFILE:
+    . ~\.config\powershell\completions\shtab.ps1
+    ```
+
 ### argparse
 
 Any existing `argparse`-based scripts should be supported with minimal effort.
@@ -155,6 +188,15 @@ Assuming this code example is installed in `MY_PROG.cli`, simply run:
       | sudo tee /usr/share/fish/vendor_completions.d/MY-PROG.fish
     ```
 
+=== "powershell"
+
+    ```powershell
+    New-Item -Path ~\.config\powershell\completions -ItemType Directory -Force
+    shtab --shell=powershell -u MY_PROG.cli.get_main_parser `
+      | Out-File -FilePath ~\.config\powershell\completions\MY-PROG.ps1
+    . ~\.config\powershell\completions\MY-PROG.ps1
+    ```
+
 ### click
 
 Speedup `click`'s completions (and get support for more shell types) by changing from e.g. `_MY_PROG_COMPLETE=bash_source MY-PROG` to `shtab MY_PROG.cli.main --prog MY-PROG -s bash`

examples/customcomplete.py

@@ -9,6 +9,13 @@
 
 import shtab  # for completion magic
 
+# WARNING: shtab.cmd is (re)run by your shell on each tab press, so could be slow
+COMPLETE_TOKEN = shtab.cmd("head -c5 /dev/random | base32")
+# override powershell function to a Windows-compatible approximate equivalent
+COMPLETE_TOKEN['preamble']['powershell'] = (   # type: ignore[index]
+    f"function {COMPLETE_TOKEN['powershell']}"
+    " { Get-Random -Count 1 -InputObject (10000..99999) }")
+
 
 def process(args):
     print(f"received <token>={args.token} [<suffix>={args.suffix}]"
@@ -25,8 +32,7 @@ def process(args):
 # mypy: disable-error-code="attr-defined"
 parser = subparsers.add_parser("process", help="parse files")
 # dynamic command tab completion builtin shortcut
-# WARNING: shtab.cmd is (re)run by your shell on each tab press, so could be slow
-parser.add_argument("token").complete = shtab.cmd("head -c5 /dev/random | base32")
+parser.add_argument("token").complete = COMPLETE_TOKEN
 # file tab completion builtin shortcut
 parser.add_argument("-i", "--input-file", dest="input_name").complete = shtab.FILE
 # directory tab completion builtin shortcut

pyproject.toml

@@ -20,7 +20,7 @@ maintainers = [{name = "tqdm developers", email = "devs@tqdm.ml"}]
 description = "Automagic shell tab completion for Python CLI applications"
 readme = "README.rst"
 requires-python = ">=3.9"
-keywords = ["tab", "completion", "shell", "bash", "zsh", "tcsh", "fish", "argparse"]
+keywords = ["tab", "completion", "argparse", "shell", "bash", "zsh", "tcsh", "fish", "powershell", "pwsh"]
 license = {text = "MPL-2.0"}
 # Trove classifiers (https://pypi.org/pypi?%3Aaction=list_classifiers)
 classifiers = [