A CSS parser.

We also use this parser inside parce, to be able to store default highlighting formats in css files.

class Css[source]

Bases: parce.language.Language

classmethod toplevel()[source]
classmethod selectors()[source]

Yield selectors, used in prelude and selector_list.


The list of selectors in :is(bla, bla), etc.


Declarations of a qualified rule between { and }.


CSS that would be in a rule block, but also in a HTML style attribute.


A property: value; declaration.

classmethod common()[source]

Stuff that can be everywhere.


Unit directly after a number, e.g. the px in 100px, also %.

classmethod identifier_common(action)[source]

Yield an ident-token and give it the specified action.


A tag name used as selector.


A CSS property.


An attribute name.






Stuff between [ and ].


Things like :first-child etc.


Things like ::first-letter etc.


Contents following ‘@’.


An atrule that has nested toplevel contents (@media, etc.)


The first identifier word in an @-rule.


a { } block from an @-rule.


a { } block from @media, @document or @supports.

classmethod atrule_common()[source]

Common stuff inside @-rules.


An ident-token where quoted or unquoted text is allowed.


An ident-token that could be a color or a function().


Contents between identifier( … ).




A double-quoted string.


A single-quoted string.

classmethod string()[source]

Common rules for string.


A comment.

class CssTransform[source]

Bases: parce.transform.Transform

Transform a CSS stylesheet into a simpler data structure.

The data structure created by this Transform only contains plain Python strings, lists, (named) tuples, dictionaries and Value objects. Value represents any item from a property value list. Most notably, a CSS color (hexadecimal, named or via the CSS rgb()/rgba() functions) is converted to a named Color four-tuple.

A tree created by the Css.root lexicon becomes a list of tuples that are either a Rule or an Atrule named tuple.

An Atrule named tuple corresponds to an @-rule and consists of three items, the keyword which contains the name, the contents, which contains all items after the name, and the block which contains the part between { and }.

There are three at-rule types:

  1. Nested at-rule: the keyword is either "media", "supports" or "document", the contents contains the query strings and Value instances; the block contains the list of nested Rule/Atrule tuples.

  2. At-rules with a properties block, like @page:left { ... }: the keyword can be anything, the block is a dictionary of properties like the properties dictionary of a normal Rule (see below). The contents contains the stuff between the block and the initial keyword.

  3. At-rules without a block; like @import url("filename.css");, the block is None for these at-rules.

A Rule named tuple corresponds to a normal CSS rule and consists of two items, the prelude, which contains the selectors, and the properties dictionary.

The prelude is a list of selector groups. Each selector group is also a list, containing at least one selector dictionary and optionally operator strings and more selector dictionaries. See the prelude() method.

The properties is a dictionary mapping property names to lists of Value instances. A Value can express any CSS property value, like a quoted string, unquoted name, number with or without unit, url, etc. It also recognizes named, rgb/rgba and hexadecimal colors, which can be found as a Color tuple in the Value.color attribute. It does not yet parse calc() function calls.

For example:

>>> from parce import root
>>> from parce.transform import transform_tree
>>> from parce.lang.css import Css
>>> transform_tree(root(Css.root, 'h1 { color: red; }'))
[Rule(prelude=[[{'element_selector': ['h1']}]], properties={'color':
[<Value text='red', color=Color(r=255, g=0, b=0, a=1.0)>]})]

Return a list of Rule or Atrule tuples.


Return a Css prelude.

A prelude is a list of selector lists. A Css prelude that contains a comma has more than one selector lists.

A selector list is a list of selector dictionaries with possible combinator operators in between. The operators can be: " " (space), ">", "~", "+", or "||".

Every selector is a dictionary, and inbetween are operator strings. A comma in the selector causes the prelude to contain more than one list. Every selector list consists of selector dicts with an operator or whitespace in between.


Return a dictionary object.

The possible keys are: “element_selector”, “id_selector”, “class_selector”, “pseudo_class”, “pseudo_element”, “attribute_selector”.

If present, the value is a list of objects created by that context. Most objects are simple strings, but for pseudo_class it is a (name, selector_list) tuple, and for attribute_selector it is a four-tuple of the contents between the [ and ].

“*” is ignored, ‘|’ is not yet handled.


Stuff inside :not(), :is(), etc.


A Css rule, between { … }.


Return a dictionary of the property values.


Return a two-tuple(property, value).

The value is a list of Value instances from common().


Return the name of the unit in itens.


Return the name of the element_selector.


Return the name of the property.


Return the name of the attribute.


Return the name of the id_selector.


Return the name of the class_selector.


Return a four-tuple representing the contents between [ and ].

The tuple: (attribute, operator, value, flag).


Return a tuple(name, selector_list).

The name is the name of the pseudo class, the selector_list is a list of selectors like the prelude of a rule. For pseudo classes without arguments, the selector_list is None.


Return the name of the pseudo element.


Return a Atrule named tuple.


Return a two-tuple: the stuff before the nested block and the nested block.


Return the name of the atrule keyword.


Return the properties dict in an atrule block.


Return a list of Rule or Atrule tuples.


Return the ident_token.


Return a Value.

For a color name, returns a Value with a color, otherwise a Value with the text.

If the identifier also has a function sub-context, a Value representing a function call is returned (this is done by the get_css_function_call() function, which is capable of interpreting url, rgb and rgba function calls).


Return a list of Value instances and delimiting tokens.


Return a Value with the url.


Return the contents of a double-quoted string.


Return the contents of a single-quoted string.

comment = None

