0
# CSS Rules
1

2
Complete implementation of CSS rule types including style rules, @-rules, and nested structures. All rules implement DOM Level 2 CSS interfaces with proper inheritance and containment.
3

4
## Capabilities
5

6
### CSSRule Base Class
7

8
Base class for all CSS rules providing common properties and methods.
9

10
```python { .api }
11
class CSSRule:
12
    """
13
    Base class for all CSS rules implementing DOM Level 2 CSSRule interface.
14
    """
15
    
16
    # Rule Type Constants
17
    UNKNOWN_RULE = 0
18
    STYLE_RULE = 1
19
    CHARSET_RULE = 2
20
    IMPORT_RULE = 3
21
    MEDIA_RULE = 4
22
    FONT_FACE_RULE = 5
23
    PAGE_RULE = 6
24
    NAMESPACE_RULE = 10
25
    MARGIN_RULE = 1006     # cssutils extension
26
    COMMENT = 1001         # cssutils extension
27
    VARIABLES_RULE = 1008  # cssutils extension
28
    
29
    # Properties
30
    type: int                    # Rule type constant
31
    cssText: str                # Complete CSS text of rule
32
    parentRule: 'CSSRule'       # Parent rule (for nested rules)
33
    parentStyleSheet: 'CSSStyleSheet'  # Containing stylesheet
34
```
35

36
### CSSStyleRule Class
37

38
Standard CSS style rule with selector and property declarations.
39

40
```python { .api }
41
class CSSStyleRule:
42
    """
43
    CSS style rule (selector { declarations }) implementing DOM Level 2 CSSStyleRule.
44
    """
45
    
46
    # Properties
47
    selectorText: str                      # Selector text
48
    style: 'CSSStyleDeclaration'          # Property declarations
49
    
50
    # Methods
51
    @property
52
    def selectorText():
53
        """Get/set selector text"""
54
    
55
    @selectorText.setter
56
    def selectorText(selectorText):
57
        """Set selector text with parsing and validation"""
58
```
59

60
### CSSCharsetRule Class
61

62
@charset rule specifying character encoding.
63

64
```python { .api }
65
class CSSCharsetRule:
66
    """
67
    @charset rule implementing DOM Level 2 CSSCharsetRule.
68
    """
69
    
70
    # Properties
71
    encoding: str  # Character encoding name
72
    
73
    # Methods
74
    @property
75
    def encoding():
76
        """Get/set character encoding"""
77
    
78
    @encoding.setter 
79
    def encoding(encoding):
80
        """Set character encoding with validation"""
81
```
82

83
### CSSImportRule Class
84

85
@import rule for importing external stylesheets.
86

87
```python { .api }
88
class CSSImportRule:
89
    """
90
    @import rule implementing DOM Level 2 CSSImportRule.
91
    """
92
    
93
    # Properties
94
    href: str                    # URL of imported stylesheet
95
    media: 'MediaList'          # Media query list
96
    styleSheet: 'CSSStyleSheet' # Imported stylesheet (if loaded)
97
    hrefFound: bool             # Whether href was successfully resolved
98
    
99
    # Methods
100
    @property
101
    def href():
102
        """Get/set import URL"""
103
    
104
    @href.setter
105
    def href(href):
106
        """Set import URL"""
107
```
108

109
### CSSMediaRule Class
110

111
@media rule with nested rules for specific media conditions.
112

113
```python { .api }
114
class CSSMediaRule:
115
    """
116
    @media rule implementing DOM Level 2 CSSMediaRule.
117
    """
118
    
119
    # Properties
120
    media: 'MediaList'     # Media query list
121
    cssRules: 'CSSRuleList'  # Nested rules
122
    
123
    # Rule Management
124
    def insertRule(rule, index):
125
        """
126
        Insert rule at specified index.
127
        
128
        Parameters:
129
        - rule (str/CSSRule): Rule to insert
130
        - index (int): Position to insert
131
        
132
        Returns:
133
        int: Index where rule was inserted
134
        """
135
    
136
    def deleteRule(index):
137
        """Delete rule at specified index"""
138
    
139
    def add(rule):
140
        """Add rule to end of media rule"""
141
```
142

143
### CSSPageRule Class
144

145
@page rule for paged media styling.
146

147
```python { .api }
148
class CSSPageRule:
149
    """
150
    @page rule implementing DOM Level 2 CSSPageRule.
151
    """
152
    
153
    # Properties
154
    selectorText: str            # Page selector (:left, :right, :first, etc.)
155
    style: 'CSSStyleDeclaration'  # Page box properties
156
    
157
    # Methods
158
    @property
159
    def selectorText():
160
        """Get/set page selector"""
161
    
162
    @selectorText.setter
163
    def selectorText(selectorText):
164
        """Set page selector with validation"""
165
```
166

