0
# CSS Parsing
1

2
Comprehensive CSS parsing capabilities supporting CSS 2.1, CSS3 modules, and real-world CSS variations. Parse CSS from strings, files, URLs, and style attributes with configurable validation and error handling.
3

4
## Capabilities
5

6
### CSSParser Class
7

8
Main parser class providing full control over parsing behavior, validation, and error handling.
9

10
```python { .api }
11
class CSSParser:
12
    """
13
    Parse CSS StyleSheets from various sources with configurable options.
14
    
15
    Constructor:
16
    CSSParser(log=None, loglevel=None, raiseExceptions=None, fetcher=None, 
17
              parseComments=True, validate=True)
18
              
19
    Parameters:
20
    - log: Custom logging object for parse messages
21
    - loglevel: Logging level for parse operations  
22
    - raiseExceptions: Whether to raise exceptions during parsing (default: log only)
23
    - fetcher: Custom URL fetcher function for @import resolution
24
    - parseComments: Whether to include CSS comments in DOM (default: True)
25
    - validate: Whether to validate CSS during parsing (default: True)
26
    """
27
    
28
    def parseString(self, cssText, encoding=None, href=None, media=None, title=None, validate=None):
29
        """
30
        Parse CSS from string.
31
        
32
        Parameters:
33
        - cssText (str): CSS source code to parse
34
        - encoding (str): Character encoding (default: detect or utf-8)
35
        - href (str): Base URL for resolving relative URLs
36
        - media (str/MediaList): Media query list for stylesheet
37
        - title (str): Advisory title for stylesheet
38
        - validate (bool): Override parser validation setting
39
        
40
        Returns:
41
        CSSStyleSheet: Parsed stylesheet object
42
        """
43
        
44
    def parseFile(self, filename, encoding=None, href=None, media=None, title=None, validate=None):
45
        """
46
        Parse CSS from file.
47
        
48
        Parameters:
49
        - filename (str): Path to CSS file
50
        - encoding (str): Character encoding (default: detect from file)
51
        - href (str): Base URL for resolving relative URLs (default: file URL)
52
        - media (str/MediaList): Media query list for stylesheet
53
        - title (str): Advisory title for stylesheet
54
        - validate (bool): Override parser validation setting
55
        
56
        Returns:
57
        CSSStyleSheet: Parsed stylesheet object
58
        """
59
        
60
    def parseUrl(self, href, encoding=None, media=None, title=None, validate=None):
61
        """
62
        Parse CSS from URL.
63
        
64
        Parameters:
65
        - href (str): URL of CSS resource to fetch and parse
66
        - encoding (str): Character encoding (default: detect from HTTP headers)
67
        - media (str/MediaList): Media query list for stylesheet
68
        - title (str): Advisory title for stylesheet
69
        - validate (bool): Override parser validation setting
70
        
71
        Returns:
72
        CSSStyleSheet: Parsed stylesheet object
73
        """
74
        
75
    def parseStyle(self, cssText, encoding='utf-8', validate=None):
76
        """
77
        Parse CSS style attribute content (property declarations only).
78
        
79
        Parameters:
80
        - cssText (str): CSS style attribute content
81
        - encoding (str): Character encoding (default: utf-8)
82
        - validate (bool): Override parser validation setting
83
        
84
        Returns:
85
        CSSStyleDeclaration: Parsed style declaration object
86
        """
87
        
88
    def setFetcher(self, fetcher=None):
89
        """
90
        Set custom URL fetcher function for resolving @import and url() references.
91
        
92
        Parameters:
93
        - fetcher (callable): Function that takes URL and returns (encoding, content) tuple
94
                             If None, uses default urllib-based fetcher
95
        """
96
```
97

98
### Convenience Parse Functions
99

100
High-level parsing functions using the default global CSSParser instance.
101

