1
2 """cssutils - CSS Cascading Style Sheets library for Python
3
4 Copyright (C) 2004-2008 Christof Hoeke
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2.1 of the License, or (at your option) any later version.
10
11 This library 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 GNU
14 Lesser General Public License for more details.
15
16 You should have received a copy of the GNU Lesser General Public
17 License along with this library; if not, write to the Free Software
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
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-03-21 23:33:10 +0100 #$:'
71 __version__ = '0.9.5b2 $Id: __init__.py 1189 2008-03-21 22:33:10Z cthedot $'
72
73 import codec
74
75
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
90 _ANYNS = -1
91
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
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
130
131 raise NotImplementedError
132
134
135 raise NotImplementedError
136
138 return (feature.lower(), unicode(version)) in self._features
139
140 xml.dom.registerDOMImplementation('cssutils', DOMImplementationCSS)
141
142
145 parseString.__doc__ = CSSParser.parseString.__doc__
146
149 parse.__doc__ = CSSParser.parse.__doc__
150
153 parseUrl.__doc__ = CSSParser.parseUrl.__doc__
154
155
156
158 """
159 sets the global serializer used by all class in cssutils
160 """
161 global ser
162 ser = serializer
163
164
166 """
167 Utility function to get all ``url(urlstring)`` values in
168 ``CSSImportRules`` and ``CSSStyleDeclaration`` objects (properties)
169 of given CSSStyleSheet ``sheet``.
170
171 This function is a generator. The url values exclude ``url(`` and ``)``
172 and surrounding single or double quotes.
173 """
174 for importrule in (r for r in sheet if r.type == r.IMPORT_RULE):
175 yield importrule.href
176
177 def getUrl(v):
178 if v.CSS_PRIMITIVE_VALUE == v.cssValueType and\
179 v.CSS_URI == v.primitiveType:
180 return v.getStringValue()
181
182 def styleDeclarations(base):
183 "recursive generator to find all CSSStyleDeclarations"
184 if hasattr(base, 'cssRules'):
185 for rule in base.cssRules:
186 for s in styleDeclarations(rule):
187 yield s
188 elif hasattr(base, 'style'):
189 yield base.style
190
191 for style in styleDeclarations(sheet):
192 for p in style.getProperties(all=True):
193 v = p.cssValue
194 if v.CSS_VALUE_LIST == v.cssValueType:
195 for item in v:
196 u = getUrl(item)
197 if u is not None:
198 yield u
199 elif v.CSS_PRIMITIVE_VALUE == v.cssValueType:
200 u = getUrl(v)
201 if u is not None:
202 yield u
203
205 """
206 Utility function to replace all ``url(urlstring)`` values in
207 ``CSSImportRules`` and ``CSSStyleDeclaration`` objects (properties)
208 of given CSSStyleSheet ``sheet``.
209
210 ``replacer`` must be a function which is called with a single
211 argument ``urlstring`` which is the current value of url()
212 excluding ``url(`` and ``)`` and surrounding single or double quotes.
213 """
214 for importrule in (r for r in sheet if r.type == r.IMPORT_RULE):
215 importrule.href = replacer(importrule.href)
216
217 def setProperty(v):
218 if v.CSS_PRIMITIVE_VALUE == v.cssValueType and\
219 v.CSS_URI == v.primitiveType:
220 v.setStringValue(v.CSS_URI,
221 replacer(v.getStringValue()))
222
223 def styleDeclarations(base):
224 "recursive generator to find all CSSStyleDeclarations"
225 if hasattr(base, 'cssRules'):
226 for rule in base.cssRules:
227 for s in styleDeclarations(rule):
228 yield s
229 elif hasattr(base, 'style'):
230 yield base.style
231
232 for style in styleDeclarations(sheet):
233 for p in style.getProperties(all=True):
234 v = p.cssValue
235 if v.CSS_VALUE_LIST == v.cssValueType:
236 for item in v:
237 setProperty(item)
238 elif v.CSS_PRIMITIVE_VALUE == v.cssValueType:
239 setProperty(v)
240
241
242 if __name__ == '__main__':
243 print __doc__
244