167
### MarginRule Class
168

169
Margin rules within @page rules (e.g., @top-left, @bottom-center).
170

171
```python { .api }
172
class MarginRule:
173
    """
174
    Margin rule for @page contexts (cssutils extension).
175
    """
176
    
177
    # Properties
178
    margin: str                   # Margin area name (@top-left, etc.)
179
    style: 'CSSStyleDeclaration' # Margin box properties
180
    
181
    # Methods
182
    @property
183
    def margin():
184
        """Get/set margin area name"""
185
    
186
    @margin.setter
187
    def margin(margin):
188
        """Set margin area with validation"""
189
```
190

191
### CSSFontFaceRule Class
192

193
@font-face rule for custom font definitions.
194

195
```python { .api }
196
class CSSFontFaceRule:
197
    """
198
    @font-face rule implementing DOM Level 2 CSSFontFaceRule.
199
    """
200
    
201
    # Properties
202
    style: 'CSSStyleDeclaration'  # Font descriptors (src, font-family, etc.)
203
```
204

205
### CSSNamespaceRule Class
206

207
@namespace rule for XML namespace declarations.
208

209
```python { .api }
210
class CSSNamespaceRule:
211
    """
212
    @namespace rule implementing CSSOM CSSNamespaceRule.
213
    """
214
    
215
    # Properties
216
    namespaceURI: str  # Namespace URI
217
    prefix: str        # Namespace prefix (may be None for default namespace)
218
    
219
    # Methods  
220
    @property
221
    def namespaceURI():
222
        """Get/set namespace URI"""
223
    
224
    @namespaceURI.setter
225
    def namespaceURI(namespaceURI):
226
        """Set namespace URI with validation"""
227
    
228
    @property
229
    def prefix():
230
        """Get/set namespace prefix"""
231
    
232
    @prefix.setter
233
    def prefix(prefix):
234
        """Set namespace prefix"""
235
```
236

237
### CSSVariablesRule Class
238

239
CSS Variables rule (experimental, cssutils extension).
240

241
```python { .api }
242
class CSSVariablesRule:
243
    """
244
    CSS Variables rule (cssutils extension for CSS Variables draft).
245
    """
246
    
247
    # Properties
248
    media: 'MediaList'                        # Media query list
249
    variables: 'CSSVariablesDeclaration'     # Variable declarations
250
```
251

252
### CSSUnknownRule Class
253

254
Unknown @-rule for handling unrecognized at-rules.
255

256
```python { .api }
257
class CSSUnknownRule:
258
    """
259
    Unknown @-rule for unrecognized at-rules.
260
    """
261
    
262
    # Properties
263
    cssText: str  # Complete text of unknown rule
264
```
265

266
### CSSComment Class
267

268
CSS comment (cssutils extension).
269

270
```python { .api }
271
class CSSComment:
272
    """
273
    CSS comment (cssutils extension).
274
    """
275
    
276
    # Properties
277
    cssText: str  # Comment text including /* */ delimiters
278
```
279

280
## Usage Examples
281

282
### Working with Style Rules
283

284
```python
285
import cssutils
286
from cssutils.css import CSSStyleRule
287

288
# Parse style rules
289
css = """
290
body { margin: 0; padding: 0; }
291
h1 { color: blue; font-size: 24px; }
292
.highlight { background: yellow; }
293
"""
294

295
sheet = cssutils.parseString(css)
296

297
# Access style rules
298
for rule in sheet:
299
    if rule.type == rule.STYLE_RULE:
300
        print(f"Selector: {rule.selectorText}")
301
        print(f"Declarations: {rule.style.cssText}")
302
        
303
        # Modify selector
304
        if rule.selectorText == 'h1':
305
            rule.selectorText = 'h1, h2'
306
        
307
        # Modify properties
308
        rule.style.setProperty('line-height', '1.5')
309

310
# Create new style rule
311
rule = CSSStyleRule()
312
rule.selectorText = 'p.intro'
313
rule.style.cssText = 'font-weight: bold; color: #333;'
314
sheet.add(rule)
315
```
316

317
### Working with @media Rules
318

319
```python
320
import cssutils
321
from cssutils.css import CSSMediaRule, CSSStyleRule
322

323
# Parse media rules
324
css = """
325
@media screen and (max-width: 768px) {
326
    body { font-size: 14px; }
327
    .sidebar { display: none; }
328
}
329
"""
330

331
sheet = cssutils.parseString(css)
332

333
# Access media rule
334
media_rule = sheet.cssRules[0]
335
print(f"Media: {media_rule.media.mediaText}")
336

337
# Add rule to media rule
338
new_rule = CSSStyleRule()
339
new_rule.selectorText = '.mobile-only'
340
new_rule.style.display = 'block'
341
media_rule.add(new_rule)
342

343
# Create new media rule
344
media_rule = CSSMediaRule()
345
media_rule.media.mediaText = 'print'
346
style_rule = CSSStyleRule()
347
style_rule.selectorText = 'body'
348
style_rule.style.fontSize = '12pt'
349
media_rule.add(style_rule)
350
sheet.add(media_rule)
351
```
352

