Package cssutils.css

Classes implementing DOM Level 2 CSS and CSS Module: Namespaces (W3C Working Draft 28 August 2006)

CSSStyleSheet

A CSSStyleSheet contains all rules. It consists of the different CSS rules like CSSImportRule, CSSStyleRule etc. It also defines the encoding of the style sheet used for serialization. The encoding might by set with an CSSCharsetRule rule or simpler with the encoding attribute. The serialized sheet may be obtained from cssText. All rules are present in cssRules, a stylesheet iterates on its rules so this might be easier. Namespaces are available via namespaces (do not rely on prefixes, see http://www.w3.org/TR/REC-xml-names/ how these work). Variables are available via variables which is a CSSVariablesDeclaration and contains all available variables including the ones defined in imported style sheets. Changes to this object do NOT change the parent sheet!

class cssutils.css.CSSStyleSheet(href=None, media=None, title=u'', disabled=None, ownerNode=None, parentStyleSheet=None, readonly=False, ownerRule=None, validating=True)

CSSStyleSheet represents a CSS style sheet.

Format:

stylesheet
  : [ CHARSET_SYM S* STRING S* ';' ]?
    [S|CDO|CDC]* [ import [S|CDO|CDC]* ]*
    [ namespace [S|CDO|CDC]* ]* # according to @namespace WD
    [ [ ruleset | media | page ] [S|CDO|CDC]* ]*
cssRules
All Rules in this style sheet, a CSSRuleList.
add(rule)

Add rule to style sheet at appropriate position. Same as insertRule(rule, inOrder=True).

alternate

Not used in cssutils yet.

cssText

Textual representation of the stylesheet (a byte string).

deleteRule(index)

Delete rule at index from the style sheet.

Parameters:

index

The index of the rule to be removed from the StyleSheet’s rule list. For an index < 0 no IndexSizeErr is raised but rules for normal Python lists are used. E.g. deleteRule(-1) removes the last rule in cssRules.

index may also be a CSSRule object which will then be removed from the StyleSheet.

Exceptions :
  • IndexSizeErr: Raised if the specified index does not correspond to a rule in the style sheet’s rule list.
  • NamespaceErr: Raised if removing this rule would result in an invalid StyleSheet
  • NoModificationAllowedErr: Raised if this style sheet is readonly.
encoding

Encoding set in CSSCharsetRule or if None resulting in default utf-8 encoding being used.

href

If the style sheet is a linked style sheet, the value of this attribute is its location. For inline style sheets, the value of this attribute is None. See the href attribute definition for the LINK element in HTML 4.0, and the href pseudo-attribute for the XML style sheet processing instruction.

insertRule(rule, index=None, inOrder=False, _clean=True)

Used to insert a new rule into the style sheet. The new rule now becomes part of the cascade.

Parameters:
  • rule – a parsable DOMString, in cssutils also a CSSRule or CSSRuleList
  • index – of the rule before the new rule will be inserted. If the specified index is equal to the length of the StyleSheet’s rule collection, the rule will be added to the end of the style sheet. If index is not given or None rule will be appended to rule list.
  • inOrder – if True the rule will be put to a proper location while ignoring index and without raising HierarchyRequestErr. The resulting index is returned nevertheless.
Returns:

The index within the style sheet’s rule collection

Exceptions :
  • HierarchyRequestErr: Raised if the rule cannot be inserted at the specified index e.g. if an @import rule is inserted after a standard rule set or other at-rule.
  • IndexSizeErr: Raised if the specified index is not a valid insertion point.
  • NoModificationAllowedErr: Raised if this style sheet is readonly.
  • SyntaxErr: Raised if the specified rule has a syntax error and is unparsable.
namespaces

All Namespaces used in this CSSStyleSheet.

ownerNode

Not used in cssutils yet.

ownerRule

A ref to an @import rule if it is imported, else None.

parentStyleSheet

For style sheet languages that support the concept of style sheet inclusion, this attribute represents the including style sheet, if one exists. If the style sheet is a top-level style sheet, or the style sheet language does not support inclusion, the value of this attribute is None.

seq

Internal readonly attribute, DO NOT USE!

setSerializer(*args, **kwargs)

Set the cssutils global Serializer used for all output.

setSerializerPref(*args, **kwargs)

Set a Preference of CSSSerializer used for output. See cssutils.serialize.Preferences for possible preferences to be set.

type

This specifies the style sheet language for this style sheet. The style sheet language is specified as a content type (e.g. text/css). The content type is often specified in the ownerNode. Also see the type attribute definition for the LINK element in HTML 4.0, and the type pseudo-attribute for the XML style sheet processing instruction. For CSS this is always text/css.

variables

A cssutils.css.CSSVariablesDeclaration containing all available variables in this CSSStyleSheet including the ones defined in imported sheets.

CSS rules

CSSRule

class cssutils.css.CSSRule(parentRule=None, parentStyleSheet=None, readonly=False)

Abstract base interface for any type of CSS statement. This includes both rule sets and at-rules. An implementation is expected to preserve all rules specified in a CSS style sheet, even if the rule is not recognized by the parser. Unrecognized rules are represented using the CSSUnknownRule interface.

CHARSET_RULE = 2

cssutils.css.CSSCharsetRule (not used in CSSOM anymore)

COMMENT = 1001

cssutils.css.CSSComment - not in the offical spec, Value has changed in 0.9.7a3

FONT_FACE_RULE = 5

cssutils.css.CSSFontFaceRule

IMPORT_RULE = 3

cssutils.css.CSSImportRule

MARGIN_RULE = 1006

cssutils.css.MarginRule - experimental rule not in the offical spec

MEDIA_RULE = 4

cssutils.css.CSSMediaRule

NAMESPACE_RULE = 10

cssutils.css.CSSNamespaceRule, Value has changed in 0.9.7a3 due to a change in the CSSOM spec.

PAGE_RULE = 6

cssutils.css.CSSPageRule

STYLE_RULE = 1

cssutils.css.CSSStyleRule

UNKNOWN_RULE = 0

cssutils.css.CSSUnknownRule (not used in CSSOM anymore)

VARIABLES_RULE = 1008

cssutils.css.CSSVariablesRule - experimental rule not in the offical spec

atkeyword

Normalized keyword of an @rule (e.g. @import).

cssText

(DOM) The parsable textual representation of the rule. This reflects the current state of the rule and not its initial value.

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

seq

Internal readonly attribute, DO NOT USE!

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

wellformed

If the rule is wellformed.

CSSRuleList

class cssutils.css.CSSRuleList(*ignored)

The CSSRuleList object represents an (ordered) list of statements.

The items in the CSSRuleList are accessible via an integral index, starting from 0.

Subclasses a standard Python list so theoretically all standard list methods are available. Setting methods like __init__, append, extend or __setslice__ are added later on instances of this class if so desired. E.g. CSSStyleSheet adds append which is not available in a simple instance of this class!

append(*ignored)

Implemented in class using a CSSRuleList only.

count(value) → integer -- return number of occurrences of value
extend(*ignored)

Implemented in class using a CSSRuleList only.

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

insert()

L.insert(index, object) – insert object before index

item(index)

(DOM) Retrieve a CSS rule by ordinal index. The order in this collection represents the order of the rules in the CSS style sheet. If index is greater than or equal to the number of rules in the list, this returns None.

Returns CSSRule, the style rule at the index position in the CSSRuleList, or None if that is not a valid index.

length

(DOM) The number of CSSRules in the list.

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

rulesOfType(type)

Yield the rules which have the given type only, one of the constants defined in cssutils.css.CSSRule.

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

CSSCharsetRule

class cssutils.css.CSSCharsetRule(encoding=None, parentRule=None, parentStyleSheet=None, readonly=False)

The CSSCharsetRule interface represents an @charset rule in a CSS style sheet. The value of the encoding attribute does not affect the encoding of text data in the DOM objects; this encoding is always UTF-16 (also in Python?). After a stylesheet is loaded, the value of the encoding attribute is the value found in the @charset rule. If there was no @charset in the original document, then no CSSCharsetRule is created. The value of the encoding attribute may also be used as a hint for the encoding used on serialization of the style sheet.

The value of the @charset rule (and therefore of the CSSCharsetRule) may not correspond to the encoding the document actually came in; character encoding information e.g. in an HTTP header, has priority (see CSS document representation) but this is not reflected in the CSSCharsetRule.

This rule is not really needed anymore as setting CSSStyleSheet.encoding is much easier.

Format:

charsetrule:
    CHARSET_SYM S* STRING S* ';'

BUT: Only valid format is (single space, double quotes!):

@charset "ENCODING";
atkeyword

Normalized keyword of an @rule (e.g. @import).

cssText

(DOM) The parsable textual representation.

encoding

(DOM)The encoding information used in this @charset rule.

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

seq

Internal readonly attribute, DO NOT USE!

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

CSSFontFaceRule

class cssutils.css.CSSFontFaceRule(style=None, parentRule=None, parentStyleSheet=None, readonly=False)

The CSSFontFaceRule interface represents a @font-face rule in a CSS style sheet. The @font-face rule is used to hold a set of font descriptions.

Format:

font_face
  : FONT_FACE_SYM S*
    '{' S* declaration [ ';' S* declaration ]* '}' S*
  ;

cssutils uses a CSSStyleDeclaration to represent the font descriptions. For validation a specific profile is used though were some properties have other valid values than when used in e.g. a CSSStyleRule.

atkeyword

Normalized keyword of an @rule (e.g. @import).

cssText

(DOM) The parsable textual representation of this rule.

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

seq

Internal readonly attribute, DO NOT USE!

style

(DOM) The declaration-block of this rule set, a CSSStyleDeclaration.

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

valid

CSSFontFace is valid if properties font-family and src are set and all properties are valid.

CSSImportRule

class cssutils.css.CSSImportRule(href=None, mediaText=None, name=None, parentRule=None, parentStyleSheet=None, readonly=False)

Represents an @import rule within a CSS style sheet. The @import rule is used to import style rules from other style sheets.

Format:

import
  : IMPORT_SYM S*
  [STRING|URI] S* [ medium [ COMMA S* medium]* ]? S* STRING? S* ';' S*
  ;
atkeyword

Normalized keyword of an @rule (e.g. @import).

cssText

(DOM) The parsable textual representation of this rule.

href

Location of the style sheet to be imported.

media

(DOM) A list of media types for this rule of type MediaList.

name

An optional name for the imported sheet.

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

seq

Internal readonly attribute, DO NOT USE!

styleSheet

(readonly) The style sheet referred to by this rule.

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

wellformed

Depending on if media is used at all.

CSSMediaRule

class cssutils.css.CSSMediaRule(mediaText='all', name=None, parentRule=None, parentStyleSheet=None, readonly=False)

Objects implementing the CSSMediaRule interface can be identified by the MEDIA_RULE constant. On these objects the type attribute must return the value of that constant.

Format:

: MEDIA_SYM S* medium [ COMMA S* medium ]* 

    STRING? # the name

LBRACE S* ruleset* '}' S*;
cssRules
All Rules in this media rule, a CSSRuleList.
add(rule)

Add rule to page rule. Same as insertRule(rule).

atkeyword

Normalized keyword of an @rule (e.g. @import).

cssText

(DOM) The parsable textual representation of this rule.

deleteRule(index)

Delete the rule at index from rules cssRules.

Parameters:

index

The index of the rule to be removed from the rules cssRules list. For an index < 0 no IndexSizeErr is raised but rules for normal Python lists are used. E.g. deleteRule(-1) removes the last rule in cssRules.

index may also be a CSSRule object which will then be removed.

Exceptions :
insertRule(rule, index=None)

Implements base insertRule.

media

(DOM) A list of media types for this rule of type MediaList.

name

An optional name for this media rule.

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

seq

Internal readonly attribute, DO NOT USE!

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

CSSNamespaceRule

class cssutils.css.CSSNamespaceRule(namespaceURI=None, prefix=None, cssText=None, parentRule=None, parentStyleSheet=None, readonly=False)

Represents an @namespace rule within a CSS style sheet.

The @namespace at-rule declares a namespace prefix and associates it with a given namespace (a string). This namespace prefix can then be used in namespace-qualified names such as those described in the Selectors Module [SELECT] or the Values and Units module [CSS3VAL].

Dealing with these rules directly is not needed anymore, easier is the use of cssutils.css.CSSStyleSheet.namespaces.

Format:

namespace
  : NAMESPACE_SYM S* [namespace_prefix S*]? [STRING|URI] S* ';' S*
  ;
namespace_prefix
  : IDENT
  ;
atkeyword

Normalized keyword of an @rule (e.g. @import).

cssText

(DOM) The parsable textual representation of this rule.

namespaceURI

URI (handled as simple string) of the defined namespace.

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

prefix

Prefix used for the defined namespace.

seq

Internal readonly attribute, DO NOT USE!

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

CSSPageRule

class cssutils.css.CSSPageRule(selectorText=None, style=None, parentRule=None, parentStyleSheet=None, readonly=False)

The CSSPageRule interface represents a @page rule within a CSS style sheet. The @page rule is used to specify the dimensions, orientation, margins, etc. of a page box for paged media.

Format:

page :
       PAGE_SYM S* IDENT? pseudo_page? S* 
       '{' S* [ declaration | margin ]? [ ';' S* [ declaration | margin ]? ]* '}' S*
       ;

pseudo_page :
       ':' [ "left" | "right" | "first" ]
       ;

margin :
       margin_sym S* '{' declaration [ ';' S* declaration? ]* '}' S*
       ;

margin_sym :
       TOPLEFTCORNER_SYM | 
       TOPLEFT_SYM | 
       TOPCENTER_SYM | 
       TOPRIGHT_SYM | 
       TOPRIGHTCORNER_SYM |
       BOTTOMLEFTCORNER_SYM | 
       BOTTOMLEFT_SYM | 
       BOTTOMCENTER_SYM | 
       BOTTOMRIGHT_SYM |
       BOTTOMRIGHTCORNER_SYM |
       LEFTTOP_SYM |
       LEFTMIDDLE_SYM |
       LEFTBOTTOM_SYM |
       RIGHTTOP_SYM |
       RIGHTMIDDLE_SYM |
       RIGHTBOTTOM_SYM 
       ;

cssRules contains a list of MarginRule objects.

add(rule)

Add rule to page rule. Same as insertRule(rule).

atkeyword

Normalized keyword of an @rule (e.g. @import).

cssText

(DOM) The parsable textual representation of this rule.

deleteRule(index)

Delete the rule at index from rules cssRules.

Parameters:

index

The index of the rule to be removed from the rules cssRules list. For an index < 0 no IndexSizeErr is raised but rules for normal Python lists are used. E.g. deleteRule(-1) removes the last rule in cssRules.

index may also be a CSSRule object which will then be removed.

Exceptions :
insertRule(rule, index=None)

Implements base insertRule.

keys()

Return list of all set margins (MarginRule).

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

selectorText

(DOM) The parsable textual representation of the page selector for the rule.

seq

Internal readonly attribute, DO NOT USE!

specificity

Specificity of this page rule (READONLY). Tuple of (f, g, h) where:

  • if the page selector has a named page, f=1; else f=0
  • if the page selector has a ‘:first’ pseudo-class, g=1; else g=0
  • if the page selector has a ‘:left’ or ‘:right’ pseudo-class, h=1; else h=0
style

(DOM) The declaration-block of this rule set, a CSSStyleDeclaration.

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

MarginRule

class cssutils.css.MarginRule(margin=None, style=None, parentRule=None, parentStyleSheet=None, readonly=False)

A margin at-rule consists of an ATKEYWORD that identifies the margin box (e.g. '@top-left‘) and a block of declarations (said to be in the margin context).

Format:

margin :
       margin_sym S* '{' declaration [ ';' S* declaration? ]* '}' S*
       ;

margin_sym :
       TOPLEFTCORNER_SYM | 
       TOPLEFT_SYM | 
       TOPCENTER_SYM | 
       TOPRIGHT_SYM | 
       TOPRIGHTCORNER_SYM |
       BOTTOMLEFTCORNER_SYM | 
       BOTTOMLEFT_SYM | 
       BOTTOMCENTER_SYM | 
       BOTTOMRIGHT_SYM |
       BOTTOMRIGHTCORNER_SYM |
       LEFTTOP_SYM |
       LEFTMIDDLE_SYM |
       LEFTBOTTOM_SYM |
       RIGHTTOP_SYM |
       RIGHTMIDDLE_SYM |
       RIGHTBOTTOM_SYM 
       ;

e.g.:

@top-left {
    content: "123";
    }
atkeyword

Margin area of parent CSSPageRule. margin and atkeyword are both normalized @keyword of the @rule.

cssText

(DOM) The parsable textual representation.

margin

Margin area of parent CSSPageRule. margin and atkeyword are both normalized @keyword of the @rule.

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

seq

Internal readonly attribute, DO NOT USE!

style

(DOM) The declaration-block of this rule set.

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

CSSStyleRule

class cssutils.css.CSSStyleRule(selectorText=None, style=None, parentRule=None, parentStyleSheet=None, readonly=False)

The CSSStyleRule object represents a ruleset specified (if any) in a CSS style sheet. It provides access to a declaration block as well as to the associated group of selectors.

Format:

: selector [ COMMA S* selector ]*
LBRACE S* declaration [ ';' S* declaration ]* '}' S*
;
atkeyword

Normalized keyword of an @rule (e.g. @import).

cssText

(DOM) The parsable textual representation of this rule.

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

selectorList

The SelectorList of this rule.

selectorText

(DOM) The textual representation of the selector for the rule set.

seq

Internal readonly attribute, DO NOT USE!

style

(DOM) The declaration-block of this rule set.

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

CSSVariablesRule

class cssutils.css.CSSVariablesRule(mediaText=None, variables=None, parentRule=None, parentStyleSheet=None, readonly=False)

The CSSVariablesRule interface represents a @variables rule within a CSS style sheet. The @variables rule is used to specify variables.

cssutils uses a CSSVariablesDeclaration to represent the variables.

Format:

variables
    VARIABLES_SYM S* medium [ COMMA S* medium ]* LBRACE S* 
    variableset* '}' S*
    ;

for variableset see cssutils.css.CSSVariablesDeclaration

Media are not implemented. Reason is that cssutils is using CSS variables in a kind of preprocessing and therefor no media information is available at this stage. For now do not use media!

Example:

@variables {
  CorporateLogoBGColor: #fe8d12;
}

div.logoContainer {
  background-color: var(CorporateLogoBGColor);
}
atkeyword

Normalized keyword of an @rule (e.g. @import).

cssText

(DOM) The parsable textual representation of this rule.

media

NOT IMPLEMENTED! As cssutils resolves variables during serializing media information is lost.

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

seq

Internal readonly attribute, DO NOT USE!

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

valid

NOT IMPLEMTED REALLY (TODO)

variables

(DOM) The variables of this rule set, a cssutils.css.CSSVariablesDeclaration.

CSSComment

class cssutils.css.CSSComment(cssText=None, parentRule=None, parentStyleSheet=None, readonly=False)

Represents a CSS comment (cssutils only).

Format:

/*...*/
atkeyword

Normalized keyword of an @rule (e.g. @import).

cssText

The parsable textual representation of this rule.

parent

The Parent Node of this CSSRule or None.

parentRule

If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns None.

parentStyleSheet

The style sheet that contains this rule.

seq

Internal readonly attribute, DO NOT USE!

type

The type of this rule, as defined by a CSSRule type constant.

typeString

Descriptive name of this rule’s type.

Additional Info

Some classes in this package support standard Python idioms like iteration on certain attributes:

>>> import cssutils
>>> sheet = cssutils.css.CSSStyleSheet()
>>> sheet.cssText = '@charset "ascii";a { color: green }'
>>> for rule in sheet:
...     print rule
...
<cssutils.css.CSSCharsetRule object encoding='ascii' at 0x2ce7
<cssutils.css.CSSStyleRule object selector=u'a' style=u'color:
s=<cssutils.util._Namespaces object at 0x02CE7B30> at 0x2ce7d3

for in is supported by CSSStyleSheet and CSSMediaRule (iterating over the contained CSSRule objects, CSSStyleDeclaration (over the names of the contained Property objects), CSSValueList (over the CSSValue objects in the list).