Titles, Rules, and Spacing

say defines a few convenience formatting functions:

say.title('Errors', char='-')
for i,e in enumerate(errors, start=1):
    say("{i:3}: {e['name'].upper()}")

might yield:

--------------- Errors ---------------

  1: I/O ERROR
  2: COMPUTE ERROR

A similar method hr produces just a horizontal line (“rule”), like the HTML <hr> element. For either, one can optionally specify the width (width), character repeated to make the line (char), and vertical separation/whitespace above and below the item (vsep). Good options for the repeated character might be be ‘-‘, ‘=’, or parts of the Unicode box drawing character set.

A final method, sep, creates a short left-aligned bar with optional following text. It’s useful for creating logical subsections.:

say.sep("coffee")
say("I prefer coffee")
say.sep("tea", char="=", width=4)
say("I prefer tea")

Yields:

-- coffee
I prefer coffee

==== tea
I prefer tea

You can even define reusable styles for separators (and other say calls):

tilde_sep = dict(char="~", width=4)
say.sep("pass one", **tilde_sep)

Yields:

~~~~ pass one

Note

The char parameter was until recently called sep, which conflicted with another use of sep. It has since been renamed.

Vertical Spacing

You don’t need to add explicit newline characters here and there to achieve good vertical spacing. say.blank_lines(n) emits n blank lines. And just about every say call also supports a vsep (vertical separation) parameter.:

say('TITLE', vsep=(2,0)        # add 2 newlines before (none after)
say('=====', vsep=(0,2))       # add 2 newlines after (none before)
say('something else', vsep=1)  # add 1 newline before, 1 after

This Just In

A new capability is to differentially set the formatting parameters on a method by method basis. For example, if you want to see titles in green:

say.title.set(style='green')

You could long set such options on a call-by-call basis, but being able to set the defaults just for specific methods allows you to get more formatting in with fewer characters typed. This capability is available on a limited basis: primarily for format-specific calls (blank_lines, hr, sep, and title) for now.

Note

title and sep now print out more vertical whitespace than in previous versions. This is a direct usage of this method-by-method configurability. Basically, say.title.set(vsep=1) and say.sep.set(vsep=(1,0)) now come baked-in.