Python composable command line interface toolkit

Overview

$ click_

Click is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It's the "Command Line Interface Creation Kit". It's highly configurable but comes with sensible defaults out of the box.

It aims to make the process of writing command line tools quick and fun while also preventing any frustration caused by the inability to implement an intended CLI API.

Click in three points:

  • Arbitrary nesting of commands
  • Automatic help page generation
  • Supports lazy loading of subcommands at runtime

Installing

Install and update using pip:

$ pip install -U click

A Simple Example

import click

@click.command()
@click.option("--count", default=1, help="Number of greetings.")
@click.option("--name", prompt="Your name", help="The person to greet.")
def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for _ in range(count):
        click.echo(f"Hello, {name}!")

if __name__ == '__main__':
    hello()
$ python hello.py --count=3
Your name: Click
Hello, Click!
Hello, Click!
Hello, Click!

Donate

The Pallets organization develops and supports Click and other popular packages. In order to grow the community of contributors and users, and allow the maintainers to devote more time to the projects, please donate today.

Links

Comments
  • Handling of argv on windows platform

    Handling of argv on windows platform

    Hi we have encountered the following problem. We were trying to profile click-enabled application on windows platform in PyCharm. Profiling the is done using a wrapper that deletes itself from the sys.argv array like this:

    del sys.argv[0] exec(our_program)

    This works on unix platform but not on windows because in def get_os_args() function the parameters are not read from sys.argv as is the standard but rather from _get_windows_argv() and thus the deletion of the first item from argv is not being applied. Would it be possible to fix it?

    windows 
    opened by mjos 38
  • Ability to create mutually exclusive option groups.

    Ability to create mutually exclusive option groups.

    Perhaps I'm missing something, but I can't find a way to create mutually exclusive option groups in Click. For example, I have a command that can take input from either a socket or a file, and I'd like the following syntax:

    cmd [-file <filename> | -stream <address>] ...
    

    At most one (or, in other examples, exactly one) of the options may be specified. Specifying more than one is a parse error caught by the library.

    Is it possible to implement this in click at present? If not, would it be feasible to add it? I've not quite got my head around the general architecture yet. Would this feature be a reasonable fit, or does it go against the overall design in some way I've missed?

    opened by robhague 37
  • Handle SIGPIPE in click.echo().

    Handle SIGPIPE in click.echo().

    When the output of a click program is sent to another program via a pipe, and the pipe is closed prematurely, click.echo() was printing an exception backtrace instead of silently exiting like most command line utilities.

    Fixes: https://github.com/pallets/click/issues/625

    opened by ob 35
  • Longest option argument not used as internal/variable name

    Longest option argument not used as internal/variable name

    It seems that with 7.0 the longest option argument isn't being used as the internal and variable name.

    https://github.com/pallets/click/blob/2c622eed402c64e1645db3904c2410f6c05fbf19/docs/parameters.rst#L93-L95

    the internal name is generated automatically by taking the longest argument

    import click
    import click.testing
    
    
    print(click.__version__)
    
    @click.command()
    @click.option(
        '--temp',
        '--temporary',
        'temporary',
    )
    def good(temporary):
        pass
    
    
    @click.command()
    @click.option(
        '--temp',
        '--temporary',
    )
    def bad(temporary):
        pass
    
    
    def click_runner(command):
        print(command.name)
        runner = click.testing.CliRunner()
        result = runner.invoke(
            command,
            [],
            catch_exceptions=False,
        )
        print(result.output)
    
    click_runner(command=good)
    click_runner(command=bad)
    
    

    https://repl.it/@altendky/click-67-unexpected-keyword-argument-1

    6.7
    good
    
    bad
    
    

    https://repl.it/@altendky/click-70-unexpected-keyword-argument-1

    7.0
    good
    
    bad
    Traceback (most recent call last):
      File "python", line 37, in <module>
      File "python", line 32, in click_runner
    TypeError: bad() got an unexpected keyword argument 'temp'
    

    https://repl.it/@altendky/click-2e856a5-unexpected-keyword-argument

    7.0
    good
    
    bad
    Traceback (most recent call last):
      File "python", line 37, in <module>
      File "python", line 32, in click_runner
    TypeError: bad() got an unexpected keyword argument 'temp'
    
    docs 
    opened by altendky 31
  • Windows

    Windows "Usage" incorrect display and difficulty to get a command name correct displayed

    When you create a command with a setuptools console_scripts entry_points (for instance named mycli) the Usage displayed on POSIX (Linux, Mac,...) when running mycli --help will be: Usage: mycli

    In contrast on Windows, I get the following: Usage: mycli-script.py

    This is annoying because the correct invocation on windows is to use mycli, not mycli-script.py. The script is the same on all OSes, even though behind the scenes setuptools creates:

    • on posix, a bin/mycli python script with a correct shebang
    • on windows, a Scripts/mycli-script.py and Scripts/mycli.exe. This is called by invoking mycli like on POSIX

    The obvious way to force this would be to use the name arg in click.command. ("This defaults to the function name."). But it does not default to the function name and always show the mycli-script.py instead of mycli.

    It looks like this comes from Context.info_name which is computed somehow, but I could not find a way to get this info_name forced to something fixed.

    bug 
    opened by pombreda 25
  • Support for shared arguments?

    Support for shared arguments?

    What are your thoughts on shared argument support for click? Sometimes it is useful to have simple inheritance hierarchies in options for complex applications. This might be frowned upon since click's raison d'etre is dynamic subcommands, however, I wanted to explore possible solutions.

    A very simple and trivial example is the verbose example. Assume you have more than one subcommand in a CLI app. An ideal user experience on the CLI would be:

    python script.py subcmd -vvv
    

    However, this wouldn't be the case with click, since subcmd doesn't define a verbose option. You'd have to invoke it as follows:

    python script.py -vvv subcmd
    

    This example is very simple, but when there are many subcommands, sometimes a root support option would go a long way to make something simple and easy to use. Let me know if you'd like further clarification.

    opened by mahmoudimus 25
  • _NonClosingTextIOWrapper conflicts with Theano

    _NonClosingTextIOWrapper conflicts with Theano

    After updating Theano from 0.7.0 to 0.8.2 I'm getting the following error:

    Exception TypeError: TypeError("'NoneType' object is not callable",) in <bound method _NonClosingTextIOWrapper.del of <_io.TextIOWrapper encoding='UTF-8'>> ignored

    Tested with Click 5.1 and 6.6 on Python 2.7.11.

    opened by zstomp 24
  • Support click.option with default values / optional arguments

    Support click.option with default values / optional arguments

    Since the default value always applies, there should be a way to differentiate between the following options usage:

    file.py file.py --foo file.py --foo 2

    where '2' is an argument to --foo. This should produce 3 different values for the destination of 'foo'. This is implemented in argparse with nargs='?' but has no functional equivalent in click (that I can identify). I've created a pull request that implements a potential solution. I'm not asking for a specific way of implementing the solution, and what I provided is mostly for a functional example. It does need test cases. #548

    opened by mbrancato 24
  • Encoding issue

    Encoding issue

    I was trying to use supervisor to start an application that uses click and I got this

     raise RuntimeError('Click will abort further execution '
    RuntimeError: Click will abort further execution because Python 3 was configured to use ASCII as encoding for the environment. Either switch to Python 2 or consult http://click.pocoo.org/python3/ for mitigation steps.
    Traceback (most recent call last):
      File "/mnt/store/www/apps/inet/pyenv/bin/inetserver", line 11, in <module>
        sys.exit(main())
      File "/mnt/store/www/apps/inet/pyenv/lib/python3.4/site-packages/click/core.py", line 700, in __call__
        return self.main(*args, **kwargs)
      File "/mnt/store/www/apps/inet/pyenv/lib/python3.4/site-packages/click/core.py", line 655, in main
        raise RuntimeError('Click will abort further execution '
    RuntimeError: Click will abort further execution because Python 3 was configured to use ASCII as encoding for the environment. Either switch to Python 2 or consult http://click.pocoo.org/python3/ for mitigation steps.
    

    I tried setting the locale using

    Supervisor
    environment = LC_ALL="en_US.utf-8", LANG="en_US.utf-8" 
    
    Bash
    $ export LC_ALL="en_US.utf-8"
    $ export LANG="en_US.utf-8"
    

    All to nothing. Note that I am using a virtualenv and python3.4

    opened by noxecane 24
  • fix(types): decorator typing fails

    fix(types): decorator typing fails

    • fixes #2227

    I've tried the fix suggested in the issue above by @Dreamsorcerer, and it seems to fix the typing issue locally.

    Checklist:

    • [ ] Add tests that demonstrate the correct behavior of the change. Tests should fail without the change.
    • [ ] Add or update relevant docs, in the docs folder and in code.
    • [ ] Add an entry in CHANGES.rst summarizing the change and linking to the issue.
    • [ ] Add .. versionchanged:: entries in any relevant code docs.
    • [x] Run pre-commit hooks and fix any issues.
    • [x] Run pytest and tox, no tests failed.
    opened by henryiii 23
  • Click should provide means to customize write

    Click should provide means to customize write

    Sometimes the output machinery embedded in click is not desirable. At least the function that performs write should be customizable to give a user a chance to handle and process all errors that may happen.

    opened by Kentzo 21
Releases(8.1.3)
  • 8.1.3(Apr 28, 2022)

    This is a fix release for the 8.1.0 feature release.

    • Changes: https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-3
    • Milestone: https://github.com/pallets/click/milestone/18?closed=1
    Source code(tar.gz)
    Source code(zip)
  • 8.1.2(Mar 31, 2022)

    This is a fix release for the 8.1.0 feature release.

    • Changes: https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-2
    • Milestone: https://github.com/pallets/click/milestone/17?closed=1
    Source code(tar.gz)
    Source code(zip)
  • 8.1.1(Mar 30, 2022)

    This is a fix release for the 8.1.0 feature release.

    • Changes: https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-1
    • Milestone: https://github.com/pallets/click/milestone/14?closed=1
    Source code(tar.gz)
    Source code(zip)
  • 8.1.0(Mar 28, 2022)

    This is a feature release, which includes new features and removes previously deprecated features. The 8.1.x branch is now the supported bugfix branch, the 8.0.x branch will become a tag marking the end of support for that branch. We encourage everyone to upgrade, and to use a tool such as pip-tools to pin all dependencies and control upgrades.

    • Changes: https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-0
    • Milestone: https://github.com/pallets/click/milestone/9?closed=1
    Source code(tar.gz)
    Source code(zip)
  • 8.0.4(Feb 18, 2022)

    • Changes: https://click.palletsprojects.com/en/8.0.x/changes/#version-8-0-4
    • Milestone: https://github.com/pallets/click/milestone/13?closed=1
    Source code(tar.gz)
    Source code(zip)
  • 8.0.3(Oct 10, 2021)

  • 8.0.2(Oct 8, 2021)

  • 8.0.1(May 19, 2021)

  • 8.0.0(May 12, 2021)

    New major versions of all the core Pallets libraries, including Click 8.0, have been released! :tada:

    • Read the announcement on our blog: https://palletsprojects.com/blog/flask-2-0-released/
    • Read the full list of changes: https://click.palletsprojects.com/changes/#version-8-0-0
    • Retweet the announcement on Twitter: https://twitter.com/PalletsTeam/status/1392266507296514048
    • Follow our blog, Twitter, or GitHub to see future announcements.

    This represents a significant amount of work, and there are quite a few changes. Be sure to carefully read the changelog, and use tools such as pip-compile and Dependabot to pin your dependencies and control your updates.

    Source code(tar.gz)
    Source code(zip)
  • 8.0.0rc1(Apr 16, 2021)

  • 8.0.0a1(Nov 29, 2020)

  • 7.1.2(Apr 27, 2020)

  • 7.1.1(Mar 9, 2020)

    • Changes: https://click.palletsprojects.com/en/7.x/changelog/#version-7-1-1
    • Blog: https://palletsprojects.com/blog/click-7-1-released/
    • Twitter: https://twitter.com/PalletsTeam/status/1237090317838340099
    Source code(tar.gz)
    Source code(zip)
  • 7.1(Mar 9, 2020)

    • Changes: https://click.palletsprojects.com/en/7.x/changelog/#version-7-1
    • Blog: https://palletsprojects.com/blog/click-7-1-released/
    • Twitter: https://twitter.com/PalletsTeam/status/1237090317838340099
    Source code(tar.gz)
    Source code(zip)
Python library to build pretty command line user prompts ✨Easy to use multi-select lists, confirmations, free text prompts ...

Questionary ✨ Questionary is a Python library for effortlessly building pretty command line interfaces ✨ Features Installation Usage Documentation Sup

Tom Bocklisch 990 Jan 01, 2023
Python library that measures the width of unicode strings rendered to a terminal

Introduction This library is mainly for CLI programs that carefully produce output for Terminals, or make pretend to be an emulator. Problem Statement

Jeff Quast 305 Dec 25, 2022
Typer, build great CLIs. Easy to code. Based on Python type hints.

Typer, build great CLIs. Easy to code. Based on Python type hints. Documentation: https://typer.tiangolo.com Source Code: https://github.com/tiangolo/

Sebastián Ramírez 10.1k Jan 02, 2023
emoji terminal output for Python

Emoji Emoji for Python. This project was inspired by kyokomi. Example The entire set of Emoji codes as defined by the unicode consortium is supported

Taehoon Kim 1.6k Jan 02, 2023
Command line animations based on the state of the system

shell-emotions Command line animations based on the state of the system for Linux or Windows 10 The ascii animations were created using a modified ver

Simon Malave 63 Nov 12, 2022
Simple cross-platform colored terminal text in Python

Colorama Makes ANSI escape character sequences (for producing colored terminal text and cursor positioning) work under MS Windows. PyPI for releases |

Jonathan Hartley 3k Jan 01, 2023
prompt_toolkit is a library for building powerful interactive command line applications in Python.

Python Prompt Toolkit prompt_toolkit is a library for building powerful interactive command line applications in Python. Read the documentation on rea

prompt-toolkit 8.1k Jan 04, 2023
Humane command line arguments parser. Now with maintenance, typehints, and complete test coverage.

docopt-ng creates magic command-line interfaces CHANGELOG New in version 0.7.2: Complete MyPy typehints - ZERO errors. Required refactoring class impl

Jazzband 108 Dec 27, 2022
Cleo allows you to create beautiful and testable command-line interfaces.

Cleo Create beautiful and testable command-line interfaces. Cleo is mostly a higher level wrapper for CliKit, so a lot of the components and utilities

Sébastien Eustace 984 Jan 02, 2023
A minimal and ridiculously good looking command-line-interface toolkit

Proper CLI Proper CLI is a Python package for creating beautiful, composable, and ridiculously good looking command-line-user-interfaces without havin

Juan-Pablo Scaletti 2 Dec 22, 2022
A drop-in replacement for argparse that allows options to also be set via config files and/or environment variables.

ConfigArgParse Overview Applications with more than a handful of user-settable options are best configured through a combination of command line args,

634 Dec 22, 2022
Textual is a TUI (Text User Interface) framework for Python using Rich as a renderer.

Textual is a TUI (Text User Interface) framework for Python using Rich as a renderer. The end goal is to be able to rapidly create rich termin

Will McGugan 17k Jan 02, 2023
Python Command-line Application Tools

Clint: Python Command-line Interface Tools Clint is a module filled with a set of awesome tools for developing commandline applications. C ommand L in

Kenneth Reitz Archive 82 Dec 28, 2022
Terminalcmd - a Python library which can help you to make your own terminal program with high-intellegence instruments

Terminalcmd - a Python library which can help you to make your own terminal program with high-intellegence instruments, that will make your code clear and readable.

Dallas 0 Jun 19, 2022
A cross platform package to do curses-like operations, plus higher level APIs and widgets to create text UIs and ASCII art animations

ASCIIMATICS Asciimatics is a package to help people create full-screen text UIs (from interactive forms to ASCII animations) on any platform. It is li

3.2k Jan 09, 2023
Corgy allows you to create a command line interface in Python, without worrying about boilerplate code

corgy Elegant command line parsing for Python. Corgy allows you to create a command line interface in Python, without worrying about boilerplate code.

Jayanth Koushik 7 Nov 17, 2022
sane is a command runner made simple.

sane is a command runner made simple.

Miguel M. 22 Jan 03, 2023
Python and tab completion, better together.

argcomplete - Bash tab completion for argparse Tab complete all the things! Argcomplete provides easy, extensible command line tab completion of argum

Andrey Kislyuk 1.1k Jan 08, 2023
plotting in the terminal

bashplotlib plotting in the terminal what is it? bashplotlib is a python package and command line tool for making basic plots in the terminal. It's a

Greg Lamp 1.7k Jan 02, 2023
Library for building powerful interactive command line applications in Python

Python Prompt Toolkit prompt_toolkit is a library for building powerful interactive command line applications in Python. Read the documentation on rea

prompt-toolkit 8.1k Dec 30, 2022