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 Vista mainly.
     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      a {
     66      color: red
     67      }
     68
     69  """
     70  __all__ = ['css', 'stylesheets', 'CSSParser', 'CSSSerializer']
     71  __docformat__ = 'restructuredtext'
     72  __author__ = 'Christof Hoeke with contributions by Walter Doerwald'
     73  __date__ = '$LastChangedDate:: 2008-08-11 20:11:23 +0200 #$:'
     74
     75  VERSION = '0.9.5.1'
     76
     77  __version__ = '%s $Id: __init__.py 1426 2008-08-11 18:11:23Z cthedot $' % VERSION
     78
     79  import codec
     80  import xml.dom
     81
     82  # order of imports is important (partly circular)
     83  from helper import Deprecated
     84  import errorhandler
     85  log = errorhandler.ErrorHandler()
     86
     87  import util
     88  import css
     89  import stylesheets
     90  from parse import CSSParser
     91
     92  from serialize import CSSSerializer
     93  ser = CSSSerializer()
     94
     95  # used by Selector defining namespace prefix '*'
     96  _ANYNS = -1
     97
     98 -class DOMImplementationCSS(object):
     99      """
    100      This interface allows the DOM user to create a CSSStyleSheet
    101      outside the context of a document. There is no way to associate
    102      the new CSSStyleSheet with a document in DOM Level 2.
    103
    104      This class is its *own factory*, as it is given to
    105      xml.dom.registerDOMImplementation which simply calls it and receives
    106      an instance of this class then.
    107      """
    108      _features = [
    109          ('css', '1.0'),
    110          ('css', '2.0'),
    111          ('stylesheets', '1.0'),
    112          ('stylesheets', '2.0')
    113      ]
    114
    115 -    def createCSSStyleSheet(self, title, media):
    116          """
    117          Creates a new CSSStyleSheet.
    118
    119          title of type DOMString
    120              The advisory title. See also the Style Sheet Interfaces
    121              section.
    122          media of type DOMString
    123              The comma-separated list of media associated with the new style
    124              sheet. See also the Style Sheet Interfaces section.
    125
    126          returns
    127              CSSStyleSheet: A new CSS style sheet.
    128
    129          TODO: DOMException
    130              SYNTAX_ERR: Raised if the specified media string value has a
    131              syntax error and is unparsable.
    132          """
    133          return css.CSSStyleSheet(title=title, media=media)
    134
    135 -    def createDocument(self, *args):
    136          # not needed to HTML, also not for CSS?
    137          raise NotImplementedError
    138
    139 -    def createDocumentType(self, *args):
    140          # not needed to HTML, also not for CSS?
    141          raise NotImplementedError
    142
    143 -    def hasFeature(self, feature, version):
    144          return (feature.lower(), unicode(version)) in self._features
    145
    146  xml.dom.registerDOMImplementation('cssutils', DOMImplementationCSS)
    147
    148
    149 -def parseString(*a, **k):
    150      return CSSParser().parseString(*a, **k)
    151  parseString.__doc__ = CSSParser.parseString.__doc__
    152
    153 -def parseFile(*a, **k):
    154      return CSSParser().parseFile(*a, **k)
    155  parseFile.__doc__ = CSSParser.parseFile.__doc__
    156
    157 -def parseUrl(*a, **k):
    158      return CSSParser().parseUrl(*a, **k)
    159  parseUrl.__doc__ = CSSParser.parseUrl.__doc__
    160
    161  @Deprecated('Use cssutils.parseFile() instead.')
    162 -def parse(*a, **k):
    163      return parseFile(*a, **k)
    164  parse.__doc__ = CSSParser.parse.__doc__
    165
    166
    167  # set "ser", default serializer
    168 -def setSerializer(serializer):
    169      """
    170      sets the global serializer used by all class in cssutils
    171      """
    172      global ser
    173      ser = serializer
    174
    175
    176 -def getUrls(sheet):
    177      """
    178      Utility function to get all ``url(urlstring)`` values in
    179      ``CSSImportRules`` and ``CSSStyleDeclaration`` objects (properties)
    180      of given CSSStyleSheet ``sheet``.
    181
    182      This function is a generator. The url values exclude ``url(`` and ``)``
    183      and surrounding single or double quotes.
    184      """
    185      for importrule in (r for r in sheet if r.type == r.IMPORT_RULE):
    186          yield importrule.href
    187
    188      def getUrl(v):
    189          if v.CSS_PRIMITIVE_VALUE == v.cssValueType and\
    190             v.CSS_URI == v.primitiveType:
    191                  return v.getStringValue()
    192
    193      def styleDeclarations(base):
    194          "recursive generator to find all CSSStyleDeclarations"
    195          if hasattr(base, 'cssRules'):
    196              for rule in base.cssRules:
    197                  for s in styleDeclarations(rule):
    198                      yield s
    199          elif hasattr(base, 'style'):
    200              yield base.style
    201
    202      for style in styleDeclarations(sheet):
    203          for p in style.getProperties(all=True):
    204              v = p.cssValue
    205              if v.CSS_VALUE_LIST == v.cssValueType:
    206                  for item in v:
    207                      u = getUrl(item)
    208                      if u is not None:
    209                          yield u
    210              elif v.CSS_PRIMITIVE_VALUE == v.cssValueType:
    211                  u = getUrl(v)
    212                  if u is not None:
    213                      yield u
    214
    215 -def replaceUrls(sheet, replacer):
    216      """
    217      Utility function to replace all ``url(urlstring)`` values in
    218      ``CSSImportRules`` and ``CSSStyleDeclaration`` objects (properties)
    219      of given CSSStyleSheet ``sheet``.
    220
    221      ``replacer`` must be a function which is called with a single
    222      argument ``urlstring`` which is the current value of url()
    223      excluding ``url(`` and ``)`` and surrounding single or double quotes.
    224      """
    225      for importrule in (r for r in sheet if r.type == r.IMPORT_RULE):
    226          importrule.href = replacer(importrule.href)
    227
    228      def setProperty(v):
    229          if v.CSS_PRIMITIVE_VALUE == v.cssValueType and\
    230             v.CSS_URI == v.primitiveType:
    231                  v.setStringValue(v.CSS_URI,
    232                                   replacer(v.getStringValue()))
    233
    234      def styleDeclarations(base):
    235          "recursive generator to find all CSSStyleDeclarations"
    236          if hasattr(base, 'cssRules'):
    237              for rule in base.cssRules:
    238                  for s in styleDeclarations(rule):
    239                      yield s
    240          elif hasattr(base, 'style'):
    241              yield base.style
    242
    243      for style in styleDeclarations(sheet):
    244          for p in style.getProperties(all=True):
    245              v = p.cssValue
    246              if v.CSS_VALUE_LIST == v.cssValueType:
    247                  for item in v:
    248                      setProperty(item)
    249              elif v.CSS_PRIMITIVE_VALUE == v.cssValueType:
    250                  setProperty(v)
    251
    252
    253  if __name__ == '__main__':
    254      print __doc__
    255