102
```python { .api }
103
def parseString(cssText, encoding=None, href=None, media=None, title=None, validate=None):
104
    """
105
    Parse CSS string using default parser.
106
    
107
    Parameters:
108
    - cssText (str): CSS source code to parse
109
    - encoding (str): Character encoding
110
    - href (str): Base URL for resolving relative URLs
111
    - media (str/MediaList): Media query list
112
    - title (str): Advisory title
113
    - validate (bool): Whether to validate CSS
114
    
115
    Returns:
116
    CSSStyleSheet: Parsed stylesheet object
117
    """
118

119
def parseFile(filename, encoding=None, href=None, media=None, title=None, validate=None):
120
    """
121
    Parse CSS file using default parser.
122
    
123
    Parameters:
124
    - filename (str): Path to CSS file
125
    - encoding (str): Character encoding
126
    - href (str): Base URL for resolving relative URLs
127
    - media (str/MediaList): Media query list
128
    - title (str): Advisory title
129
    - validate (bool): Whether to validate CSS
130
    
131
    Returns:
132
    CSSStyleSheet: Parsed stylesheet object
133
    """
134

135
def parseUrl(href, encoding=None, media=None, title=None, validate=None):
136
    """
137
    Parse CSS from URL using default parser.
138
    
139
    Parameters:
140
    - href (str): URL of CSS resource
141
    - encoding (str): Character encoding
142
    - media (str/MediaList): Media query list
143
    - title (str): Advisory title
144
    - validate (bool): Whether to validate CSS
145
    
146
    Returns:
147
    CSSStyleSheet: Parsed stylesheet object
148
    """
149

150
def parseStyle(cssText, encoding='utf-8', validate=None):
151
    """
152
    Parse CSS style attribute using default parser.
153
    
154
    Parameters:
155
    - cssText (str): CSS style attribute content
156
    - encoding (str): Character encoding
157
    - validate (bool): Whether to validate CSS
158
    
159
    Returns:
160
    CSSStyleDeclaration: Parsed style declaration object
161
    """
162
```
163

164
## Usage Examples
165

166
### Basic Parsing
167

168
```python
169
import cssutils
170

171
# Parse from string
172
css = "body { color: red; font-size: 14px; }"
173
stylesheet = cssutils.parseString(css)
174

175
# Parse from file
176
stylesheet = cssutils.parseFile('styles.css')
177

178
# Parse from URL
179
stylesheet = cssutils.parseUrl('http://example.com/styles.css')
180

181
# Parse style attribute
182
style = cssutils.parseStyle('color: blue; margin: 10px')
183
```
184

185
### Advanced Parser Configuration
186

187
```python
188
import cssutils
189
import logging
190

191
# Create custom parser with logging
192
parser = cssutils.CSSParser(
193
    loglevel=logging.WARNING,
194
    raiseExceptions=False,
195
    parseComments=True,
196
    validate=True
197
)
198

199
# Custom URL fetcher for @import resolution
200
def custom_fetcher(url):
201
    # Custom logic to fetch URLs
202
    import urllib2
203
    response = urllib2.urlopen(url)
204
    encoding = response.headers.get('charset', 'utf-8')
205
    content = response.read()
206
    return encoding, content
207

208
parser.setFetcher(custom_fetcher)
209

210
# Parse with custom configuration
211
stylesheet = parser.parseString(css_text, 
212
                               href='http://example.com/base/',
213
                               media='screen, print',
214
                               title='Main Stylesheet')
215
```
216

217
### Error Handling
218

219
```python
220
import cssutils
221

222
# Configure parser to raise exceptions
223
parser = cssutils.CSSParser(raiseExceptions=True)
224

225
try:
226
    # This will raise an exception for invalid CSS
227
    stylesheet = parser.parseString('invalid { css syntax }')
228
except xml.dom.SyntaxErr as e:
229
    print(f"CSS parsing error: {e}")
230

231
# Or use logging mode (default)
232
parser = cssutils.CSSParser(raiseExceptions=False)
233
stylesheet = parser.parseString('invalid { css syntax }')
234
# Errors logged but parsing continues with recoverable portions
235
```
236

237
### Encoding Handling
238

239
```python
240
import cssutils
241

242
# Explicit encoding
243
stylesheet = cssutils.parseString(css_bytes, encoding='utf-8')
244

245
# Auto-detection from @charset rule
246
css_with_charset = '@charset "iso-8859-1"; body { color: red; }'
247
stylesheet = cssutils.parseString(css_with_charset)  # encoding detected
248

249
# File with BOM or encoding detection
250
stylesheet = cssutils.parseFile('styles.css')  # encoding auto-detected
251
```