Yield any values, see Css.common().

Every item is either a Value instance or a delimiting token. If an identifier context is followed by a function context, they are combined into a Value with funcname and arguments by the get_css_function_call() method.

get_css_function_call(name, arguments)[source]

Return a Value for a CSS function call. Handles rgb/rgba.


Get the value of a Number.


Get the value of escaped text.


Yield the parts of a string.

Called by sqstring() and dqstring().


Return a two-tuple(name, action).

Combines tokens in an identifier context, (see Css.identifier_common()).


Return a named four-tuple Color(r, g, b, a) describing color and alpha.

The text is a hexadecimal color without the hash, like “FA0042”. The r, g, b values are in the range 0..255, a in 0..1; 1.0 is fully opaque.


Return a named four-tuple Color(r, g, b, a) describing color and alpha.

The text is a CSS3 color name. The r, g, b values are in the range 0..255, a in 0..1; 1.0 is fully opaque.


Convert the arguments to a rgba(1 2 3 4) call to a Color.

get_number_value(value, maximum)[source]

Return a numeric value from the Value object.

If the value object has a percentage, apply it so 100% yields the maximum value. Otherwise, the number is constrained to be in the 0..maximum range.

class Atrule(keyword, contents, block)

Bases: tuple

An at-rule. For nested atrules the nested stylesheet is in a list block, for other at-rules that end with a rule with properties, the properties dict is in block; when there is no block, block is None.

property block

Alias for field number 2

property contents

Alias for field number 1

property keyword

Alias for field number 0

class Rule(prelude, properties)

Bases: tuple

A normal rule

property prelude

Alias for field number 0

property properties

Alias for field number 1

class Color(r, g, b, a)

Bases: tuple

A named tuple holding the (r, g, b, a) value of a color.

property a

Alias for field number 3

property b

Alias for field number 2

property g

Alias for field number 1

property r

Alias for field number 0

class Value(text=None, number=None, unit=None, url=None, color=None, funcname=None, quoted=None, arguments=())[source]

Bases: object

Any value that can occur in a CSS property declaration.

The value of a CSS property is always a list of Value instances.

For a numerial value, the number attribute contains the numeric value, and the text attribute the textual representation as present in the CSS file. A unit (or “%”) that was specified, is in the unit attribute.

For a color value, the color is in the color attribute as a Color four-tuple. When a CSS3 named color was specified, the name of the color is in the text attribute, or when a hexadecimal color was specified, the hexadecimal notation is also in the text attribute.

For a value that can either be a quoted string or an ident_token, the value is in the text attribute. If it originally was a quoted string, the quoted attribute is set to True.

If the value represents a URL specified via the url() function, the URL is in the url attribute.

If the value represents a function call, the name of the function is in the funcname attribute, and the argument list in the arguments attribute. Except for the url(), the rgb() and rgba() functions, which are handled by the CssTransform class.


Root lexicon Css.root and text:

/* css example */
h1.main {
    color: red;
    background: grey url(bla.png);

Result tree:

<Context Css.root at 0-80 (4 children)>
 ├╴<Token '/*' at 0:2 (Comment)>
 ├╴<Context Css.comment at 2-17 (2 children)>
 │  ├╴<Token ' css example ' at 2:15 (Comment)>
 │  ╰╴<Token '*/' at 15:17 (Comment)>
 ├╴<Context Css.prelude at 18-27 (2 children)>
 │  ├╴<Context Css.selector at 18-25 (3 children)>
 │  │  ├╴<Context Css.element_selector at 18-20 (1 child)>
 │  │  │  ╰╴<Token 'h1' at 18:20 (Name.Tag)>
 │  │  ├╴<Token '.' at 20:21 (Keyword)>
 │  │  ╰╴<Context Css.class_selector at 21-25 (1 child)>
 │  │     ╰╴<Token 'main' at 21:25 (Name.Class)>
 │  ╰╴<Token '{' at 26:27 (Delimiter.Bracket)>
 ╰╴<Context Css.rule at 32-80 (3 children)>
    ├╴<Context Css.declaration at 32-43 (4 children)>
    │  ├╴<Context Css.property at 32-37 (1 child)>
    │  │  ╰╴<Token 'color' at 32:37 (Name.Property.Definition)>
    │  ├╴<Token ':' at 37:38 (Delimiter)>
    │  ├╴<Context Css.identifier at 39-42 (1 child)>
    │  │  ╰╴<Token 'red' at 39:42 (Literal.Color)>
    │  ╰╴<Token ';' at 42:43 (Delimiter)>
    ├╴<Context Css.declaration at 48-78 (7 children)>
    │  ├╴<Context Css.property at 48-58 (1 child)>
    │  │  ╰╴<Token 'background' at 48:58 (Name.Property.Definition)>
    │  ├╴<Token ':' at 58:59 (Delimiter)>
    │  ├╴<Context Css.identifier at 60-64 (1 child)>
    │  │  ╰╴<Token 'grey' at 60:64 (Literal.Color)>
    │  ├╴<Token 'url' at 65:68 (Name)>
    │  ├╴<Token '(' at 68:69 (Delimiter)>
    │  ├╴<Context Css.url_function at 69-77 (2 children)>
    │  │  ├╴<Token 'bla.png' at 69:76 (Literal.Url)>
    │  │  ╰╴<Token ')' at 76:77 (Delimiter)>
    │  ╰╴<Token ';' at 77:78 (Delimiter)>
    ╰╴<Token '}' at 79:80 (Delimiter.Bracket)>