Metadata-Version: 1.1
Name: Colr
Version: 0.9.1
Summary: Easy terminal colors, with chainable methods.

Home-page: https://github.com/welbornprod/colr
Author: Christopher Welborn
Author-email: cj@welbornprod.com
License: UNKNOWN
Description: Colr
        ====
        
        A python module for using terminal colors. It contains a simple
        ``color`` function that accepts style and color names, and outputs a
        string with escape codes, but also has all colors and styles as
        chainable methods on the ``Colr`` object.
        
        --------------
        
        Dependencies:
        -------------
        
        System
        ~~~~~~
        
        -  **Python 3.5+** - This library uses ``yield from`` and the ``typing``
           module. `Python 2 support is not planned. <#python-2>`__
        
        Modules
        ~~~~~~~
        
        There are no dependencies required for importing this library, however:
        
        -  `Docopt <https://github.com/docopt/docopt>`__ - Only required for the
           command line tools (`colr <#colr-tool>`__ and
           `colr-run <#colr-run>`__) and the `colr.docopt
           wrapper <#colrdocopt>`__, not the library itself.
        
        Installation:
        -------------
        
        Colr is listed on `PyPi <https://pypi.python.org/pypi/Colr>`__, and can
        be installed using `pip <https://pip.pypa.io/en/stable/installing/>`__:
        
        ::
        
            pip install colr
        
        Or you can clone the repo on
        `GitHub <https://github.com/welbornprod/colr>`__ and install it from the
        command line:
        
        ::
        
            git clone https://github.com/welbornprod/colr.git
            cd colr
            python3 setup.py install
        
        --------------
        
        Examples:
        ---------
        
        Simple:
        ~~~~~~~
        
        .. code:: python
        
            from colr import color
            print(color('Hello world.', fore='red', style='bright'))
        
        Chainable:
        ~~~~~~~~~~
        
        .. code:: python
        
            from colr import Colr as C
            print(
                C()
                .bright().red('Hello ')
                .normal().blue('World')
            )
        
            # Background colors start with 'bg', and AttributeError will be raised on
            # invalid method names.
            print(C('Hello ', fore='red').bgwhite().blue('World'))
        
        Examples (256 Colors):
        ----------------------
        
        Simple:
        ~~~~~~~
        
        .. code:: python
        
            from colr import color
            # Invalid color names/numbers raise a ValueError.
            print(color('Hello world', fore=125, back=80))
        
        Chainable:
        ~~~~~~~~~~
        
        .. code:: python
        
            from colr import Colr as C
            # Foreground colors start with 'f_'
            # Background colors start with 'b_'
            print(C().f_125().b_80('Hello World'))
        
        Examples (True Color):
        ----------------------
        
        Simple:
        ~~~~~~~
        
        .. code:: python
        
            from colr import color
            print(color('Hello there.', fore=(255, 0, 0), back=(0, 0, 0)))
        
        Chainable:
        ~~~~~~~~~~
        
        .. code:: python
        
            from colr import Colr as C
            # Foreground colors are set with the `rgb()` method.
            # Background colors are set with the `b_rgb()` method.
            # Text for the chained methods should be chained after or during
            # the call to the methods.
            print(C().b_rgb(0, 0, 0).rgb(255, 0, 0, 'Hello there.'))
        
        Examples (Hex):
        ---------------
        
        Simple:
        ~~~~~~~
        
        .. code:: python
        
            from colr import color
            # When not using the Colr.hex method, the closest matching extended code
            # is used. For true color, just use:
            #     fore=hex2rgb('ff0000')
            # or
            #     Colr.hex('ff0000', rgb_mode=True)
            print(color('Hello there.', fore='ff0000', back='000'))
        
        Chainable:
        ~~~~~~~~~~
        
        .. code:: python
        
            from colr import Colr as C
            # Foreground colors are set with the `hex()` method.
            # Background colors are set with the `b_hex()` method.
            # Text for the chained methods should be chained after or during
            # the call to the methods.
            print(C().b_hex('#000').hex('ff0000', 'Hello there.'))
        
            # With rgb_mode set, these are the same:
            print(C().hex('ff0000', 'test', rgb_mode=True))
            print(C().rgb(255, 0, 0, 'test'))
        
        --------------
        
        Documentation:
        --------------
        
        Documentation for the ``colr`` API can be found in the GitHub repo
        (`github.com/welbornprod/colr <https://github.com/welbornprod/colr>`__):
        
        +-------------------------------------+--------------------------------------+
        | Module/Object                       | Description                          |
        +=====================================+======================================+
        | `colr.Colr <https://github.com/welb | Methods for the ``Colr`` object, to  |
        | ornprod/colr/blob/dev/docs/colr.Col | colorize text.                       |
        | r.md>`__                            |                                      |
        +-------------------------------------+--------------------------------------+
        | `colr.Control <https://github.com/w | Functions, classes, and methods for  |
        | elbornprod/colr/blob/dev/docs/colr. | the ``Control`` object, to control   |
        | controls.md>`__                     | the cursor/screen.                   |
        +-------------------------------------+--------------------------------------+
        | colr.ColrControl                    | ``Colr`` and ``Control`` merged into |
        |                                     | one class. See ``colr.Colr`` and     |
        |                                     | ``colr.Control``.                    |
        +-------------------------------------+--------------------------------------+
        | `colr.progress <https://github.com/ | Progress updates, bars, or spinners. |
        | welbornprod/colr/blob/dev/docs/colr |                                      |
        | .progress.md>`__                    |                                      |
        +-------------------------------------+--------------------------------------+
        | `colr.trans <https://github.com/wel | Color code translation/detection.    |
        | bornprod/colr/blob/dev/docs/colr.tr |                                      |
        | ans.md>`__                          |                                      |
        +-------------------------------------+--------------------------------------+
        
        --------------
        
        Colr Tool:
        ----------
        
        The ``colr`` package can be used as a command line tool. An entry point
        script named ``colr`` is created when installed with pip. Otherwise it
        can be executed using the ``python -m colr`` method.
        
        .. code:: bash
        
            colr --help
        
        Basic usage involves passing text, or piping stdin data and setting the
        colors by position or flag.
        
        .. code:: bash
        
            # These all do the same thing:
            colr "Test" "red" "white" "bright"
            colr "Test" -f "red" -b "white" -s "bright"
            printf "Test" | colr -f "red" -b "white" -s "bright"
        
        Using the positional arguments is faster for just setting fore colors,
        but the flag method is needed for stdin data, or for picking just the
        background color or style:
        
        .. code:: bash
        
            colr "Test" -s "bright"
        
        Extended and True colors are supported:
        
        .. code:: bash
        
            colr "Test" 124 255
            colr "Test" "255, 0, 0" "255, 255, 255"
            # Use true color (rgb) escape codes to generate a gradient, and then
            # center it in the terminal (0 means use terminal width).
            colr "Test" -G "255,0,0" -G "0,0,255" -c 0
        
        It will do fore, back, style, gradients, rainbows, justification, and
        translation. It can strip codes from text (as an argument or stdin), or
        explain the codes found in the text.
        
        `lolcat <https://github.com/busyloop/lolcat>`__ emulation:
        
        .. code:: bash
        
            fortune | colr --rainbow
        
        The colr tool does not read files, but it's not a problem:
        
        .. code:: bash
        
            cat myfile.txt | colr --gradient red
        
        Also see `ccat <https://github.com/welbornprod/ccat>`__.
        
        Colr-run:
        ---------
        
        A small command-runner is included, called ``colr-run``. This program
        will run another program, printing an animated message instead of the
        normal output.
        
        It is used to turn "noisy" commands into a nice single-line animation.
        
        Basic Example:
        ~~~~~~~~~~~~~~
        
        To run a program with the default settings, ``--`` is still required:
        
        .. code:: bash
        
            colr-run -- bash -c 'x=0; while ((x<1000000)); do let x+=1; done'
        
        Any stderr output from the program will ruin the animation, which may be
        fine if you are only looking for errors.
        
        You can silence stderr output with ``-e`` if you don't need it:
        
        .. code:: bash
        
            colr-run -e -- some-long-running-command
        
        The exit status of ``colr-run`` is the exit status of the command being
        executed. For ``colr-run`` errors, the exit status is ``1`` for basic
        errors, and ``2`` for cancelled commands.
        
        Colr.docopt:
        ------------
        
        Colr provides a wrapper for docopt that will automatically colorize
        usage strings. If you provide it a script name it will add a little more
        color by colorizing the script name too.
        
        .. code:: python
        
            from colr import docopt
            argd = docopt(USAGE, script='mycommand')
        
        --------------
        
        Contributing:
        -------------
        
        As always contributions are welcome here. If you think you can improve
        something, or have a good idea for a feature, please file an
        `issue <https://github.com/welbornprod/colr/issues/new>`__ or a `pull
        request <https://github.com/welbornprod/colr/compare>`__.
        
        --------------
        
        Notes:
        ------
        
        Reasons
        ~~~~~~~
        
        In the past, I used a simple ``color()`` function because I'm not fond
        of the string concatenation style that other libraries use. The 'clor'
        javascript library uses method chaining because that style suits
        javascript, but I wanted to make it available to Python also, at least
        as an option.
        
        Reset Codes
        ~~~~~~~~~~~
        
        The reset code is appended only if some kind of text was given, and
        colr/style args were used. The only values that are considered 'no text'
        values are ``None`` and ``''`` (empty string). ``str(val)`` is called on
        all other values, so ``Colr(0, 'red')`` and ``Colr(False, 'blue')`` will
        work, and the reset code will be appended.
        
        This makes it possible to build background colors and styles, but also
        have separate styles for separate pieces of text.
        
        Python 2
        ~~~~~~~~
        
        I don't really have the desire to back-port this to Python 2. It
        wouldn't need too many changes, but I like the Python 3 features
        (``yield from``, ``str/bytes``).
        
        Windows
        ~~~~~~~
        
        Windows 10 finally has support for ANSI escape codes. Colr can now be
        used on Windows 10+ by calling ``SetConsoleMode``. Older Windows
        versions are not supported and haven't been tested. If you are using
        Colr for a tool that needs to support older Windows versions, you will
        need to detect the current Windows version and call ``colr.disable()``
        for those that aren't supported. Otherwise you will have "junk"
        characters printed to the screen.
        
        Misc.
        ~~~~~
        
        This library may be a little too flexible:
        
        .. code:: python
        
            from colr import Colr as C
            warnmsg = lambda s: C('warning', 'red').join('[', ']')(' ').green(s)
            print(warnmsg('The roof is on fire again.'))
        
        .. figure:: https://welbornprod.com/static/media/img/colr-warning.png
           :alt: The possibilities are endless.
        
           The possibilities are endless.
        
Keywords: python module library 2 3 terminal escape codes color
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
