././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1698902019.651161 argcomplete-3.1.4/0000755000076600000240000000000014520630004014713 5ustar00andrey.kislyukstaff././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1698902019.6228518 argcomplete-3.1.4/.github/0000755000076600000240000000000014520630004016253 5ustar00andrey.kislyukstaff././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1698096677.0 argcomplete-3.1.4/.github/FUNDING.yml0000644000076600000240000000002214515563045020100 0ustar00andrey.kislyukstaffgithub: [kislyuk] ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1698902019.6235032 argcomplete-3.1.4/.github/workflows/0000755000076600000240000000000014520630004020310 5ustar00andrey.kislyukstaff././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1698851483.0 argcomplete-3.1.4/.github/workflows/ci.yml0000644000076600000240000000167514520465233021451 0ustar00andrey.kislyukstaffname: Python package on: [push, pull_request] jobs: build: runs-on: ${{matrix.os}} strategy: fail-fast: false matrix: os: [ubuntu-20.04, ubuntu-22.04, macos-11, macos-12] python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"] steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v4 with: python-version: ${{matrix.python-version}} allow-prereleases: true - name: Install CI dependencies run: | [[ $(uname) == Linux ]] && sudo apt-get install --yes rpm tcsh fish zsh [[ $(uname) == Darwin ]] && brew install bash tcsh fish python -m pip install --quiet --upgrade codecov - run: make install - run: make lint - run: make test - uses: codecov/codecov-action@v3 black: runs-on: ubuntu-22.04 steps: - uses: psf/black@stable isort: runs-on: ubuntu-22.04 steps: - uses: isort/isort-action@v1.1.0 ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1698096677.0 argcomplete-3.1.4/.gitignore0000644000076600000240000000073214515563045016723 0ustar00andrey.kislyukstaff# Reminder: # - A leading slash means the pattern is anchored at the root. # - No leading slash means the pattern matches at any depth. # Python files *.pyc __pycache__/ *.egg-info/ /build/ /dist/ /.eggs/ .coverage .venv # IDE project files /.pydevproject # vim python-mode plugin /.ropeproject # IntelliJ IDEA / PyCharm project files /.idea /*.iml # JS/node/npm/web dev files node_modules npm-debug.log # OS X metadata files .DS_Store # test test/test_package/build ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1698096678.0 argcomplete-3.1.4/Authors.rst0000644000076600000240000000004314515563046017106 0ustar00andrey.kislyukstaffAndrey Kislyuk ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1698902005.0 argcomplete-3.1.4/Changes.rst0000644000076600000240000003260614520627765017050 0ustar00andrey.kislyukstaffChanges for v3.1.4 (2023-11-01) =============================== - Call \_default as a fallback in zsh global completion Changes for v3.1.3 (2023-11-01) =============================== - Use homebrew prefix by default - zsh: Allow to use external script (#453) - Add support for Python 3.12 and drop EOL 3.6 and 3.7 (#449) Changes for v3.1.3 (2023-11-01) =============================== - Use homebrew prefix by default - zsh: Allow to use external script (#453) - Add support for Python 3.12 and drop EOL 3.6 and 3.7 (#449) Changes for v3.1.2 (2023-09-16) =============================== - Ensure Python 3.12+ compatibility in check_console_script (#448) Changes for v3.1.1 (2023-06-11) =============================== - Search through asdf shims - Use \` as escape character in PowerShell (#434) Changes for v3.1.0 (2023-06-10) =============================== - setup.py -> pyproject.toml migration start (#427) - Improve user install logic in activate-global-python-argcomplete (#437) - Ensure Python 3.7 compatibility in check_console_script (#436) - ZSH implementation fixes (#431, #433) - Documentation improvements Changes for v3.0.8 (2023-04-23) =============================== - Test suite shell wrapper: Accept OSError on exit Changes for v3.0.7 (2023-04-23) =============================== - Test suite: Use general regex to cut zsh reset ANSI sequences (#425) Changes for v3.0.6 (2023-04-22) =============================== - Allow importlib-metadata 6.x; skip test failures on Python 3.7 (#420, #424) - Note completers can return iterables of strings, not just lists (#422) - Documentation and test improvements Changes for v3.0.5 (2023-03-25) =============================== - Call \_default as fallback in zsh global completion hook - Begin support for mapping-emitting completers Changes for v3.0.4 (2023-03-21) =============================== - activate-global-python-argcomplete: do not overwrite existing dotfile in user directory - Add NOTICE file - Establish long term name for split_line as argcomplete.lexers.split_line Changes for v3.0.3 (2023-03-20) =============================== - Re-add split_line to API (#419) Changes for v3.0.2 (2023-03-19) =============================== Fix zsh default completion issues Changes for v3.0.1 (2023-03-19) =============================== - Fix zsh autoload issues Changes for v3.0.0 (2023-03-19) =============================== - Fully support zsh. Argcomplete now supports completion descriptions and global completion in zsh. - Clean up top level namespace. - Documentation and test improvements. Changes for v2.1.2 (2023-03-17) =============================== - Test infrastructure improvements - Indicate that there is no support commitment for fish and tcsh shells Changes for v2.1.1 (2023-03-06) =============================== - Documentation and test improvements Changes for v2.1.0 (2023-03-06) =============================== - Remove scripts for contrib-supported shells from global namespace Changes for v2.0.6 (2023-03-06) =============================== - setup.py: exclude test.\* subpackages from find_packages (#406) - Support PowerShell (#405) - CI updates Changes for v2.0.5 (2023-03-04) =============================== - Revert “Support powershell (#392)” Changes for v2.0.4 (2023-03-04) =============================== - Fix interrupted release (v2.0.1) Changes for v2.0.3 (2023-03-04) =============================== - Fix interrupted release (v2.0.1) Changes for v2.0.2 (2023-03-04) =============================== - Fix interrupted release (v2.0.1) Changes for v2.0.1 (2023-03-04) =============================== - Support powershell (#392) - Update importlib-metadata dependency to include versions 5.x (#389) - Test and documentation improvements Changes for v2.0.0 (2022-01-03) =============================== - Truncate input after cursor. Fixes #351 (#352) - Support of path completion in fish #327 (#359) - Drop support for Python 2.7 and 3.5 (#361) - Add support for Python 3.10 (#356) - Test, documentation, and release infrastructure improvements Changes for v1.12.3 (2021-04-19) ================================ - Update importlib-metadata version pin (#345) - Display script debug output in tcsh (#342) - Fish support improvements (#338, #339) - Print ``warn()`` message from beginning of line (#335) - Test infrastructure improvements Changes for v1.12.2 (2020-11-23) ================================ - Update importlib-metadata dependency pin (#332) - Add change log project URL (#312) - Replace Travis CI with GitHub Actions (#323) Changes for v1.12.1 (2020-09-26) ================================ - Update importlib-metadata dependency version range - Bash nounset mode fixes (#313) Changes for v1.11.1 (2020-01-14) ================================ - Add -o bashdefault to register-python-argcomplete’s output command (#284) Changes for v1.11.0 (2019-12-23) ================================ - Use shell builtins where possible (#280) - Switch from pkg_resources to importlib (#283) - Remove .sh extension by bash-completion convention (#281) - Catch exceptions in \_check_module (#269) - Documentation and test improvements Changes for v1.10.3 (2019-11-26) ================================ - Do not suggest options after – (end-of-options delimiter) Changes for v1.10.2 (2019-11-17) ================================ - Include all test directory contents in source distribution Changes for v1.10.1 (2019-11-16) ================================ - Trigger completers on –optional=PARTIAL_VALUE - Complete console scripts installed from wheels (#241) Changes for v1.10.0 (2019-05-12) ================================ - Fish support #68 (#260), thanks to @volkov Changes for v1.9.5 (2019-04-02) =============================== - check_module: Don’t crash, exit with error instead (#261) - Register completion for multiple commands (#246) Changes for v1.9.4 (2018-02-13) =============================== - Use the correct interpreter when checking wrappers (#226) - Provide shellcode as a module function (#237) Changes for v1.9.3 (2017-11-16) =============================== - Fix handling of COMP\_POINT (#236) - Fix crash when writing unicode to debug\_stream in Python 2 (#230) Changes for v1.9.2 (2017-08-23) =============================== - Fix release Changes for v1.9.1 (2017-08-23) =============================== - Fix release Changes for v1.9.0 (2017-08-23) =============================== - Add SuppressCompleter to skip completion for specific arguments while allowing help text (#224) - Redirect all output to debug stream in debug mode (#206) - Complete python -m module (#204) Changes for v1.8.2 (2017-01-26) =============================== - Fix bug introduced in v0.7.1 where completers would not receive the parser keyword argument. - Documentation improvements. Changes for v1.8.1 (2017-01-21) =============================== - Fix completion after tokens with wordbreak chars (#197) Changes for v1.8.0 (2017-01-19) =============================== This release contains work by @evanunderscore with numerous improvements to the handling of special characters in completions. - Simplify nospace handling in global completion (#195) - Specially handle all characters in COMP\_WORDBREAKS (#187) - Use setuptools tests-require directive, fixes #186 - Complete files using the specified interpreter (#192) - Fix completion for scripts run via python (#191) - Clarify argument to register-python-argcomplete (#190) - Fix handling of commas and other special chars (#172); handle more special characters (#189) - Fix handling of special characters in tcsh (#188) - Update my\_shlex to Python 3.6 version (#184) - Fix additional trailing space in exact matches (#183) - Adjust tests to handle development environments (#180) - Fix tcsh tests on OSX (#177); Update bash on OSX (#176); Check output of test setup command (#179) - Optionally disable duplicated flags (#143) - Add default\_completer option to CompletionFinder.\ **call** (#167) - Let bash add or suppress trailing space (#159) Changes for v1.7.0 (2016-11-30) =============================== - Restore parser to its original state to allow reuse after completion (#150). - Expose COMP\_TYPE environment variable (#157). Thanks to Matt Clay (@mattclay). - Test infrastructure and documentation improvements. Changes for v1.6.0 (2016-10-20) =============================== - Add support for tcsh (#155) - Fix handling of unquoted completions containing $ (#154) - Don't insert unnecessary leading quote char in completions (#152) - Fix parser reuse with positional arguments (#149) - Tests: Add simple pexpect tests for bash (#153); Add test case to verify #20 is fixed (#148) - Thanks to @davvid and @evanunderscore for their work on this release. Changes for v1.5.1 (2016-10-11) =============================== - Packaging fix Changes for v1.5.0 (2016-10-11) =============================== - Do not suggest options from mutually exclusive groups (#145). Version 1.4.1 (2016-06-14) ========================== - activate-global-python-argcomplete runs on Homebrew out of the box Version 1.4.0 (2016-06-10) ========================== - Correctly handle suggestions for positionals with variable-length nargs. Thanks to @evanunderscore (#132, #133). Version 1.3.0 (2016-06-01) ========================== - Correctly handle suggestions with custom nargs for optionals. Thanks to @evanunderscore (#131). Version 1.2.0 (2016-05-25) ========================== - Fix propagation of partially parsed subparser namespace into parent parser namespace upon subparser failure due to partial args. This allows completers to access partial parse results for subparser optionals in parsed_args (#114). - The default completer can now be specified when manually instantiating CompletionFinder. Thanks to @avylove (#130). Version 1.1.1 (2016-03-22) ========================== - Use FilesCompleter as default completer fallback (#120). Version 1.1.0 (2016-02-21) ========================== - Recognize subclasses of argparse._SubParsersAction. Thanks to Stephen Koo (#118). - Support parsed_args in custom completers with missing args. Thanks to Dan Kilman (#124). - Non-ASCII support in FilesCompleter. - Automatically enable FilesCompleter for argparse.FileType arguments. Version 1.0.0 (2015-08-22) ========================== - Don't print args with suppressed help by default; add ``argcomplete.autocomplete(print_suppressed=True)`` to control this behavior (#113). Version 0.9.0 (2015-07-03) ========================== - Fix always_complete_options=False support (#115). Version 0.8.9 (2015-06-01) ========================== - Correct doc filename in setup.cfg (fixes bdist_rpm failure, Issue 111). - Make context managers exception-safe. Thanks to Mikołaj Siedlarek (pull request #110). Version 0.8.8 (2015-05-01) ========================== - Build and upload universal wheel packages in release. - Fix issue with non-string choices for arguments. Thanks to @neizod (pull request #107). - Improve non-ascii argparse argument support on Python 2.7. Version 0.8.7 (2015-04-11) ========================== - register-python-argcomplete: add option to avoid default readline completion. Thanks to @drmalex07 (pull request #99). Version 0.8.6 (2015-04-11) ========================== - Expand tilde in script name, allowing argcomplete to work when invoking scripts from one's home directory. Thanks to @VorpalBlade (Issue 104). Version 0.8.5 (2015-04-07) ========================== - Fix issues related to using argcomplete in a REPL environment. - New helper method for custom completion display. - Expand test suite; formatting cleanup. Version 0.8.4 (2014-12-11) ========================== - Fix issue related to using argcomplete in a REPL environment. Thanks to @wapiflapi (pull request #91). Version 0.8.3 (2014-11-09) ========================== - Fix multiple issues related to using argcomplete in a REPL environment. Thanks to @wapiflapi (pull request #90). Version 0.8.2 (2014-11-03) ========================== - Don't strip colon prefix in completion results if COMP_WORDBREAKS does not contain a colon. Thanks to @berezv (pull request #88). Version 0.8.1 (2014-07-02) ========================== - Use complete --nospace to avoid issues with directory completion. Version 0.8.0 (2014-04-07) ========================== - Refactor main body of code into a class to enable subclassing and overriding of functionality (Issue #78). Version 0.7.1 (2014-03-29) ========================== - New keyword option "argcomplete.autocomplete(validator=...)" to supply a custom validator or bypass default validation. Thanks to @thijsdezoete (Issue #77). - Document debug options. Version 0.7.0 (2014-01-19) ========================== - New keyword option "argcomplete.autocomplete(exclude=[...])" to suppress options (Issue #74). - More speedups to code path for global completion hook negative result. Version 0.6.9 (2014-01-19) ========================== - Fix handling of development mode script wrappers. Thanks to @jmlopez-rod and @dcosson (Issue #69). - Speed up code path for global completion hook negative result by loading pkg_resources on demand. Version 0.6.8 (2014-01-18) ========================== - Begin tracking changes in changelog. - Add completion support for PBR installed scripts (PR #71). - Detect easy-install shims with shebang lines that contain Py instead of py (Issue #69). ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1698096677.0 argcomplete-3.1.4/LICENSE.rst0000644000076600000240000002367614515563045016563 0ustar00andrey.kislyukstaff Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1698096676.0 argcomplete-3.1.4/MANIFEST.in0000644000076600000240000000011714515563044016465 0ustar00andrey.kislyukstaffinclude argcomplete/bash_completion.d/* include *.rst recursive-include test * ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1698096676.0 argcomplete-3.1.4/Makefile0000644000076600000240000000137614515563044016377 0ustar00andrey.kislyukstaffSHELL=/bin/bash test_deps: python -m pip install .[test] lint: for dir in $$(dirname */__init__.py); do ruff $$dir; done for script in scripts/*[^cmd]; do if grep -q python $$script; then ruff $$script; fi; done mypy --install-types --non-interactive --check-untyped-defs argcomplete test: coverage run --source=argcomplete --omit=argcomplete/packages/_shlex.py ./test/test.py -v init_docs: cd docs; sphinx-quickstart docs: python -m pip install furo sphinx-copybutton sphinxext-opengraph sphinx-build docs docs/html install: clean python -m pip install build python -m build python -m pip install --upgrade $$(echo dist/*.whl)[test] clean: -rm -rf build dist -rm -rf *.egg-info .PHONY: test_deps lint test docs install clean include common.mk ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1698096676.0 argcomplete-3.1.4/NOTICE0000644000076600000240000000060314515563044015633 0ustar00andrey.kislyukstaffargcomplete is a free open source library that integrates Python applications with Bash and Zsh shell completion. The argcomplete project is staffed by volunteers. If you are using this library in a for-profit project, please contribute to argcomplete development and maintenance using the "Sponsor" button on the argcomplete GitHub project page, https://github.com/kislyuk/argcomplete. ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1698902019.6507103 argcomplete-3.1.4/PKG-INFO0000644000076600000240000004030414520630004016011 0ustar00andrey.kislyukstaffMetadata-Version: 2.1 Name: argcomplete Version: 3.1.4 Summary: Bash tab completion for argparse Home-page: https://github.com/kislyuk/argcomplete Author: Andrey Kislyuk Author-email: kislyuk@gmail.com License: Apache Software License Project-URL: Documentation, https://kislyuk.github.io/argcomplete Project-URL: Source Code, https://github.com/kislyuk/argcomplete Project-URL: Issue Tracker, https://github.com/kislyuk/argcomplete/issues Project-URL: Change Log, https://github.com/kislyuk/argcomplete/blob/master/Changes.rst Platform: MacOS X Platform: Posix Classifier: Environment :: Console Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: Apache Software License Classifier: Operating System :: MacOS :: MacOS X Classifier: Operating System :: POSIX Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: 3.8 Classifier: Programming Language :: Python :: 3.9 Classifier: Programming Language :: Python :: 3.10 Classifier: Programming Language :: Python :: 3.11 Classifier: Programming Language :: Python :: 3.12 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Development Status :: 5 - Production/Stable Classifier: Topic :: Software Development Classifier: Topic :: Software Development :: Libraries :: Python Modules Classifier: Topic :: System :: Shells Classifier: Topic :: Terminals Requires-Python: >=3.8 Description-Content-Type: text/x-rst License-File: LICENSE.rst License-File: NOTICE Provides-Extra: test Requires-Dist: coverage; extra == "test" Requires-Dist: pexpect; extra == "test" Requires-Dist: wheel; extra == "test" Requires-Dist: ruff; extra == "test" Requires-Dist: mypy; extra == "test" argcomplete - Bash/zsh tab completion for argparse ================================================== *Tab complete all the things!* Argcomplete provides easy, extensible command line tab completion of arguments for your Python application. It makes two assumptions: * You're using bash or zsh as your shell * You're using `argparse `_ to manage your command line arguments/options Argcomplete is particularly useful if your program has lots of options or subparsers, and if your program can dynamically suggest completions for your argument/option values (for example, if the user is browsing resources over the network). Installation ------------ :: pip install argcomplete activate-global-python-argcomplete See `Activating global completion`_ below for details about the second step. Refresh your shell environment (start a new shell). Synopsis -------- Add the ``PYTHON_ARGCOMPLETE_OK`` marker and a call to ``argcomplete.autocomplete()`` to your Python application as follows: .. code-block:: python #!/usr/bin/env python # PYTHON_ARGCOMPLETE_OK import argcomplete, argparse parser = argparse.ArgumentParser() ... argcomplete.autocomplete(parser) args = parser.parse_args() ... Register your Python application with your shell's completion framework by running ``register-python-argcomplete``:: eval "$(register-python-argcomplete my-python-app)" Quotes are significant; the registration will fail without them. See `Global completion`_ below for a way to enable argcomplete generally without registering each application individually. argcomplete.autocomplete(*parser*) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This method is the entry point to the module. It must be called **after** ArgumentParser construction is complete, but **before** the ``ArgumentParser.parse_args()`` method is called. The method looks for an environment variable that the completion hook shellcode sets, and if it's there, collects completions, prints them to the output stream (fd 8 by default), and exits. Otherwise, it returns to the caller immediately. .. admonition:: Side effects Argcomplete gets completions by running your program. It intercepts the execution flow at the moment ``argcomplete.autocomplete()`` is called. After sending completions, it exits using ``exit_method`` (``os._exit`` by default). This means if your program has any side effects that happen before ``argcomplete`` is called, those side effects will happen every time the user presses ```` (although anything your program prints to stdout or stderr will be suppressed). For this reason it's best to construct the argument parser and call ``argcomplete.autocomplete()`` as early as possible in your execution flow. .. admonition:: Performance If the program takes a long time to get to the point where ``argcomplete.autocomplete()`` is called, the tab completion process will feel sluggish, and the user may lose confidence in it. So it's also important to minimize the startup time of the program up to that point (for example, by deferring initialization or importing of large modules until after parsing options). Specifying completers --------------------- You can specify custom completion functions for your options and arguments. Two styles are supported: callable and readline-style. Callable completers are simpler. They are called with the following keyword arguments: * ``prefix``: The prefix text of the last word before the cursor on the command line. For dynamic completers, this can be used to reduce the work required to generate possible completions. * ``action``: The ``argparse.Action`` instance that this completer was called for. * ``parser``: The ``argparse.ArgumentParser`` instance that the action was taken by. * ``parsed_args``: The result of argument parsing so far (the ``argparse.Namespace`` args object normally returned by ``ArgumentParser.parse_args()``). Completers can return their completions as an iterable of strings or a mapping (dict) of strings to their descriptions (zsh will display the descriptions as context help alongside completions). An example completer for names of environment variables might look like this: .. code-block:: python def EnvironCompleter(**kwargs): return os.environ To specify a completer for an argument or option, set the ``completer`` attribute of its associated action. An easy way to do this at definition time is: .. code-block:: python from argcomplete.completers import EnvironCompleter parser = argparse.ArgumentParser() parser.add_argument("--env-var1").completer = EnvironCompleter parser.add_argument("--env-var2").completer = EnvironCompleter argcomplete.autocomplete(parser) If you specify the ``choices`` keyword for an argparse option or argument (and don't specify a completer), it will be used for completions. A completer that is initialized with a set of all possible choices of values for its action might look like this: .. code-block:: python class ChoicesCompleter(object): def __init__(self, choices): self.choices = choices def __call__(self, **kwargs): return self.choices The following two ways to specify a static set of choices are equivalent for completion purposes: .. code-block:: python from argcomplete.completers import ChoicesCompleter parser.add_argument("--protocol", choices=('http', 'https', 'ssh', 'rsync', 'wss')) parser.add_argument("--proto").completer=ChoicesCompleter(('http', 'https', 'ssh', 'rsync', 'wss')) Note that if you use the ``choices=`` option, argparse will show all these choices in the ``--help`` output by default. To prevent this, set ``metavar`` (like ``parser.add_argument("--protocol", metavar="PROTOCOL", choices=('http', 'https', 'ssh', 'rsync', 'wss'))``). The following `script `_ uses ``parsed_args`` and `Requests `_ to query GitHub for publicly known members of an organization and complete their names, then prints the member description: .. code-block:: python #!/usr/bin/env python # PYTHON_ARGCOMPLETE_OK import argcomplete, argparse, requests, pprint def github_org_members(prefix, parsed_args, **kwargs): resource = "https://api.github.com/orgs/{org}/members".format(org=parsed_args.organization) return (member['login'] for member in requests.get(resource).json() if member['login'].startswith(prefix)) parser = argparse.ArgumentParser() parser.add_argument("--organization", help="GitHub organization") parser.add_argument("--member", help="GitHub member").completer = github_org_members argcomplete.autocomplete(parser) args = parser.parse_args() pprint.pprint(requests.get("https://api.github.com/users/{m}".format(m=args.member)).json()) `Try it `_ like this:: ./describe_github_user.py --organization heroku --member If you have a useful completer to add to the `completer library `_, send a pull request! Readline-style completers ~~~~~~~~~~~~~~~~~~~~~~~~~ The readline_ module defines a completer protocol in rlcompleter_. Readline-style completers are also supported by argcomplete, so you can use the same completer object both in an interactive readline-powered shell and on the command line. For example, you can use the readline-style completer provided by IPython_ to get introspective completions like you would get in the IPython shell: .. _readline: http://docs.python.org/3/library/readline.html .. _rlcompleter: http://docs.python.org/3/library/rlcompleter.html#completer-objects .. _IPython: http://ipython.org/ .. code-block:: python import IPython parser.add_argument("--python-name").completer = IPython.core.completer.Completer() ``argcomplete.CompletionFinder.rl_complete`` can also be used to plug in an argparse parser as a readline completer. Printing warnings in completers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Normal stdout/stderr output is suspended when argcomplete runs. Sometimes, though, when the user presses ````, it's appropriate to print information about why completions generation failed. To do this, use ``warn``: .. code-block:: python from argcomplete import warn def AwesomeWebServiceCompleter(prefix, **kwargs): if login_failed: warn("Please log in to Awesome Web Service to use autocompletion") return completions Using a custom completion validator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, argcomplete validates your completions by checking if they start with the prefix given to the completer. You can override this validation check by supplying the ``validator`` keyword to ``argcomplete.autocomplete()``: .. code-block:: python def my_validator(completion_candidate, current_input): """Complete non-prefix substring matches.""" return current_input in completion_candidate argcomplete.autocomplete(parser, validator=my_validator) Global completion ----------------- In global completion mode, you don't have to register each argcomplete-capable executable separately. Instead, the shell will look for the string **PYTHON_ARGCOMPLETE_OK** in the first 1024 bytes of any executable that it's running completion for, and if it's found, follow the rest of the argcomplete protocol as described above. Additionally, completion is activated for scripts run as ``python