Package: colorlabels
colorlabelscolorlabelsis a console message display library for Python. Equipped with various kinds of colorful and semantic labels, it is tailored for message display and interaction in automated scripts (e.g. test scripts, installation scripts and hacker tools).Demoimporttimeimportcolorlabelsasclcl.section('Overview of Labels')cl.success('Good job! All test cases passed!')cl.warning('Warning! Security update delayed!')cl.error('Error! Failed to write file!')cl.info('Server listening on port 8888.')cl.progress('Downloading package, please wait...')cl.plain('Nothing interesting.')choice=cl.question('A new version is present, would you like to update? (Y/N)')withcl.progress('Downloading...',mode=cl.PROGRESS_SPIN):time.sleep(3)withcl.progress('Downloading ',mode=cl.PROGRESS_DETERMINATE)asp:time.sleep(1)p.update(0.5,' 50% (2.5MB/5MB) ETA 1s')time.sleep(1)p.update(1,' 100% (5MB/5MB)')FeaturesVarious kinds of labels and progress animations. Colorful and semantic.Easy to use.Customizable.Compatible.Works on Unix-like Systems & Windows. (Based oncolorama)Works on both Python 2 & 3 (Python 2 may not work well with unicode).InstallationInstall with pip:pip install -U colorlabelsDocumentationConceptscolorlabelsmimics the famousBootstraplibrary in Web front-end developing, providing a number of components (calledlabels) to facilitate message display and interaction in automated scripts.Option LayeringIncolorlabels, most of the configurable options are organized in three layers:Default settingsRuntime global settings (using the module-level functionconfig(), apply to the whole running process)Per-call settings (setting parameters when calling label printing functions, only apply to this function call)Runtime global settings can override default settings, and per-call settings can override runtime global settings and default settings.LabelAlabelis a line of message composed of aheaderand itscontent. A header is amarkwith a pair of brackets.Here is an anatomy of a label:When usingcolorlabels, you will be able to customize a label's mark and color settings. However, the default settings should already look nice under most operating systems and terminals with a dark background.colorlabelsprovides the following kinds of labels with semantic names:section,item,success,warning,error,info,progress,plain,question,inputandpassword. Thesection,item,success,warning,error,infoandplainlabels print a message to the console. Theprogresslabel can alternatively display some animation. Thequestion,inputandpasswordlabels prompt for user input. Behaviors of all the labels can be demonstrated by runningdemo.py.Mark and ColorMarksandcolorsare carefully selected to visually symbolize the semantic meaning of a label, which makes labels pretty and easy for visual grepping.A mark is a non-empty string to be enclosed in a pair of brackets to comprise a header. By default all marks for labels are composed of only one character, but you can customize them to contain more than one character, or even emojis if you wish to.If you prefer labels without headers, you can set theshow_headeroption toFalseto remove them.A color is anANSI escape sequencerepresenting color in terminal.colorlabelsutilizescoloramato achieve cross-platform color printing compatibility. By default all colors for labels only contain the classic and ubiquitous 16 colors (code 30-37, 90-97), but you can customize them to include 8-bit colors and 24-bit colors if you wish to.Thecolor_spanoption specifies the range that color covers in a label. There are four values forcolor_span:0: does not color any part of the label1: colors only the mark2: colors only the header3: colors the whole label (default)The default marks and colors for different kinds of labels are as follows:Label TypeDefault MarkDefault Colorsection#Bright Magenta (95)item*No Colorsuccess+Bright Green (92)warning!Bright Yellow (93)error-Bright Red (91)infoiBright Cyan (96)progress=Bright Cyan (96)plain*No Colorquestion?Bright Cyan (96)input>Bright Cyan (96)password>Bright Cyan (96)The Progress LabelThe progress label supports different modes:Progress ModeAnimationDeterminatePROGRESS_STATICNoneN/APROGRESS_SPINSpinningNoPROGRESS_EXPANDExpanding CharactersNoPROGRESS_MOVEMoving CharactersNoPROGRESS_DETERMINATEProgress BarYesThe static progress label only prints a message without any animation, just like non-progress labels. Non-static progress labels can be classified asdeterminateandindeterminate. A determinate progress label has a concrete progress value (percentage) associated with it, and user should notify the progress label to update the percentage value (and alternatively other messages about the progress). An indeterminate progress label does not have a concrete percentage value (we cannot estimate the end of the progress), and user should notify the progress label to stop the animation when the progress ends.For a detailed list of configurable options regarding progress labels, please refer to the corresponding content in the API Reference part of this documentation.TTY mode and non-TTY modeBy default,colorlabelswill detect whether the standard output is interactive (i.e. connected to a terminal/tty device). If it is not interactive,colorlabelswill operate in non-TTY mode, where color output and progress animations will be disabled (i.e. no ANSI escape sequence printed, all progress labels become static), to make output parsing easier. However, you can override this behavior by setting theCOLORLABELS_TTYenvironment variable. IfCOLORLABELS_TTYis set to one of'1', 'yes', 'y', 'true', 'on'(case-insensitive), this will force the use of TTY mode (i.e. treat standard output as interactive and display color output and progress animations as usual); ifCOLORLABELS_TTYis set to one of'0', 'no', 'n', 'false', 'off'(case-insensitive), this will force the use of non-TTY mode.API ReferenceModule-level Functionscolor_code(color_number)Generate an ANSI escape sequence with the given color number or description string.Arguments:color_number: required,any, color number or description stringReturn:str, an ANSI escape sequenceconfig(**kwargs)Set up runtime global settings.Arguments:section_color: optional,str, runtime global settings of color forsectionlabelsitem_color: optional,str, runtime global settings of color foritemlabelssuccess_color: optional,str, runtime global settings of color forsuccesslabelswarning_color: optional,str, runtime global settings of color forwarninglabelserror_color: optional,str, runtime global settings of color forerrorlabelsinfo_color: optional,str, runtime global settings of color forinfolabelsprogress_color: optional,str, runtime global settings of color forprogresslabelsplain_color: optional,str, runtime global settings of color forplainlabelsquestion_color: optional,str, runtime global settings of color forquestionlabelsinput_color: optional,str, runtime global settings of color forinputlabelspassword_color: optional,str, runtime global settings of color forpasswordlabelssection_mark: optional,str, runtime global settings of mark forsectionlabelsitem_mark: optional,str, runtime global settings of mark foritemlabelssuccess_mark: optional,str, runtime global settings of mark forsuccesslabelswarning_mark: optional,str, runtime global settings of mark forwarninglabelserror_mark: optional,str, runtime global settings of mark forerrorlabelsinfo_mark: optional,str, runtime global settings of mark forinfolabelsprogress_mark: optional,str, runtime global settings of mark forprogresslabelsplain_mark: optional,str, runtime global settings of mark forplainlabelsquestion_mark: optional,str, runtime global settings of mark forquestionlabelsinput_mark: optional,str, runtime global settings of mark forinputlabelspassword_mark: optional,str, runtime global settings of mark forpasswordlabelscolor_span: optional,int, runtime global settings of color span, should be in [0, 1, 2, 3]show_header: optional,bool, runtime global settings of whether to display headers for labelsReturn:Nonesection(msg, **kwargs)Display asectionlabel containing the given message.Arguments:msg: required,any, the message content to displaycolor: optional,str, the color for this labelmark: optional,str, the mark for this labelcolor_span: optional,int, the color span for this label, should be in [0, 1, 2, 3]show_header: optional,bool, whether to display header for this labelReturn:Noneitem(msg, **kwargs)Display anitemlabel containing the given message.Arguments: The same assection().Return:Nonesuccess(msg, **kwargs)Display asuccesslabel containing the given message.Arguments: The same assection().Return:Nonewarning(msg, **kwargs)Display awarninglabel containing the given message.Arguments: The same assection().Return:Noneerror(msg, **kwargs)Display anerrorlabel containing the given message.Arguments: The same assection().Return:Noneinfo(msg, **kwargs)Display aninfolabel containing the given message.Arguments: The same assection().Return:Noneplain(msg, **kwargs)Display aplainlabel containing the given message.Arguments: The same assection().Return:Nonequestion(msg, **kwargs)Display aquestionlabel containing the given message and prompt for user input.Arguments: The same assection().Return:str, the string that user inputsinput(msg, **kwargs)Display aninputlabel containing the given message and prompt for user input.Arguments: The same assection().Return:str, the string that user inputspassword(msg, **kwargs)Display apasswordlabel containing the given message and prompt for user input. The password will not be echoed on the terminal.Arguments: The same assection().Return:str, the password that user inputsprogress(msg, mode=PROGRESS_STATIC, **kwargs)Display aprogresslabel containing the given message.Arguments: Accept all arguments forsection(). In addition:mode: optional, should be one of [PROGRESS_STATIC,PROGRESS_SPIN,PROGRESS_EXPAND,PROGRESS_MOVE,PROGRESS_DETERMINATE]For modePROGRESS_SPIN:position: optional,str, the position of spinner, should be one of ['mark', 'tail'], default is 'mark'interval: optional,float, the refreshing interval (in seconds), default is 0.1erase: optional,bool, whether to erase the whole label when animation finished, default isFalseFor modePROGRESS_EXPAND:char: optional,char, the character to expand, default is '.'width: optional,int, the maximum width to expand, default is 3interval: optional,float, the refreshing interval (in seconds), default is 1erase: optional,bool, whether to erase the whole label when animation finished, default isFalseFor modePROGRESS_MOVE:char: optional,char, the character to move, default is '.'num: optional,int, the number of characters to move, default is 3width: optional,int, the width of range that characters move in, default is 12style: optional,str, the style of moving, can be one of:'loop': when characters hit the boundary, they will appear at the other boundary in the next cycle (default)'reflect': when characters hit the boundary, they will be reflected back and alter their moving directioninterval: optional,float, the refreshing interval (in seconds), default is 0.1erase: optional,bool, whether to erase the whole label when animation finished, default isFalseFor modePROGRESS_DETERMINATE:char_done: optional,char, the character to represent done percentage, default is '='char_head: optional,char, the character to display at the head of the progress bar, default is '>'char_undone: optional,char, the character to represent undone percentage, default is ' 'width: optional,int, the width of the progress bar, default is 40cleanup: optional,bool, whether to remove the progress bar when animation finished (original label message will remain), default isFalseerase: optional,bool, whether to erase the whole label when animation finished, default isFalseReturn:For modePROGRESS_STATIC, returnNoneFor other modes, return aProgressLabelobjectnewline()Print an empty line.Return:NoneProgressLabelMethodsWe recommend using context managers (withstatements) to manage progress labels with animations, as in our demo, which automatically stop the animation and clean up the side effects whether the progress normally ends or some exceptions occur. However, you may still call thestop()method if you want to manually stop the animation.stop()Stop progress animation. This is automatically called by the__exit__()of the context manager, but you can also manually call it if you wish to.Arguments: NoneReturn:Noneupdate(percent, text='')Update progress to the given percentage in determinate mode. You can provide additional text to describe current status.Arguments:percent: required,float, the percentage of the progresstext: optional,str, additional text to describe current status, will be appended after the progress barReturn:None