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)
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
Color text streams with a polished command line interface

colout(1) -- Color Up Arbitrary Command Output Synopsis colout [-h] [-r RESOURCE] colout [-g] [-c] [-l min,max] [-a] [-t] [-T DIR] [-P DIR] [-d COLORM

nojhan 1.1k Dec 21, 2022
Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object.

Python Fire Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object. Python Fire is a s

Google 23.6k Dec 31, 2022
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
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
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 4, 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
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 2, 2023
Pythonic command line arguments parser, that will make you smile

docopt creates beautiful command-line interfaces Video introduction to docopt: PyCon UK 2012: Create *beautiful* command-line interfaces with Python N

null 7.7k Dec 30, 2022
A CLI tool to build beautiful command-line interfaces with type validation.

Piou A CLI tool to build beautiful command-line interfaces with type validation. It is as simple as from piou import Cli, Option cli = Cli(descriptio

Julien Brayere 310 Dec 7, 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 2, 2023
sane is a command runner made simple.

sane is a command runner made simple.

Miguel M. 22 Jan 3, 2023
A simple terminal Christmas tree made with Python

Python Christmas Tree A simple CLI Christmas tree made with Python Installation Just clone the repository and run $ python terminal_tree.py More opti

Francisco B. 64 Dec 27, 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 1, 2023
Rich is a Python library for rich text and beautiful formatting in the terminal.

Rich 中文 readme • lengua española readme • Läs på svenska Rich is a Python library for rich text and beautiful formatting in the terminal. The Rich API

Will McGugan 41.4k Jan 2, 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 2, 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 8, 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
A thin, practical wrapper around terminal capabilities in Python

Blessings Coding with Blessings looks like this... from blessings import Terminal t = Terminal() print(t.bold('Hi there!')) print(t.bold_red_on_brig

Erik Rose 1.4k Jan 7, 2023