0
# cssutils
1

2
A comprehensive CSS Cascading Style Sheets library for Python that implements DOM Level 2 Style specifications. cssutils enables parsing, manipulation, and generation of CSS stylesheets with complete CSS 2.1 and CSS3 module support.
3

4
## Package Information
5

6
- **Package Name**: cssutils
7
- **Language**: Python
8
- **Installation**: `pip install cssutils`
9
- **Version**: 1.0.2
10
- **License**: LGPL 3.0
11

12
## Core Imports
13

14
```python
15
import cssutils
16
```
17

18
Common imports for CSS parsing and manipulation:
19

20
```python
21
from cssutils import CSSParser, CSSSerializer
22
```
23

24
Access CSS classes through the css module:
25

26
```python
27
import cssutils.css as css
28
# Then use: css.CSSStyleSheet, css.CSSStyleRule, css.CSSStyleDeclaration
29
```
30

31
Import all main functionality:
32

33
```python
34
from cssutils import *
35
# Imports: css, stylesheets, CSSParser, CSSSerializer
36
```
37

38
## Basic Usage
39

40
```python
41
import cssutils
42

43
# Parse CSS from string
44
css_text = """
45
a {
46
    color: red;
47
    font-weight: bold;
48
}
49
"""
50

51
# Using convenience function
52
stylesheet = cssutils.parseString(css_text)
53
print(stylesheet.cssText)
54

55
# Using CSSParser directly
56
parser = cssutils.CSSParser()
57
stylesheet = parser.parseString(css_text)
58

59
# Access and modify rules
60
for rule in stylesheet:
61
    if rule.type == rule.STYLE_RULE:
62
        print(f"Selector: {rule.selectorText}")
63
        print(f"Properties: {rule.style.cssText}")
64
        
65
        # Modify properties
66
        rule.style.color = 'blue'
67
        rule.style.setProperty('background-color', 'yellow')
68

69
# Serialize back to CSS
70
print(stylesheet.cssText)
71
```
72

73
## Architecture
74

75
cssutils implements the DOM Level 2 CSS specification with the following key components:
76

77
- **CSSStyleSheet**: Top-level container for CSS rules and stylesheet metadata
78
- **CSS Rules**: Complete hierarchy of CSS rule types (@import, @media, style rules, etc.)
79
- **CSSStyleDeclaration**: Container for CSS property declarations within rules
80
- **Values**: Structured representation of CSS property values with type-specific handling
81
- **Selectors**: Parser and representation for CSS selectors
82
- **CSSParser**: Configurable parser for CSS strings, files, and URLs
83
- **CSSSerializer**: Customizable serializer for converting CSS objects back to text
84

85
The library provides both high-level convenience functions and low-level DOM access, enabling use cases from simple CSS processing to complex stylesheet manipulation and validation.
86

87
## Capabilities
88

89
### CSS Parsing
90

91
Parse CSS from strings, files, and URLs with comprehensive error handling and validation. Support for CSS 2.1, CSS3 modules, and real-world CSS variations.
92

93
```python { .api }
94
def parseString(cssText, encoding=None, href=None, media=None, title=None, validate=None):
95
    """Parse CSS from string"""
96
    
97
def parseFile(filename, encoding=None, href=None, media=None, title=None, validate=None):
98
    """Parse CSS from file"""
99
    
100
def parseUrl(href, encoding=None, media=None, title=None, validate=None):
101
    """Parse CSS from URL"""
102
    
103
def parseStyle(cssText, encoding='utf-8', validate=None):
104
    """Parse CSS style attribute"""
105
```
106

107
[CSS Parsing](./parsing.md)
108

109
### CSS Stylesheets
110

111
Create, manipulate, and manage CSS stylesheets with full DOM Level 2 compliance. Handle rules, namespaces, media queries, and variables.
112

