Metadata-Version: 1.1
Name: clickutil
Version: 0.0.1
Summary: Tools for working with container types, command data operations, and concise exception handling
Home-page: https://github.com/stroxler/clickutil
Author: Steven Troxler
Author-email: steven.troxler@gmail.com
License: MIT
Description: clickutil - making click even better
        ====================================
        
        Python's `click` package is an awesome tool for building command-line
        interfaces. But sometimes to use `click` the way I want to I need a
        lot of boilerplate code, so I wrote `clickutil` to make my command
        line packages more concise and less buggy.
        
        
        Keep access to your python functions by using `clickutil.call`
        --------------------------------------------------------------
        
        A normal click decorator looks something like this:
        
        ::
          @click.command('do-something')
          @click.option('--an-option', required=True, help='a click option')
          def do_something(an_option):
              click.echo(an_option)
        
        
        This can be frustrating if you want to expose a public api that is accessible
        from both python and the command line, because the original `do_someting`
        function which took an argument is replaced by a function that takes no
        arguments and reads `sys.argv` for inputs.
        
        The `clickutil.call` decorator lets you instead decorate a placeholder function
        as calling some function you want as part of your public api, so that the
        original function may still be accessed from python:
        
        ::
          def do_something(an_option):
              click.echo(an_option)
        
          @click.command('do-something')
          @click.option('--an-option', required=True, help='a click option')
          def _do_something(): pass
        
        
        Add debugging using clickutil.debug
        -----------------------------------
        
        A common workflow for python developers is to load code from `ipython` and run
        it from the shell. There are several benefits to doing this, one of which is
        that you can use the `%debug` magic command if unhandled exceptions occur.
        
        The `clickutils.debug` decorator lets you get a similar benefit when running
        click commands, by dropping into a debugger on unhandled exceptions. By default
        it adds an option `--debug`. When that flag is used, on any exceptions the click
        endpoint will enter a debugger after delaying a few seconds (which gives the
        user a chance to keyboard escape if they don't need to debug). The delay, and
        also whether to debug by default, can both be configured.
        
        By default, `clickutil` will first try `pudb` and then `pdb` for debugging, but
        this is configurable via an argument.
        
        For example, here we debug using `ipdb` after 10 seconds of waiting in the
        event that `do_something` raises an exception. We do so by default, so to
        turn off this behavior you would need to use the `--no-debug` flag:
        
        ::
          import ipdb
        
          @click.command('do-something')
          @click.debug(default=False, delay=10, use_debugger=ipdb)
          @click.call(do_something)
          def _do_something(): pass
        
        More concise options and flags
        ------------------------------
        
        The `click.option` function takes a lot of arguments to control different
        kinds of behaviors, and conflates a lot of different kinds of options
        (for example, boolean flags like `--debug/--no-debug` get grouped together
        with options that take arguments). Partly because the behavior of a click
        option depends on many different arguments, some of the default behaviors -- such
        as not showing the default value of an option that has a default in the
        `--help` output -- don't make sense.
        
        To make working with options easier, `clickutil` provides three more specific
        functions: `clickutil.boolean_flag` for setting flags such as `--debug`,
        `clickutil.required_option` for options that take an argument and must be
        provided, and `clickutil.default_option` for options that take an argument
        and need not be provided. It also provides three special option types,
        `clickutil.EXISTING_FILE`, `clickutil.EXISTING_DIR`, and
        `clickutil.NEW_FILE_OR_DIR`, to handle the most common `click.Path` input
        types.
        
        Detecting default values from function signatures
        -------------------------------------------------
        
        Because clickutil tries to keep the original python function available
        for calling from python using `clickutil.call`, it becomes irritating to
        have to set default values for `default_option`s and `boolean_flag`s twice,
        both in the function and in the click decorators. In addition, the fact that
        these two can differ becomes a potential source of bugs.
        
        By inspecing the arguments of functions, `clickutil` is able to set defaults
        based on the argument list in the definition of a function.
        
        The `clickutil.boolean` decorator is similar to `clickutil.boolean_flag`,
        except it picks up its default value from the function signature. Similarly,
        `clickutil.option` is like `clickutil.required_option` or
        `clickutil.default_option`, depending on whether there's a default value in the
        function signature.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2.7
