Package cssutils |
[hide private]
[frames] | no frames]

# Source Code for Package cssutils

      1  #!/usr/bin/env python
      2  """cssutils - CSS Cascading Style Sheets library for Python
      3
      4      Copyright (C) 2004-2008 Christof Hoeke
      5
      6      cssutils is free software: you can redistribute it and/or modify
      7      it under the terms of the GNU Lesser General Public License as published by
      8      the Free Software Foundation, either version 3 of the License, or
      9      (at your option) any later version.
     10
     11      This program is distributed in the hope that it will be useful,
     12      but WITHOUT ANY WARRANTY; without even the implied warranty of
     13      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     14      GNU Lesser General Public License for more details.
     15
     16      You should have received a copy of the GNU Lesser General Public License
     17      along with this program.  If not, see <http://www.gnu.org/licenses/>.
     18
     19
     20  A Python package to parse and build CSS Cascading Style Sheets. DOM only, not any rendering facilities!
     21
     22  Based upon and partly implementing the following specifications :
     23
     24  `CSS 2.1 <http://www.w3.org/TR/CSS21/>`__
     25      General CSS rules and properties are defined here
     26  `CSS 2.1 Errata  <http://www.w3.org/Style/css2-updates/CR-CSS21-20070719-errata.html>`__
     27      A few errata, mainly the definition of CHARSET_SYM tokens
     28  `CSS3 Module: Syntax <http://www.w3.org/TR/css3-syntax/>`__
     29      Used in parts since cssutils 0.9.4. cssutils tries to use the features from CSS 2.1 and CSS 3 with preference to CSS3 but as this is not final yet some parts are from CSS 2.1
     30  `MediaQueries <http://www.w3.org/TR/css3-mediaqueries/>`__
     31      MediaQueries are part of ``stylesheets.MediaList`` since v0.9.4, used in @import and @media rules.
     32  `Namespaces <http://dev.w3.org/csswg/css3-namespace/>`__
     33      Added in v0.9.1, updated to definition in CSSOM in v0.9.4, updated in 0.9.5 for dev version
     34  `Selectors <http://www.w3.org/TR/css3-selectors/>`__
     35      The selector syntax defined here (and not in CSS 2.1) should be parsable with cssutils (*should* mind though ;) )
     36
     37  `DOM Level 2 Style CSS <http://www.w3.org/TR/DOM-Level-2-Style/css.html>`__
     38      DOM for package css
     39  `DOM Level 2 Style Stylesheets <http://www.w3.org/TR/DOM-Level-2-Style/stylesheets.html>`__
     40      DOM for package stylesheets
     41  `CSSOM <http://dev.w3.org/csswg/cssom/>`__
     42      A few details (mainly the NamespaceRule DOM) is taken from here. Plan is to move implementation to the stuff defined here which is newer but still no REC so might change anytime...
     43
     44
     45  The cssutils tokenizer is a customized implementation of `CSS3 Module: Syntax (W3C Working Draft 13 August 2003) <http://www.w3.org/TR/css3-syntax/>`_ which itself is based on the CSS 2.1 tokenizer. It tries to be as compliant as possible but uses some (helpful) parts of the CSS 2.1 tokenizer.
     46
     47  I guess cssutils is neither CSS 2.1 nor CSS 3 compliant but tries to at least be able to parse both grammars including some more real world cases (some CSS hacks are actually parsed and serialized). Both official grammars are not final nor bugfree but still feasible. cssutils aim is not to be fully compliant to any CSS specification (the specifications seem to be in a constant flow anyway) but cssutils *should* be able to read and write as many as possible CSS stylesheets "in the wild" while at the same time implement the official APIs which are well documented. Some minor extensions are provided as well.
     48
     49  Please visit http://cthedot.de/cssutils/ for more details.
     50
     51
     52  Tested with Python 2.5 on Windows XP.
     53
     54
     55  This library may be used ``from cssutils import *`` which
     56  import subpackages ``css`` and ``stylesheets``, CSSParser and
     57  CSSSerializer classes only.
     58
     59  Usage may be::
     60
     61      >>> from cssutils import *
     62      >>> parser = CSSParser()
     63      >>> sheet = parser.parseString(u'a { color: red}')
     64      >>> print sheet.cssText
     65
     66  """
     67  __all__ = ['css', 'stylesheets', 'CSSParser', 'CSSSerializer']
     68  __docformat__ = 'restructuredtext'
     69  __author__ = 'Christof Hoeke with contributions by Walter Doerwald'
     70  __date__ = '$LastChangedDate:: 2008-06-01 21:06:37 +0200 #$:'
     71  __version__ = '0.9.5b3 $Id: __init__.py 1277 2008-06-01 19:06:37Z cthedot $'
     72
     73  import codec
     74
     75  # order of imports is important (maybe as it is partly circular)
     76  import xml.dom
     77
     78  import errorhandler
     79  log = errorhandler.ErrorHandler()
     80
     81  import util
     82  import css
     83  import stylesheets
     84  from parse import CSSParser
     85
     86  from serialize import CSSSerializer
     87  ser = CSSSerializer()
     88
     89  # used by Selector defining namespace prefix '*'
     90  _ANYNS = -1
     91
     92 -class DOMImplementationCSS(object):
     93      """
     94      This interface allows the DOM user to create a CSSStyleSheet
     95      outside the context of a document. There is no way to associate
     96      the new CSSStyleSheet with a document in DOM Level 2.
     97
     98      This class is its *own factory*, as it is given to
     99      xml.dom.registerDOMImplementation which simply calls it and receives
    100      an instance of this class then.
    101      """
    102      _features = [
    103          ('css', '1.0'),
    104          ('css', '2.0'),
    105          ('stylesheets', '1.0'),
    106          ('stylesheets', '2.0')
    107      ]
    108
    109 -    def createCSSStyleSheet(self, title, media):
    110          """
    111          Creates a new CSSStyleSheet.
    112
    113          title of type DOMString
    114              The advisory title. See also the Style Sheet Interfaces
    115              section.
    116          media of type DOMString
    117              The comma-separated list of media associated with the new style
    118              sheet. See also the Style Sheet Interfaces section.
    119
    120          returns
    121              CSSStyleSheet: A new CSS style sheet.
    122
    123          TODO: DOMException
    124              SYNTAX_ERR: Raised if the specified media string value has a
    125              syntax error and is unparsable.
    126          """
    127          return css.CSSStyleSheet(title=title, media=media)
    128
    129 -    def createDocument(self, *args):
    130          # not needed to HTML, also not for CSS?
    131          raise NotImplementedError
    132
    133 -    def createDocumentType(self, *args):
    134          # not needed to HTML, also not for CSS?
    135          raise NotImplementedError
    136
    137 -    def hasFeature(self, feature, version):
    138          return (feature.lower(), unicode(version)) in self._features
    139
    140  xml.dom.registerDOMImplementation('cssutils', DOMImplementationCSS)
    141
    142
    143 -def parseString(*a, **k):
    144      return CSSParser().parseString(*a, **k)
    145  parseString.__doc__ = CSSParser.parseString.__doc__
    146
    147 -def parseFile(*a, **k):
    148      return CSSParser().parseFile(*a, **k)
    149  parseFile.__doc__ = CSSParser.parseFile.__doc__
    150
    151 -def parseUrl(*a, **k):
    152      return CSSParser().parseUrl(*a, **k)
    153  parseUrl.__doc__ = CSSParser.parseUrl.__doc__
    154
    155  @util.Deprecated('Use cssutils.parseFile() instead.')
    156 -def parse(*a, **k):
    157      return CSSParser().parseFile(*a, **k)
    158  parse.__doc__ = CSSParser.parse.__doc__
    159
    160
    161  # set "ser", default serializer
    162 -def setSerializer(serializer):
    163      """
    164      sets the global serializer used by all class in cssutils
    165      """
    166      global ser
    167      ser = serializer
    168
    169
    170 -def getUrls(sheet):
    171      """
    172      Utility function to get all ``url(urlstring)`` values in
    173      ``CSSImportRules`` and ``CSSStyleDeclaration`` objects (properties)
    174      of given CSSStyleSheet ``sheet``.
    175
    176      This function is a generator. The url values exclude ``url(`` and ``)``
    177      and surrounding single or double quotes.
    178      """
    179      for importrule in (r for r in sheet if r.type == r.IMPORT_RULE):
    180          yield importrule.href
    181
    182      def getUrl(v):
    183          if v.CSS_PRIMITIVE_VALUE == v.cssValueType and\
    184             v.CSS_URI == v.primitiveType:
    185                  return v.getStringValue()
    186
    187      def styleDeclarations(base):
    188          "recursive generator to find all CSSStyleDeclarations"
    189          if hasattr(base, 'cssRules'):
    190              for rule in base.cssRules:
    191                  for s in styleDeclarations(rule):
    192                      yield s
    193          elif hasattr(base, 'style'):
    194              yield base.style
    195
    196      for style in styleDeclarations(sheet):
    197          for p in style.getProperties(all=True):
    198              v = p.cssValue
    199              if v.CSS_VALUE_LIST == v.cssValueType:
    200                  for item in v:
    201                      u = getUrl(item)
    202                      if u is not None:
    203                          yield u
    204              elif v.CSS_PRIMITIVE_VALUE == v.cssValueType:
    205                  u = getUrl(v)
    206                  if u is not None:
    207                      yield u
    208
    209 -def replaceUrls(sheet, replacer):
    210      """
    211      Utility function to replace all ``url(urlstring)`` values in
    212      ``CSSImportRules`` and ``CSSStyleDeclaration`` objects (properties)
    213      of given CSSStyleSheet ``sheet``.
    214
    215      ``replacer`` must be a function which is called with a single
    216      argument ``urlstring`` which is the current value of url()
    217      excluding ``url(`` and ``)`` and surrounding single or double quotes.
    218      """
    219      for importrule in (r for r in sheet if r.type == r.IMPORT_RULE):
    220          importrule.href = replacer(importrule.href)
    221
    222      def setProperty(v):
    223          if v.CSS_PRIMITIVE_VALUE == v.cssValueType and\
    224             v.CSS_URI == v.primitiveType:
    225                  v.setStringValue(v.CSS_URI,
    226                                   replacer(v.getStringValue()))
    227
    228      def styleDeclarations(base):
    229          "recursive generator to find all CSSStyleDeclarations"
    230          if hasattr(base, 'cssRules'):
    231              for rule in base.cssRules:
    232                  for s in styleDeclarations(rule):
    233                      yield s
    234          elif hasattr(base, 'style'):
    235              yield base.style
    236
    237      for style in styleDeclarations(sheet):
    238          for p in style.getProperties(all=True):
    239              v = p.cssValue
    240              if v.CSS_VALUE_LIST == v.cssValueType:
    241                  for item in v:
    242                      setProperty(item)
    243              elif v.CSS_PRIMITIVE_VALUE == v.cssValueType:
    244                  setProperty(v)
    245
    246
    247  if __name__ == '__main__':
    248      print __doc__
    249