Skip to main content

Produce colored terminal text with an xml-like markup

Project description

Latest version released on PyPi Build status BSD 3-Clause

Ansimarkup is an XML-like markup for producing colored terminal text.

from ansimarkup import ansiprint as print

print('<b>bold text</b>'))
print('<red>red text</red>', '<red,green>red text on a green background</red,green>')

Installation

The latest stable version of ansimarkup can be installed from pypi:

$ pip install ansimarkup

Usage

Basic

from ansimarkup import parse, ansiprint

# parse() converts the tags to the corresponding ansi escape sequence.
parse("<b>bold</b> <d>dim</d>")

# ansiprint() works exactly like print(), but first runs parse() on all arguments.
ansiprint("<b>bold</b>", "<d>dim</d>")
ansiprint("<b>bold</b>", "<d>dim</d>", sep=':', file=sys.stderr)

Colors and styles

# Colors may be specified in one of several ways.
parse("<red>red foreground</red>")
parse("<RED>red background</RED>")
parse("<fg red>red foreground</fg red>")
parse("<bg red>red background</bg red>")

# Tags may be nested.
parse("<r><Y>red text on a yellow foreground</Y></r>")

# The above may be more concisely written as:
parse("<r,y>red text on a yellow background</r,y>")

# This shorthand also supports style tags.
parse("<b,r,y>bold red text on a yellow background</b,r,y>"
parse("<b,r,>bold red text</b,r,>
parse("<b,,y>bold regular text on a yellow background</b,,y>

# Unrecognized tags are left as-is.
parse("<b><element1></element1></b>")

For a list of markup tags, please refer to tags.py.

User-defined tags

Custom tags or overrides for existing tags may be defined by creating a new AnsiMarkup instance:

from ansimarkup import AnsiMarkup, parse

user_tags = {
    # Add a new tag (e.g. we want <info> to expand to '<bold><green>'
    'info': parse('<b><g>')

    # ... or use the ansi escape sequence directly
    'info': 'e\x1b[32m\x1b[1m',

    # Tag names may also be callables.
    'err':  lambda: parse('<r>')

    # User-defined tags always take precedence over existing tags.
    'bold': parse('<dim>')
}

am = AnsiMarkup(tags=user_tags)

am.parse('<info>bold green</info>')
am.ansiprint('<err>red</err>')

# Calling the instance is equivalent to calling its parse method.
am('<b>bold</b>') == am.parse('<b>bold</b>')

Other features

The default tag separators can be changed by passing the tag_sep argument to AnsiMarkup:

from ansimarkup import AnsiMarkup

am = AnsiMarkup(tag_sep='{}')
am.parse('{b}{r}bold red{/b}{/r}

Command-line

Ansimarkup may also be used as a command-line script. This works as if all arguments were passed to ansiprint():

$ python -m ansimarkup "<b>bold</b>" "<red>red</red>"

Logging formatter

Ansimarkup also comes with a formatter for the standard library logging module. It can be used as:

import logging
from ansimarkup.logformatter import AnsiMarkupFormatter

log = logging.getLogger()
hdl = logging.StreamHandler()
fmt = AnsiMarkupFormatter()
hdl.setFormatter(fmt)
log.addHandler(hdl)

log.info("<b>bold text</b>")

Windows

Ansimarkup uses the colorama library internally, which means that Windows support for ansi escape sequences is available by first running:

import colorama
colorama.init()

For more information on Windows support, consult the “Usage” section of the colorama documentation.

Performance

While the focus of ansimarkup is convenience, it does try to keep processing to a minimum. The benchmark.py script attempts to benchmark different ansi escape code libraries:

Benchmark 1: <r><b>red bold</b></r>
  colorama     0.2998 μs
  termcolor    3.2339 μs
  colr         3.6483 μs
  ansimarkup   6.8679 μs
  pastel       28.8538 μs
  plumbum      53.5004 μs

Benchmark 2: <r><b>red bold</b>red</r><b>bold</b>
  colorama     0.8269 μs
  termcolor    8.9296 μs
  ansimarkup   9.3099 μs
  colr         9.6244 μs
  pastel       62.2018 μs
  plumbum      120.8048 μs

Limitations

Ansimarkup is a simple wrapper around colorama. It does very little in the way of validating that markup strings are well-formed. This is a conscious decision with the goal of keeping things simple and fast.

Unbalanced nesting, such as in the following example, will produce incorrect output:

<r><Y>1</r>2</Y>

Todo

  • Many corner cases remain to be fixed.

  • The documentation needs to be moved from the readme to a sphinx doc.

  • More docstrings and comments.

  • The testsuite is very superficial.

  • The tag_list.index in sub_end can be replaced with something more efficient (i.e. something like an ordered MultiDict).

Similar libraries

  • pastel: bring colors to your terminal

  • plumbum.colors: small yet feature-rich library for shell script-like programs in Python

License

Ansimarkup is released under the terms of the Revised BSD License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ansimarkup-0.3.0.tar.gz (8.4 kB view hashes)

Uploaded Source

Built Distribution

ansimarkup-0.3.0-py2.py3-none-any.whl (11.7 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page