CLI: click -> argparse (#830)

- Remove `click` and `sphinx-click`
- Add `sphinx-argparse`
- Use [`argparse`](https://docs.python.org/3/library/argparse.html)
- Remove completion, for now

See also: vcs-python/vcspull#400

Author: tony

CHANGES

@@ -17,7 +17,26 @@ $ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force
 
 ## tmuxp 1.17.x (unreleased)
 
-- _Insert changes/features/fixes for next release here_
+- Notes on upcoming releases will be added here
+
+<!-- Maintainers, insert changes / features for the next release here -->
+
+### Breaking changes
+
+- **Completions have changed** (#830)
+
+  Completions now use a different tool: [shtab]. See the [completions page] for more information.
+
+  If you were using earlier versions of tmuxp (earlier than 1.17.0), you may need to uninstall the old completions, first.
+
+  [completions page]: https://tmuxp.git-pull.com/cli/completion.html
+  [shtab]: https://docs.iterative.ai/shtab/
+
+- Deprecate `click` in favor of {mod}`argparse` (#830)
+
+### Packages
+
+- Remove `click` dependency
 
 ## tmuxp 1.16.2 (2022-10-08)
 

MIGRATION

@@ -21,7 +21,20 @@ well.
 
 ## Next release
 
-_Add migration notes here_
+_Notes on the upcoming release will be added here_
+
+<!-- Maintainers, insert changes / features for the next release here -->
+
+## 1.17.x (unreleased)
+
+**Completions have changed** (#830)
+
+Completions now use a different tool: [shtab]. See the [completions page] for more information.
+
+If you were using earlier versions of tmuxp (earlier than 1.17.0), you may need to uninstall the old completions, first.
+
+[completions page]: https://tmuxp.git-pull.com/cli/completion.html
+[shtab]: https://docs.iterative.ai/shtab/
 
 <!---
 # vim: set filetype=markdown:

Makefile

@@ -58,3 +58,9 @@ watch_mypy:
 
 format_markdown:
 	npx prettier --parser=markdown -w *.md docs/*.md docs/**/*.md CHANGES
+
+monkeytype_create:
+	poetry run monkeytype run `poetry run which py.test`
+
+monkeytype_apply:
+	poetry run monkeytype list-modules | xargs -n1 -I{} sh -c 'poetry run monkeytype apply {}'

conftest.py

@@ -25,7 +25,7 @@
 
 @pytest.mark.skipif(USING_ZSH, reason="Using ZSH")
 @pytest.fixture(autouse=USING_ZSH, scope="session")
-def zshrc(user_path: pathlib.Path):
+def zshrc(user_path: pathlib.Path) -> pathlib.Path:
     """This quiets ZSH default message.
 
     Needs a startup file .zshenv, .zprofile, .zshrc, .zlogin.
@@ -41,7 +41,7 @@ def home_path_default(monkeypatch: pytest.MonkeyPatch, user_path: pathlib.Path)
 
 
 @pytest.fixture(scope="function")
-def monkeypatch_plugin_test_packages(monkeypatch):
+def monkeypatch_plugin_test_packages(monkeypatch: pytest.MonkeyPatch) -> None:
     paths = [
         "tests/fixtures/pluginsystem/plugins/tmuxp_test_plugin_bwb/",
         "tests/fixtures/pluginsystem/plugins/tmuxp_test_plugin_bs/",
@@ -55,7 +55,7 @@ def monkeypatch_plugin_test_packages(monkeypatch):
 
 
 @pytest.fixture(scope="function")
-def socket_name(request) -> str:
+def socket_name(request: pytest.FixtureRequest) -> str:
     return "tmuxp_test%s" % next(namer)
 
 

docs/cli/completion.md

@@ -1,11 +1,58 @@
 (completion)=
 
-# Completion
+(completions)=
+
+(cli-completions)=
+
+# Completions
+
+## tmuxp 1.17+ (experimental)
+
+```{note}
+See the [shtab library's documentation on shell completion](https://docs.iterative.ai/shtab/use/#cli-usage) for the most up to date way of connecting completion for tmuxp.
+```
+
+Provisional support for completions in tmuxp 1.17+ are powered by [shtab](https://docs.iterative.ai/shtab/). This must be **installed separately**, as it's **not currently bundled with tmuxp**.
+
+```console
+$ pip install shtab --user
+```
+
+:::{tab} bash
+
+```bash
+shtab --shell=bash -u tmuxp.cli.create_parser \
+  | sudo tee "$BASH_COMPLETION_COMPAT_DIR"/TMUXP
+```
+
+:::
+
+:::{tab} zsh
+
+```zsh
+shtab --shell=zsh -u tmuxp.cli.create_parser \
+  | sudo tee /usr/local/share/zsh/site-functions/_TMUXP
+```
+
+:::
+
+:::{tab} tcsh
+
+```zsh
+shtab --shell=tcsh -u tmuxp.cli.create_parser \
+  | sudo tee /etc/profile.d/TMUXP.completion.csh
+```
+
+:::
+
+## tmuxp 1.1 to 1.16
 
 ```{note}
 See the [click library's documentation on shell completion](https://click.palletsprojects.com/en/8.0.x/shell-completion/) for the most up to date way of connecting completion for tmuxp.
 ```
 
+tmuxp 1.1 to 1.16 use [click](https://click.palletsprojects.com)'s completion:
+
 :::{tab} Bash
 
 _~/.bashrc_:

docs/cli/convert.md

@@ -4,6 +4,16 @@
 
 Convert between YAML and JSON
 
+```{eval-rst}
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: convert
+```
+
+## Usage
+
 ````{tab} YAML -> JSON
 
 ```console
@@ -22,12 +32,3 @@ $ tmuxp convert /path/to/file.json
 
 tmuxp automatically will prompt to convert `.yaml` to `.json` and
 `.json` to `.yaml`.
-
-## Reference
-
-```{eval-rst}
-.. click:: tmuxp.cli.convert:command_convert
-    :prog: tmuxp convert
-    :commands: convert
-    :nested: full
-```

docs/cli/debug-info.md

@@ -7,6 +7,16 @@
 Use to collect all relevant information for submitting an issue to
 the project.
 
+```{eval-rst}
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: debug-info
+```
+
+## Usage
+
 ```console
 
 $ tmuxp debug-info
@@ -17,12 +27,3 @@ environment:
 ...
 
 ```
-
-## Reference
-
-```{eval-rst}
-.. click:: tmuxp.cli.debug_info:command_debug_info
-    :prog: tmuxp debug-info
-    :commands: debug-info
-    :nested: full
-```

docs/cli/edit.md

@@ -1,10 +1,13 @@
 (edit-config)=
 
+(cli-edit)=
+
 # tmuxp edit
 
 ```{eval-rst}
-.. click:: tmuxp.cli.edit:command_edit
-    :prog: tmuxp edit
-    :commands: edit
-    :nested: full
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: edit
 ```

docs/cli/freeze.md

@@ -1,7 +1,19 @@
 (cli-freeze)=
 
+(cli-freeze-reference)=
+
 # tmuxp freeze
 
+```{eval-rst}
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: freeze
+```
+
+## Usage
+
 Freeze sessions
 
 ```console
@@ -23,12 +35,3 @@ Tmuxp will offer to save your session state to `.json` or `.yaml`.
 If no session is specified, it will default to the attached session.
 
 If the `--force` argument is passed, it will overwrite any existing config file with the same name.
-
-(cli-freeze-reference)=
-
-```{eval-rst}
-.. click:: tmuxp.cli.freeze:command_freeze
-    :prog: tmuxp freeze
-    :commands: freeze
-    :nested: full
-```

docs/cli/import.md

@@ -7,9 +7,11 @@
 ## From teamocil
 
 ```{eval-rst}
-.. click:: tmuxp.cli.import_config:command_import_teamocil
-    :prog: tmuxp import teamocil
-    :nested: full
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: import teamocil
 ```
 
 ````{tab} YAML
@@ -33,9 +35,11 @@ $ tmuxp import teamocil /path/to/file.json
 ## From tmuxinator
 
 ```{eval-rst}
-.. click:: tmuxp.cli.import_config:command_import_tmuxinator
-    :prog: tmuxp import tmuxinator
-    :nested: short
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: import tmuxinator
 ```
 
 ````{tab} YAML

docs/cli/index.md

@@ -21,20 +21,35 @@ edit
 import
 convert
 freeze
-
 ```
 
 ```{toctree}
 :caption: Diagnostic
 :maxdepth: 1
 
 debug-info
-
 ```
 
 ```{toctree}
-:caption: More
+:caption: Completion
 :maxdepth: 1
 
 completion
 ```
+
+(cli-main)=
+
+(tmuxp-main)=
+
+## Command: `tmuxp`
+
+```{eval-rst}
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :nosubcommands:
+
+    subparser_name : @replace
+        See :ref:`cli-ls`
+```

docs/cli/load.md

@@ -2,8 +2,20 @@
 
 (tmuxp-load)=
 
+(tmuxp-load-reference)=
+
 # tmuxp load
 
+```{eval-rst}
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: load
+```
+
+## Usage
+
 You can load your tmuxp file and attach the vim session via a few
 shorthands:
 
@@ -136,14 +148,3 @@ $ tmuxp load [filename] --log-file [log_filename]
 ```console
 $ tmuxp --log-level [LEVEL] load [filename] --log-file [log_filename]
 ```
-
-## Reference
-
-(tmuxp-load-reference)=
-
-```{eval-rst}
-.. click:: tmuxp.cli.load:command_load
-    :prog: tmuxp load
-    :commands: load
-    :nested: full
-```

docs/cli/ls.md

@@ -1,10 +1,15 @@
+(cli-ls)=
+
 (ls-config)=
 
 # tmuxp ls
 
+List sesssions.
+
 ```{eval-rst}
-.. click:: tmuxp.cli.ls:command_ls
-    :prog: tmuxp ls
-    :commands: ls
-    :nested: full
+.. argparse::
+    :module: tmuxp.cli
+    :func: create_parser
+    :prog: tmuxp
+    :path: ls
 ```