113
```python { .api }
114
class CSSStyleSheet:
115
    """Complete CSS stylesheet representation"""
116
    cssRules: CSSRuleList
117
    media: MediaList
118
    href: str
119
    title: str
120
    
121
    def insertRule(rule, index): ...
122
    def deleteRule(index): ...
123
    def add(rule): ...
124
```
125

126
[CSS Stylesheets](./stylesheets.md)
127

128
### CSS Rules
129

130
Complete implementation of all CSS rule types including style rules, @-rules, and nested structures with proper inheritance and containment.
131

132
```python { .api }
133
class CSSStyleRule:
134
    """CSS style rule (selector + declarations)"""
135
    selectorText: str
136
    style: CSSStyleDeclaration
137
    
138
class CSSMediaRule:
139
    """@media rule with nested rules"""
140
    media: MediaList
141
    cssRules: CSSRuleList
142
    
143
class CSSImportRule:
144
    """@import rule"""
145
    href: str
146
    media: MediaList
147
    styleSheet: CSSStyleSheet
148
```
149

150
[CSS Rules](./css-rules.md)
151

152
### CSS Selectors
153

154
Parse, validate, and manipulate CSS selectors with support for CSS3 selector syntax and pseudo-classes.
155

156
```python { .api }
157
class Selector:
158
    """Individual CSS selector"""
159
    selectorText: str
160
    specificity: tuple
161
    
162
class SelectorList:
163
    """List of CSS selectors"""
164
    selectorText: str
165
    
166
    def appendSelector(selector): ...
167
```
168

169
[CSS Selectors](./selectors.md)
170

171
### Style Declarations
172

173
Manage CSS property declarations with validation, shorthand expansion, and value parsing.
174

175
```python { .api }
176
class CSSStyleDeclaration:
177
    """CSS property declarations container"""
178
    cssText: str
179
    length: int
180
    
181
    def getPropertyValue(propertyName): ...
182
    def setProperty(propertyName, value, priority=''): ...
183
    def removeProperty(propertyName): ...
184
    def getProperties(all=False): ...
185
```
186

187
[Style Declarations](./style-declarations.md)
188

189
### CSS Serialization
190

191
Convert CSS objects back to formatted CSS text with extensive customization options for output formatting.
192

193
```python { .api }
194
class CSSSerializer:
195
    """CSS serialization with formatting control"""
196
    prefs: Preferences
197
    
198
    def do_CSSStyleSheet(stylesheet): ...
199
    def do_CSSStyleRule(rule): ...
200
    def do_css_CSSStyleDeclaration(style): ...
201
```
202

203
[CSS Serialization](./serialization.md)
204

205
### Utility Functions
206

207
Helper functions for CSS processing, URL handling, import resolution, and stylesheet manipulation.
208

209
```python { .api }
210
def getUrls(sheet):
211
    """Generator yielding all URLs in stylesheet"""
212
    
213
def replaceUrls(sheetOrStyle, replacer, ignoreImportRules=False):
214
    """Replace URLs in stylesheet or style"""
215
    
216
def resolveImports(sheet, target=None):
217
    """Recursively resolve @import rules"""
218
    
219
def setSerializer(serializer):
220
    """Set global serializer"""
221
```
222

223
[Utility Functions](./utilities.md)
224

225
### Command Line Tools
226

227
Console scripts for CSS processing and manipulation from the command line.
228

229
```python { .api }
230
# Installed as console scripts via pip install cssutils
231

232
cssparse   # Parse and format CSS files
233
csscombine # Combine CSS files by resolving @import rules  
234
csscapture # Capture CSS from web pages
235
```
236

237
### Global Configuration
238

239
Global objects for controlling cssutils behavior across all parsing and serialization operations.
240

241
```python { .api }
242
cssutils.log       # Global error handler (ErrorHandler instance)
243
cssutils.ser       # Global serializer (CSSSerializer instance)  
244
cssutils.profile   # Global validation profiles (Profiles instance)
245
cssutils.VERSION   # Package version string
246
```