353
### Working with @import Rules
354

355
```python
356
import cssutils
357

358
# Parse import rules
359
css = """
360
@import url("base.css");
361
@import "layout.css" screen;
362
@import "print.css" print;
363
"""
364

365
sheet = cssutils.parseString(css)
366

367
# Access import rules
368
for rule in sheet:
369
    if rule.type == rule.IMPORT_RULE:
370
        print(f"Import: {rule.href}")
371
        print(f"Media: {rule.media.mediaText}")
372
        if rule.styleSheet:
373
            print(f"Loaded: {len(rule.styleSheet.cssRules)} rules")
374
```
375

376
### Working with @page Rules
377

378
```python
379
import cssutils
380
from cssutils.css import CSSPageRule, MarginRule
381

382
# Parse page rules
383
css = """
384
@page {
385
    margin: 1in;
386
    size: letter;
387
}
388

389
@page :first {
390
    margin-top: 2in;
391
}
392

393
@page {
394
    @top-left {
395
        content: "Document Title";
396
    }
397
    @bottom-center {
398
        content: counter(page);
399
    }
400
}
401
"""
402

403
sheet = cssutils.parseString(css)
404

405
# Access page rules  
406
for rule in sheet:
407
    if rule.type == rule.PAGE_RULE:
408
        print(f"Page selector: {rule.selectorText}")
409
        print(f"Properties: {rule.style.cssText}")
410
        
411
        # Access margin rules
412
        for margin_rule in rule.cssRules:
413
            if isinstance(margin_rule, MarginRule):
414
                print(f"Margin {margin_rule.margin}: {margin_rule.style.cssText}")
415
```
416

417
### Working with @font-face Rules
418

419
```python
420
import cssutils
421

422
# Parse font-face rules
423
css = """
424
@font-face {
425
    font-family: 'MyFont';
426
    src: url('myfont.woff2') format('woff2'),
427
         url('myfont.woff') format('woff');
428
    font-weight: normal;
429
    font-style: normal;
430
}
431
"""
432

433
sheet = cssutils.parseString(css)
434

435
# Access font-face rule
436
font_rule = sheet.cssRules[0]
437
print(f"Font family: {font_rule.style.getPropertyValue('font-family')}")
438
print(f"Sources: {font_rule.style.getPropertyValue('src')}")
439
```
440

441
### Working with @namespace Rules
442

443
```python
444
import cssutils
445

446
# Parse namespace rules
447
css = """
448
@namespace "http://www.w3.org/1999/xhtml";
449
@namespace svg "http://www.w3.org/2000/svg";
450

451
div { color: blue; }
452
svg|rect { fill: red; }
453
"""
454

455
sheet = cssutils.parseString(css)
456

457
# Access namespace rules
458
for rule in sheet:
459
    if rule.type == rule.NAMESPACE_RULE:
460
        print(f"Prefix: {rule.prefix}")
461
        print(f"URI: {rule.namespaceURI}")
462

463
# Access stylesheet namespaces
464
for prefix, uri in sheet.namespaces.items():
465
    print(f"Namespace {prefix}: {uri}")
466
```
467

468
### Rule Type Detection and Handling
469

470
```python
471
import cssutils
472

473
css = """
474
@charset "utf-8";
475
@import "base.css";
476
@media screen { body { margin: 0; } }
477
@page { margin: 1in; }
478
@font-face { font-family: 'Custom'; src: url('custom.woff'); }
479
/* Comment */
480
body { color: black; }
481
"""
482

483
sheet = cssutils.parseString(css)
484

485
# Handle all rule types
486
for rule in sheet:
487
    if rule.type == rule.CHARSET_RULE:
488
        print(f"Charset: {rule.encoding}")
489
    elif rule.type == rule.IMPORT_RULE:
490
        print(f"Import: {rule.href}")
491
    elif rule.type == rule.MEDIA_RULE:
492
        print(f"Media: {rule.media.mediaText} ({len(rule.cssRules)} nested rules)")
493
    elif rule.type == rule.PAGE_RULE:
494
        print(f"Page: {rule.selectorText}")
495
    elif rule.type == rule.FONT_FACE_RULE:
496
        print("Font-face rule")
497
    elif rule.type == rule.STYLE_RULE:
498
        print(f"Style: {rule.selectorText}")
499
    elif rule.type == rule.COMMENT:
500
        print(f"Comment: {rule.cssText}")
501
    else:
502
        print(f"Unknown rule type: {rule.type}")
503
```