The theme module

This module provides the Theme class, which provides text formatting properties based on the action (standard action) of a Token.

These properties can be used to colorize text according to a language definition.

By default, the properties are read from a normal CSS (Cascading StyleSheets) file and presented to the user of the Theme module through TextFormat objects, although other storage backends could be devised.

A Theme provides a textformat() for standard actions, and for three general situations: window(), which denotes an editor window (or an encompassing DIV or PRE block in HTML), selection(), which is used for selected text, and currentline(), which can highlight the current line the cursor is in in an editor.

From the TextFormat returned by selection() and currentline(), in most cases only the background color will be used.

The methods window(), selection() and currentline() also accept a state argument, which can be “default”, “focus” or “disabled”. A theme always supports the default state, but can provide separate colors for the “focus” or “disabled” state, which can be used to change the basic formatting in an editor window based on its state (in keyboard focus or disabled). If a theme does not support the “disabled” and/or “focus” state, the default scheme is used.

In the themes/ directory are bundled CSS themes that can be used. Instantiate a bundled theme with:

>>> from parce.theme import Theme
>>> th = Theme.byname("default")

To use a custom CSS theme file, load it using:

>>> th = Theme('/path/to/my/custom.css')

Get a TextFormat for an action, use e.g.:

>>> f = th.textformat(String)
>>> f
<TextFormat color=Color(r=192, g=0, b=0, a=255)>

Mapping actions to CSS classes

Standard actions are mapped to a tuple of CSS class names: the action itself and the actions it descends from. All CSS rules are combined, the one with the most matches comes first.

For example, Comment maps to the “comment” CSS class, and Number maps to (“literal”, “number”) because Number is a descendant action of Literal.

Some actions might have the same name, e.g. Escape and String.Escape. Both match CSS rules with the .escape class selector, but a rule with .string.escape will have higher precedence.

The order of the action names does not matter. E.g. an action Text.Comment will match exactly the same CSS rules as an action Comment.Text. So you should take some care when designing you action hierachy and not add too much base action types.

class Theme(filename='', stylesheet='')[source]

Bases: object

A Theme maps a StandardAction to a TextFormat with CSS properties.

classmethod byname(name='default')[source]

Create Theme by name.

The name is a CSS file in the themes/ directory, without the “.css” extension.

property style

The stylesheet style rules (see css.Style).

filenames()[source]

Return the list of filenames of the used stylesheet when instantiated

baseformat(role='window', state='default')[source]

Return a TextFormat for a specific role and a state.

The role may be any string that maps to a CSS class in the theme CSS file that is available there together with the ‘parce’ class.

The following roles are recognized and used by parce, but you may also define your own roles in your (applications’) theme CSS files:

"window"

The TextFormat for the editor window or the encompassing DIV when formatting HTML. Corresponds to the “parce” CSS class alone in the theme file. You can set color, background and, if desired, font preferences.

"selection"

The TextFormat to use for selected text. Uses the ::selection pseudo element.

"current-line"

The TextFormat for the current line. If you use it, set only the background color in your theme file.

"trialing-whitespace"

The TextFormat (use only the background) to highlight trialing whitespace, if desired.

"eol-marker"

The color to draw a “end-of-line” marker with, if desired

The state argument may be “default”, “focus”, or “disabled”, and reflects the state of the user interface the style variant is used for.

textformat(action)[source]

Return the TextFormat for the specified action.

tokens(theme_context, tree, start=0, end=None)[source]

Yield tokens from tree.tokens_range(start, end).

If a context is entered, theme_context.push(language) is called with the language of the context’s lexicon. If the context is left, theme_context.pop() is called.

In Theme, the theme_context argument is unused.

class MetaTheme(theme)[source]

Bases: object

A Theme that encapsulates a default Theme and per-language sub-Themes.

add_theme(language, theme, add_window=False)[source]

Add a specific Theme for the specified Language.

If add_window is set to True, the formatter will render text from the specified language with its own window default style added to all formats. A formatter will also need to take care to render untokenized ranges with the window() style of the sub-theme.

