tessl/pypi-cssutils

A CSS Cascading Style Sheets library for Python implementing DOM Level 2 Style specifications

—

Pending

Overview

Eval results

Files

CSS Parsing

Name: tessl/pypi-cssutils
Author: tessl

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.

Capabilities

CSSParser Class

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

class CSSParser:
    """
    Parse CSS StyleSheets from various sources with configurable options.
    
    Constructor:
    CSSParser(log=None, loglevel=None, raiseExceptions=None, fetcher=None, 
              parseComments=True, validate=True)
              
    Parameters:
    - log: Custom logging object for parse messages
    - loglevel: Logging level for parse operations  
    - raiseExceptions: Whether to raise exceptions during parsing (default: log only)
    - fetcher: Custom URL fetcher function for @import resolution
    - parseComments: Whether to include CSS comments in DOM (default: True)
    - validate: Whether to validate CSS during parsing (default: True)
    """
    
    def parseString(self, cssText, encoding=None, href=None, media=None, title=None, validate=None):
        """
        Parse CSS from string.
        
        Parameters:
        - cssText (str): CSS source code to parse
        - encoding (str): Character encoding (default: detect or utf-8)
        - href (str): Base URL for resolving relative URLs
        - media (str/MediaList): Media query list for stylesheet
        - title (str): Advisory title for stylesheet
        - validate (bool): Override parser validation setting
        
        Returns:
        CSSStyleSheet: Parsed stylesheet object
        """
        
    def parseFile(self, filename, encoding=None, href=None, media=None, title=None, validate=None):
        """
        Parse CSS from file.
        
        Parameters:
        - filename (str): Path to CSS file
        - encoding (str): Character encoding (default: detect from file)
        - href (str): Base URL for resolving relative URLs (default: file URL)
        - media (str/MediaList): Media query list for stylesheet
        - title (str): Advisory title for stylesheet
        - validate (bool): Override parser validation setting
        
        Returns:
        CSSStyleSheet: Parsed stylesheet object
        """
        
    def parseUrl(self, href, encoding=None, media=None, title=None, validate=None):
        """
        Parse CSS from URL.
        
        Parameters:
        - href (str): URL of CSS resource to fetch and parse
        - encoding (str): Character encoding (default: detect from HTTP headers)
        - media (str/MediaList): Media query list for stylesheet
        - title (str): Advisory title for stylesheet
        - validate (bool): Override parser validation setting
        
        Returns:
        CSSStyleSheet: Parsed stylesheet object
        """
        
    def parseStyle(self, cssText, encoding='utf-8', validate=None):
        """
        Parse CSS style attribute content (property declarations only).
        
        Parameters:
        - cssText (str): CSS style attribute content
        - encoding (str): Character encoding (default: utf-8)
        - validate (bool): Override parser validation setting
        
        Returns:
        CSSStyleDeclaration: Parsed style declaration object
        """
        
    def setFetcher(self, fetcher=None):
        """
        Set custom URL fetcher function for resolving @import and url() references.
        
        Parameters:
        - fetcher (callable): Function that takes URL and returns (encoding, content) tuple
                             If None, uses default urllib-based fetcher
        """

Convenience Parse Functions

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

def parseString(cssText, encoding=None, href=None, media=None, title=None, validate=None):
    """
    Parse CSS string using default parser.
    
    Parameters:
    - cssText (str): CSS source code to parse
    - encoding (str): Character encoding
    - href (str): Base URL for resolving relative URLs
    - media (str/MediaList): Media query list
    - title (str): Advisory title
    - validate (bool): Whether to validate CSS
    
    Returns:
    CSSStyleSheet: Parsed stylesheet object
    """

def parseFile(filename, encoding=None, href=None, media=None, title=None, validate=None):
    """
    Parse CSS file using default parser.
    
    Parameters:
    - filename (str): Path to CSS file
    - encoding (str): Character encoding
    - href (str): Base URL for resolving relative URLs
    - media (str/MediaList): Media query list
    - title (str): Advisory title
    - validate (bool): Whether to validate CSS
    
    Returns:
    CSSStyleSheet: Parsed stylesheet object
    """

def parseUrl(href, encoding=None, media=None, title=None, validate=None):
    """
    Parse CSS from URL using default parser.
    
    Parameters:
    - href (str): URL of CSS resource
    - encoding (str): Character encoding
    - media (str/MediaList): Media query list
    - title (str): Advisory title
    - validate (bool): Whether to validate CSS
    
    Returns:
    CSSStyleSheet: Parsed stylesheet object
    """

def parseStyle(cssText, encoding='utf-8', validate=None):
    """
    Parse CSS style attribute using default parser.
    
    Parameters:
    - cssText (str): CSS style attribute content
    - encoding (str): Character encoding
    - validate (bool): Whether to validate CSS
    
    Returns:
    CSSStyleDeclaration: Parsed style declaration object
    """

Usage Examples

Basic Parsing

import cssutils

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

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

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

# Parse style attribute
style = cssutils.parseStyle('color: blue; margin: 10px')

Advanced Parser Configuration

import cssutils
import logging

# Create custom parser with logging
parser = cssutils.CSSParser(
    loglevel=logging.WARNING,
    raiseExceptions=False,
    parseComments=True,
    validate=True
)

# Custom URL fetcher for @import resolution
def custom_fetcher(url):
    # Custom logic to fetch URLs
    import urllib2
    response = urllib2.urlopen(url)
    encoding = response.headers.get('charset', 'utf-8')
    content = response.read()
    return encoding, content

parser.setFetcher(custom_fetcher)

# Parse with custom configuration
stylesheet = parser.parseString(css_text, 
                               href='http://example.com/base/',
                               media='screen, print',
                               title='Main Stylesheet')

Error Handling

import cssutils

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

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

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

Encoding Handling

import cssutils

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

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

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

Install with Tessl CLI