get_theme(language)[source]

Return the tuple(theme, add_window) for the language.

If the exact language was not found, the base classes of the Language are tried. If still no luck, self is returned.

get_add_window(theme)[source]

Return the add_window value that was set when adding this sub-theme.

baseformat(role='window', state='default')[source]

Return the base TextFormat for the rold and state of the default theme.

textformat(action)[source]

Return the TextFormat for the specified action of the default theme.

tokens(theme_context, tree, start=0, end=None)[source]

Yield tokens from tree.tokens_range(start, end).

If a context is entered, theme_context.push(language) is called with the language of the context’s lexicon. If the context is left, theme_context.pop() is called.

The theme_context can switch the theme, based on the current language.

class TextFormat(properties)[source]

Bases: object

Simple textformat that reads CSS properties and supports a subset of those.

This factory is used by default by Theme, but you can implement your own. Such a factory only needs to implement an __init__ method that reads the dictionary of property Value lists returned by Style.properties().

A TextFormat has a False boolean value if no single property is set.

You can add and subtract TextFormats:

>>> import parce
>>> t = parce.theme_by_name()
>>> f = t.window()
>>> f
<TextFormat background_color=Color(r=255, g=255, b=240, a=1.0), color=
Color(r=0, g=0, b=0, a=1.0), font_family=['monospace'], font_size=12,
font_size_unit='pt'>
>>> f2 = t.textformat(parce.Comment)
>>> f2
<TextFormat color=Color(r=105, g=105, b=105, a=1.0), font_family=['serif'],
font_style='italic'>
>>> f + f2
<TextFormat background_color=Color(r=255, g=255, b=240, a=1.0), color=
Color(r=105, g=105, b=105, a=1.0), font_family=['serif'], font_size=12,
font_size_unit='pt', font_style='italic'>
>>> f - f2
<TextFormat background_color=Color(r=255, g=255, b=240, a=1.0), color=
Color(r=0, g=0, b=0, a=1.0), font_family=['monospace'], font_size=12,
font_size_unit='pt'>
>>>

Adding a TextFormat returns a new format with our properties set and then the properties of the other. This is useful when it is not possible to overlay properties with underlying window properties.

Subtracting a TextFormat returns a new format with the properties removed that are the same in the other format. This is useful when properties of a certain action happen to be the same as the underlying window properties; it is not needed to set these again in such cases.

color = None

the foreground color as Color(r, g, b, a) tuple

background_color = None

the background color (id)

text_decoration_color = None

the color for text decoration

text_decoration_line = ()

underline, overline and/or line-through

text_decoration_style = None

solid, double, dotted, dashed or wavy

font_family = ()

family or generic name

font_kerning = None

font kerning

font_size = None

font size

font_size_unit = None

font size unit if given

font_stretch = None

font stretch value (keyword or float, 1.0 is normal)

font_style = None

normal, italic or oblique

font_style_angle = None

oblique slant if given

font_style_angle_unit = None

oblique slant unit if given

font_variant_caps = None

all kind of small caps

font_variant_position = None

normal, sub or super

font_weight = None

100 - 900 or keyword like bold

dispatch(*args, **kwargs)
css_properties()[source]

Return a dict usable to write out a CSS rule with our properties.

write_color()[source]

Yield color and background color as CSS properties, if set.

write_text_decoration()[source]

Yield a text-decoration property, if set.

write_font()[source]

Yield all font-xxxx properties, if set.

read_color(values)[source]
read_background_color(values)[source]
read_background(values)[source]
read_text_decoration_color(values)[source]
read_text_decoration_line(values)[source]
read_text_decoration_style(values)[source]
read_text_decoration(values)[source]
read_font_family(values)[source]
read_font_kerning(values)[source]
read_font_size(values)[source]
read_font_stretch(values)[source]
read_font_style(values)[source]
read_font_variant_caps(values)[source]
read_font_variant_position(values)[source]
read_font_weight(values)[source]
read_font(values)[source]