CSSStyleSheet.cssText is a serialized byte string (not unicode string) currently. This may change in the future.
The seq attribute of most classes does not hinder you to add invalid items. It will probably become readonly. Never write to it!
Content of ``seq`` will most likely change completely, seq is more of an internal property and should not be used in client code yet
CSS2Properties not implemented completely (setting a shorthand property does not set related properties like setting margin does not set margin-left etc). Also the return values are not as defined in the specification as no normalizing is done yet. Prefer to use style['property'] over style.property.
although cssutils tries to preserve CSS hacks not all are (and some - mainly syntactically invalid ones - will probably never be). The following hacks are known to not be preserved:
*html syntactically invalid
html*#test-span (IMHO invalidated by the missing WS between html and "*")
The main problem for cssutils users is that some stylesheets in the wild are not parsable without loosing some information, a pretty print for these sheets is simply not possible with cssutils (actually with hardly any css parser...).
Generally syntactically valid stylesheets should be preserved completely (otherwise it will be a bug in cssutils itself). Invalid stylesheets will probably loose some information like to above *html hack. Most of these hacks may be rewritten while still be working, e.g. * html should work same to *html. Until cssutils 0.9.5b2 the invalid IE-specific CSS hack using $propertyname was preserved but its usage was already discouraged (and if e.g. specifying color and $color these properties are not the same for cssutils (but are for IE...). These kind of invalid hacks are not kept during parsing anymore since cssutils 0.9.5b3! In almost any case it is possible to use at least syntactically valid CSS while still working around different browser implementations.
Some methods of css.CSSPrimitiveValue and subclasses Rect, Counter and RGBColor are not implemented. As CSSOM defines a completely different DOM for Property values they may never be implemented as defined in DOM Level 2. Actually the current implementation of CSSValue, CSSValueList, and CSSPrimitiveValue may be completely replaced/refactored with suggestions from CSSOM.
handling of comments does probably not work for all cases
HEAD
API CHANGE: CSSRule.NAMESPACE_RULE actual value has been changed from 8 to 10 (according to the change in the CSSOM spec). The actual integer values SHOULD NOT be used anyway! Please do always use the ``CSSRule`` constants which are present in ALL CSSRule and subclass objects like CSSStyleRule, CSSImportRule etc.!
API CHANGE: CSSStyleSheet.setSerializer and CSSStyleSheet.setSerializerPref have been DEPRECATED. Use cssutils.setSerializer(serializer) or set pref in cssutils.ser.prefs instead.
FEATURE: Started experimental implementation of CSS Variables
experimental and incomplete
Related details:
- added cssutils.css.CSSStyleSheet.variables which is a cssutils.css.CSSVariablesDeclaration containing all available variables in this CSSStyleSheet including the ones defined in imported sheets.
- cssutils.ser.prefs.resolveVariables == False: If set to True tries to resolve all variable references and removes any CSSVariablesRules.
- cssutils.ser.prefs.normalizedVarNames==True: Defines if variable names should be serialized normalized (they are used as being normalized anyway)
DOCUMENTATION: Reordered and cleared docs up a bit
IMPROVEMENT: Massive speed improvement due to changes in internal parsing.
When tried in a real world situation (parsing the stylesheet for my own site inside a simple WSGI based CSS handler) the parser uses ~0.7-0.8s when using cssutils 0.9.6. With cssutils 0.9.7a0 it only needs ~0.21s so only about 1/3 to 1/4 the time...
FEATURE: Parameter index of CSSStyleSheet.deleteRule(index) and CSSMediaRule.deleteRule(index) may now also be a rule object to be removed from the contained cssRules list.
IMPROVEMENT: cssutils.resolveImports now keeps media information when to be resolved @import rule uses these. It wraps the imported rules in an @media rule which uses the same media information from the @media rule in the original sheet.
An xml.dom.HierarchyRequestErr may occur if an imported sheet itself contains @imports with media information or other rules which are not allowed in a @media rule like @namespace rules. In that case cssutils cannot resolve the @import rule and logs a WARNING but keeps the original @import.
new properties: font-stretch, font-size-adjust
Added CSSFontFaceRule.valid. A @font-face rule is valid if all font descriptions properties are valid and properties font-family and src are set.
FEATURE: Added cssutils.parseStyle(cssText, encoding='utf-8') convienience function which assumes that the given cssText is the content of an HTML style attribute. It returns a CSSStyleDeclaration.
FEATURE (experimental, request from issue #27): Added css.CSSStyleDeclaration.children() which is a generator yielding any known children of a declaration including all properties, comments or CSSUnknownRules.
FEATURE: CSSStyleDeclaration.insertRule also accepts a CSSRuleList now (same as CSSStyleSheet which does this for some time now).
FEATURE: Added CSSStyleDeclaration.keys() method which analoguous to standard dict returns property names which are set in the declaration.
BUGFIX: Parsing of CSSValues with unknown function names with a specific length of 4 or 7 chars were resulting in a SyntaxErr. Also parsing of comma separated list of CSS FUNCTION values works now.
FEATURE (experimental): Added support to at least parse sheets with Microsoft only property values for filter which start with progid:DXImageTransform.Microsoft.[...](. To enable these you need to set:
>>> from cssutils import settings
>>> settings.set('DXImageTransform.Microsoft', True)
>>> cssutils.ser.prefs.useMinified()
>>> text = 'a {filter: progid:DXImageTransform.Microsoft.BasicImage( rotation = 90 )}'
>>> print cssutils.parseString(text).cssText
a{filter:progid:DXImageTransform.Microsoft.BasicImage(rotation=90)}
>>>
This currently is a major hack but if you like to minimize sheets in the wild which use this kind of CSS cssutils at least can parse and reserialize them. Also you cannot reset this change until you restart your program.
These custom CSS FUNCTION names are not normalized at all. Also stuff like expression(...) which was normalized until now is not anymore.
BUGFIX: Fixed issue #22 parsing or actually reserializing of values like content: "\\"
FEATURE: New preference option keepUnkownAtRules = False which defines if unknown atrules like e.g. @three-dee {...} are kept or not. Setting this pref to False in result removes unknown @rules from the serialized sheet which is the default for the minified settings.
IMPROVEMENT: Fixed issue #23. The examples/style.py example renderer was reusing Property objects for each HTML element so they effectively overwrote each other.
BUGFIX: Fixed issue #21 http://code.google.com/p/cssutils/issues/detail?id=21. Definition of valid values for property background-position was wrong. Still mixed values like background-position: 0 top are invalid although most browsers accept them. But the CSS 2.1 spec defines it the above way. CSS3 backgrounds is not implemented yet in cssutils.
API CHANGE: cssutils.profiles.Profiles (introduced in 0.9.6a1) has been refactored:
- cssutils.profile (a cssutils.profiles.Profiles object) is now preset and available used for all validation
- moved variable cssutils.profiles.defaultprofile to attribute Profiles.defaultProfiles (and so also available as cssutils.profile.defaultProfiles)
- renamed Profiles.CSS_BOX_LEVEL_3 to Profiles.CSS3_BOX and Profiles.CSS_COLOR_LEVEL_3 to Profiles.CSS3_COLOR
- renamed Profiles.basicmacros to Profiles._TOKEN_MACROS and Profiles.generalmacros to Profiles._MACROS. As these two are always added to your property definitions there is no need to use these predefined macro dictionaries in your code.
- renamed Profiles.knownnames to Profiles.knownNames
- Profiles.validateWithProfile returns valid, matching, profiles now
- renamed named parameter in cssutils.css.Property.validate(profiles=None)() from profile to profiles
- cssutils.profiles.properties (and new cssutils.profiles.macros) use as keys the predefined constants in Profiles, like e.g. Profiles.CSS_LEVEL_2 now. If you want to use some of the predefind macros you may e.g. use cssutils.profiles.macros[Profiles.CSS_LEVEL_2]['family-name'] (in addition to the always available Profiles._TOKEN_MACROS and Profiles._MACROS).
CHANGE: Reporting levels of properties have changed. Please see cssutils.css.Property.validate() for details. E.g. valid properties in the current profile are only reported on DEBUG and not INFO level anymore. The log output has been changed too, context information is provided now (line, column and name of the relevant property)
API CHANGE: Known but invalid properties raise/log an ERROR instead of a WARNING now. Properties not expected in the current profile log an INFO. As the default profile is None even basic properties like color are logged now. You may want to change the default profile by setting e.g. cssutils.profiles.defaultprofile = cssutils.profiles.Profiles.CSS_LEVEL_2 (~ CSS 2.1) to prevent CSS 2.1 properties to be reported. Also other validation related output has been slightly changed.
The way to change a defaultprofile may change again.
API CHANGE: cssutils.script.csscombine has ONLY keyword parameters now. Use csscombine(path=path[,...]) for the old behaviour. New parameter url combines the sheet at URL now.
FEATURE: Added experimental profiles handling. You may add new profiles with new properties and their validation and set a defaultprofile used for validation. The current default profile is None so all predefined profiles are used. Currently 3 profiles are defined:
Properties defined by CSS2.1
CSS 3 color properties
Currently overflow related properties only
See the docs and source of the cssutils.profiles module for details.
FEATURE: cssutils.util._readUrl() allows fetchers to pre-decode CSS content and return unicode instances, with or without a specified source encoding (integrated from patch of Issue #19).
FEATURE: URL fetch method checks if cssutils is run in GoogleAppEngine (GAE) (if import google.appengine is successful) and uses the GAE fetch methods instead of urllib2 in that case. So in result cssutils should run on GAE just as elsewhere.
FEATURE: Function cssutils.resolveImports(sheet) returns a new stylesheet with all rules in given sheet but with all @import rules being pulled into the top sheet.
FEATURE: CSSCombine script and helper function resolve nested imports now.
FEATURE: Script csscombine has new option -u URL, --url=URL URL to parse (path is ignored if URL given) now
TODO: Preference setting. Profile?
FEATURE: xml.dom.DOMExceptions raised do now contain infos about the position where the exception occured. An exception might for example have been raised as:
raise xml.dom.SyntaxErr('the message', 10, 5)
(where 10 is the line and 5 the column of the offending text).
Therefor you may not simply use str(e) to get the exception message but you have to use msg, line, col = e.args[0], e.args[1], e.args[2]. Additionally exceptions raised have attributes e.line and e.col.
FEATURE: @page rule accepts named page selector now, e.g. @page intro or page main:left.
FEATURE: Script cssparse has new option -u URL which parses the given URL.
moved cssutils.css.cssproperties.cssvalues to cssutils.profiles.css2
added CSS Color Module Level 3 with properties color and opacity. Not implemented are SVG color names.
unknown properties raise a WARNING instead of INFO now
FEATURE experimental: Added class CSSColor which is used for RGB, RGBA, HSL, HSLA and HEX color values of CSSValue respective CSSPrimitiveValue.
FEATURE (strange): IE only CSS expressions should be parsed and serialized now an an Expression value. I have not tested this deeply and there may be problems but for some common cases this should work, e.g. for hacking maxwidth for IE you may define the following:
width: expression(document.body.clientWidth > 1000 ? "1000px": "100%")
Usage of CSS expressions is strongly discouraged as they do not validate AND may slow down the rendering and browser quite a lot!
Valid:
"somestring followed by escaped NL\
and continuing here."
and now results in:
"somestring followed by escaped NL and continuing here."
url()) => not allowed and must be written as url(")")
BUGFIX: Setting CSSPageRule.selectorText does actually work now.
BUGFIX: Other priority values than !important are parsed now. Nevertheless they log an ERROR or raise a SyntaxErr.
BUGFIX: Fixed Issue #14, added CSSStyleDeclaration().borderLeftWidth. But prefer to use CSSStyleDeclaration()['border-left.width'].
API CHANGE/BUGFIX (major):
Upto 0.9.5rc1 any sheet resulting from parsing via any parse* function or CSSParser(raiseExceptions=False) (which also was and is the default) resulted in the library simply logging any later exceptions and not raising them. Until now the global setting of cssutils.log.raiseExceptions=True (the default) was overwritten with the value of the CSSParser raiseExceptions setting which normally is False any time a cssutils.parse* function or CSSParser.parse* method was used. 0.9.5rc2 fixes this.
until 0.9.5rc1:
>>> # parsing does not raise errors >>> s = cssutils.parseString('$') # empty but CSSStyleSheet object >>> # using DOM methods does **not raise either** but should: >>> s.cssText = '$' # just logs: ERROR CSSStyleRule: No start { of style declaration found: u'$' [1:2: ]from 0.9.5rc2:
>>> # parsing STILL does not raise errors >>> s = cssutils.parseString('$') # empty but CSSStyleSheet object >>> # using DOM methods **does raise now though** >>> s.cssText = '$' # raises: xml.dom.SyntaxErr: CSSStyleRule: No start { of style declaration found: u'$' [1:1: $]To use the old but false behaviour add the following line at the start to your program:
>>> cssutils.log.raiseExceptions = False # normally TrueThis should only be done in specific cases as normal raising of exceptions in methods or functions with the CSS DOM is the expected behaviour. This setting may also be removed in the future so use with care.
BUGFIX: Parsing of @rules like @mediaall ... does not result in @media all ... anymore (so not a CSSMediaRule) but parses as @mediaall so a CSSUnknownRule. The specification is not too clear here but it seems this is the way to go. To help finding typos like this probably is, for any found CSSUnknownRule (an unknown @rule) a WARNING is emitted now (but never an exception raised). These typos will most likely happen like e.g. @mediaall, @importurl(), @namespaceprefix"uri" or @pagename:left.
BUGFIX: Parsing of unicode escapes like \\abc followed by CR/LF this is now correctly combined as only a single whitespace character.
BUGFIX: Adding a malformed stylesheets.MediaQuery to a stylesheets.MediaList does fail now, e.g.:
>>> # invalid malformed medialist (missing comma):
>>> sheet = cssutils.parseString('@media tv INVALID {a {top: 0;}}')
ERROR MediaQuery: Unexpected syntax. [1:11: INVALID]
ERROR MediaList: Invalid MediaQuery: tv INVALID
>>> # the actual rule exists but has default empty content, this may be
changed later as it can be seen as a bug itself
>>> sheet.cssRules[0]
cssutils.css.CSSMediaRule(mediaText=u'all')
>>> sheet.cssText
''
>>> # BUT: Unknown media type but as it is valid does parse:
>>> sheet = cssutils.parseString('@media tv, UNKNOWN {a {top: 0;}}')
WARNING MediaQuery: Unknown media type "UNKNOWN".
>>> sheet.cssRules[0]
cssutils.css.CSSMediaRule(mediaText=u'tv, UNKNOWN')
>>> sheet.cssText
'@media tv, UNKNOWN {\n a {\n top: 0\n }\n }'
BUGFIX: References to MediaList in CSSImportRule and CSSMediaRule are kept now properly.
BUGFIX: Deleting a MediaQuery item from a MediaList does use the libs logging/raising settings instead of always raising
IMPROVEMENT: Parsing performance has been improved (by about 25%, tested with a basic CSS of about 50 lines, so may not be representative but this release definitely is faster ;). The following changes have been done which should not impact any actual stylesheet:
- A BOM token is recognized at the start of a stylesheet only (may be swallowed by the CSS codec anyway).
- A BOM token is not counted in the line/col reporting anymore so the following token has a line and col of 1 now
- Tests for tokenizing with css2productions has been removed but this is never used in the library anyway
API CHANGE/FEATURE: The cssutils.log may be partly used like a standard logging log. The following methods are available: ('setLevel', 'getEffectiveLevel', 'addHandler', 'removeHandler') as well as all "messaging" calls like 'error', 'warning' etc.
Therefor cssutils.log.setloglevel has been DEPRECATED and should be used via cssutils.log.setLevel. The old method is still available though.
cssutils.log.setlog has been renamed to cssutils.log.setLog but is still available but DEPRECATED too.
FEATURE: All three decoders in the codec now have an additional force argument. If force is false, the encoding from the input will only by used if is is detected explicitely via BOM or @charset rule.
FEATURE: cssparse script has new option -m --minify which results in the parsed CSS to be serialized minified
FEATURE: CSSCapture and csscombine are now available not only as standalone scripts but also via cssutils.script.CSSCapture and cssutils.script.csscombine repectively so you can use them programmatically now.
BUGFIX: A space after @rule keyword is added when serializing minified something like @media all{}. Until now it was @mediaall{} which is recognized by Safari only but probably is not valid at all. Other @rules behave similar now too.
BUGFIX: Properties of rules set via css.CSSStyleSheet.add or .insert were not set properly, e.g. parentStyleSheet or the stylesheet handling of new @import rules was buggy.
BUGFIX: Encountering OSError during resolving @import does not throw an error anymore but the resulting CSSImportRule.styleSheet will have a value of None. OSError will probably only happen when using parseFile.
IMPROVEMENT/BUGFIX: A style sheet with href == None (e.g. parsed with parseString() or build completely from scratch) uses os.getcwd() as its base href now to be able to resolve CSSImportRules.
IMPROVEMENT/BUGFIX: Rewrote csscombine script which should be much more stable now and handles namespaces correctly. Nested imports are still not resolved yet but this may come in the next release.
IMPROVEMENT/BUGFIX: Added catching of WindowsError to default fetcher (e.g. is a file URL references a file not present).
CHANGE/BUGFIX: Redone csscapture script. A few minor method changes (parameter ua of capture has been replaced by init parameter) and lots of internal improvement has been done.
CHANGE: CSSStyleSheet.add(rule) simply appends rules with no specific order in the sheet to the end of it. So e.g. COMMENTs, STYLE_RULEs, etc are appended while rules with a specific place are ordered-in as before (e.g. IMPORT_RULE or NAMESPACE_RULE). Until now rules of a specific type like COMMENTs were ordered together which does not really make sense. The csscombine script needs this functionality and the resulting combined sheets should be more readable and understandable now.
CHANGE: Default URL fetcher emits an ERROR instead of a warning if finding a different mine-type than text/css.
API CHANGE: parse() is DEPRECATED, use parseFile() instead. I know this should not happen in a release already in beta but better now than later and currently both ways are still possible.
FEATURE: CSSStyleDeclatation objects may be used like dictionaries now. The value during setting a property may be a single value string or a tuple of (value, priority):
>>> style = css.CSSStyleDeclaration()
>>> style['color'] = 'red'
>>> style.getProperties()
[cssutils.css.Property(name='color', value=u'red', priority=u'')]
>>> del style['color']
>>> style['unknown'] = ('value', 'important')
INFO Property: No CSS2 Property: 'unknown'.
>>> style.getProperties()
[cssutils.css.Property(name='unknown', value=u'value', priority=u'impor
tant')]
>>> del style['never-set'] # does not raise KeyError but returns u'' like removeProperty()
>>>
FEATURE: While reading an imported styleSheet all relevant encoding parameters (HTTP headers, BOM/@charset, etc) are used now as defined in http://www.w3.org/TR/CSS21/syndata.html#charset
Additionally a given parameter encoding for parseString, parseFile and parseUrl functions/methods overrides any detected encoding of read sheet like HTTP information or @charset rules. Useful if e.g. HTTP information is not set properly. The given encoding is used for all imported sheets of the parsed one too! This is a cssutils only addition to the rules defined at http://www.w3.org/TR/CSS21/syndata.html#charset.
FEATURE: A custom URL fetcher may be used during parsing via CSSParser.setFetcher(fetcher) (or as an init parameter). The so customized parser is reusable (as all parsers are). The fetcher is called when an @import rule is found and the referenced stylesheet is about to be retrieved.
The function gets a single parameter
the URL to read
and MUST return (encoding, content) where encoding normally is the HTTP charset given via a Content-Type header (which may simply omit the charset though) and content being the (byte) string content. The Mimetype of the fetched url should be text/css but this has to be checked by the fetcher itself (the default fetcher emits an ERROR (from 0.9.5 before a WARNING) if encountering a different mimetype). The content is then decoded by cssutils using all encoding related data available.
Example:
def fetcher(url): return 'ascii', '/*test*/' parser = cssutils.CSSParser(fetcher=fetcher) parser.parse...
To omit parsing of imported sheets just define a fetcher like lambda url: None (A single None is sufficient but returning (None, None) is more explicit).
You might also want to define an encoding for each imported sheet with a fetcher which returns a (normally HTTP content-type header) encoding depending on each URL.
FEATURE: Added option -s --string to cssparse script which expects a CSS string to be parsed.
FEATURE/BUGFIX: Parsing of CSSStyleDeclarations is improved. Invalid /color: red;color: green is now correctly parsed as color: green now. At the same time the until now parsed but invalid $color: red (an IE hack) is not parse anymore but correctly dismissed!
Unknown rules in CSSStyleDeclaration are parsed now. So e.g @x; color: red; which is syntactically valid is kept completely.
BUGFIX: parseUrl does return None if an error occurs during reading the given URL. Until now an empty stylesheet was returned.
BUGFIX: Fixed parsing of values like background: url(x.gif)0 0; (missing space but still valid).
BUGFIX: Serializing CSSUnknownRules is slightly improved, blocks are correctly indentet now.
LICENSE: cssutils is licensed under the LGPL v3 now (before LGPL v2.1). This should not be a problem I guess but please be aware. So the former mix of LGPL 2.1 and 3 is resolved to a single LGPL 3 license for both cssutils and the included encutils.
INTERNAL: Moved tests out of cssutils main package into a tests package parallel to cssutils.
API CHANGE: cssutils.css.CSSSStyleSheet.replaceUrls(replacer) has been DEPRECATED but is available as an utility function so simply use cssutils.replaceUrls(sheet, replacer) instead. For the why see getUrls(sheet) below.
API CHANGE/FEATURE: parseString has a new parameter encoding now which is used if a str is given for cssText. Otherwise it is ignored. (patch by doerwalter)
API CHANGE/FEATURE: .parse() .parseString() and constructor of CSSStyleSheet have a new parameter title needed for the cascade (yet to be implemented ;).
Also the representation of CSSStyleSheet has been improved.
FEATURE: Defining a namespace with a prefix but an empty namespaceURI is not allowed in XML 1.0 (but in XML 1.1). It is allowed in CSS and therefor also in cssutils.
ATTENTION: CSS differs from XML 1.0 here!
FEATURE: Added property css.CSSImportRule.name and css.CSSMediaRule.name as decribed in http://www.w3.org/TR/css3-cascade/#cascading. It is parsed, serialized and available in this new property now. Property name is a constructor parameter now too.
FEATURE: css.UnknownRule is now parsed properly and checked for INVALID tokens or if {}, [] or () are not nested or paired properly. CSSUnknownRule is removed from CSSOM but in cssutils it is and will be used for @rules of programs using extensions, e.g. PrinceXML CSS. It is not very usable yet as no actual properties except atkeyword, cssText and seq are present but at least it is syntactically checked properly and I hope serialized similar to other rules. This has been completely rewritten so may contain a few bugs so check your serialized sheets if you use non-standard @rules.
BUGFIX: Improved escaping. Fixed cases where e.g. an URI is given as url("\""). Also escapes of delimiters in STRINGs is improved. This is used by CSSImportRule or CSSNamespaceRule among others. All STRING values are serialized with "..." (double quotes) now. This should not be a problem but please note that e.g. a CSSValue may be slightly different now (but be as valid as before).
BUGFIX: Fixed serialization of namespaces in Selector objects. Actually all possible namespaced selectors should be preserved now:
- *
any element or if a default namespace is given any element in that namespace
- a
all "a" elements or if a default namespace is given "a" elements in that namespace
- |*
any element in the no namespace (the empty namespace)
- |a
"a" elements in the no namespace (the empty namespace)
- *|*
any element in any namespace including the no namespace
- *|a
"a" elements in any namespace including the no namespace
- p|*
any element in the namespace defined for prefix p
- p|a
"a" elements in the namespace defined for prefix p
BUGFIX: Default namespace is no longer used by attribute selectors.
Aim was to prevent building invalid style sheets. therefor namespaces must be checked e.g. when adding a new Selector etc. This probably is not fixed for all cases but much better now than before.
API CHANGE: parentRule and parentStyleSheet of all CSS rules are now readonly to prevent building illegal style sheets.
API CHANGE: Changed order of constructor parameters for CSSStyleDeclaration. Named parameters SHOULD be used anyway but be careful if you used ordered ones here!
BUGFIX: CSSMediaRule.insertRule setting with a rule string fixed
BUGFIX: *.parentStyleSheet and *.parentRule where * is any CSSRule is properly set now
BUGFIX: CSSStyleDeclatation.getPropertyPriority(p) returns important (without the "!"!) or the empty string now (see http://dev.w3.org/csswg/cssom/#the-cssstyledeclaration). Same goes for Property.priority which is not in CSSOM but cssutils only.
(Property._normalpriority has been removed, the normalized value that was available here is now in Property.priority. The literal priority value is available in Property.literalproperty now (analog to Property.literalname). All these values probably should not be used by client code anyway but may be helpful when using CSS hacks.)
BUGFIX: Changed serialization of combinators in Selector according to http://dev.w3.org/csswg/cssom/#selectors, e.g. a>b+c~d e serializes as a > b + c ~ d e now (single spaces around +, > and ~). A new serializer preference selectorCombinatorSpacer = u' ' has been added to overwrite this behaviour (which is set to u'' when using the CSS minifier settings)
BUGFIX: Some minor fixes including some reference improvements
API CHANGE: Property.name is now the same as Property.normalname which is DEPRECATED now. To access the literal name (the value which was available in name until now) use Property.literalname. For most cases where a property name is used the new behaviour makes more sense, therefor the change.
Do not use ``normalname`` anymore, it will probably be removed for release 1.0.
NEW since 0.9.5:
p = Property(ur'c\olor', 'red') p.name == ur'color' p.literalname == ur'c\olor' # DEPRECATED: p.normalname == ur'color'OLD until 0.9.5:
p = Property(ur'c\olor', 'red') p.name == ur'c\olor' p.normalname == ur'color'
API CHANGE: iterating over css.CSSStyleDeclaration yields now effective properties only and not all properties set in the declaration. E.g. from color: red; c\olor: green only one Property is returned which has the value green. To retrieve all properties use CSSStyleDeclaration.getProperties(all=True). Reason for this change is that for most cases the new default makes more sense.
FEATURE: css.CSSStyleDelcaration supports in now. Expected is a Property or a name of a property which is checked if already in the style declaration
FEATURE: css.Selector has a readonly property specificity now which is calculated as described at http://www.w3.org/TR/css3-selectors/#specificity
ATTENTION: changing the Selector by changing its property seq does not update the specificity! Selector.seq.append has been made private therefor and writing to seq not be used at all!
FEATURE: Added css.CSSStyleDeclaration.getProperty(name, normalize=True) which returns the effective Property object for name.
FEATURE: Implemented http://csswg.inkedblade.net/spec/css2.1#issue-23, URI may be URL(...) or u\r\6c(...) now
BUGFIX: Serializing escape sequences add a single SPACE after each escape. This was not present until now so a sequence like "\74 a" did come out as "\000074a" which was not as intended. Also as a SPACE is inserted in any case all escapes are not padded to 6 digits anymore but are only as long as needed.
BUGFIX: Handling of illegal selectors is now same as the W3C CSS validator (and according the selector spec - I hope ;). Illegal selectors result the complete rule being dropped. Fixed are the following (edge) cases:
Meant was probably a space between a and b (plus maybe the comment) but it MUST be inserted. IE and Safari nevertheless seem to parse this rule as a b so as if a space would be present. cssutils now parses this selector as intented by the spec as ab.
Again spaces around the UNIVERSAL * were probably meant by the author. IE and Safari seem to parse this invalid selector as a b. cssutils ignores this rule completely!
BUGFIX: css.CSSRuleList is still a Python list but setting methods like __init__, append, extend or __setslice__ are added later on instances of this class if so desired. E.g. CSSStyleSheet adds append which is not available in a simple instance of this class! This has been changed as no validation is possible in CSSRuleList itself.
FEATURE: Implemented css.CSSFontFaceRule.
FEATURE: Added css.CSSStyleSheet.encoding which reflects the encoding of an explicit @charset rule. Setting the property to None removes an @charset rule if present and sets the encoding to the default value 'utf-8'. Setting a value of utf-8 sets the encoding to the default value too but the @charset rule is explicitly added.
Effectively this removes the need to use css.CSSCharsetRule directly as using this new property is easier and simpler.
(A suggestion in the CSSOM but not yet resolved. IMHO it does make sense so it is present in cssutils. css.CSSCharsetRule remains though if you really want to use it).
BUGFIX/IMPROVEMENT: css.SelectorList and stylesheets.MediaList have (Python) list like behaviour partly but are directly not lists anymore (which did not work properly anyway...). The following list like possibilities are implemented for now:
The DOM additional methods and properties like length or item() are still present (and also will be in the future) but the standard Python idioms are probably easier to use.
stylesheets.StyleSheetList and css.CSSRuleList are the only direct lists for now. This may change in the future so it is safer to also use the above possibilities only for now.
BUGFIX: Fixed handling of "\ " (an escaped space) in selectors and values.
BUGFIX: !important is normalized (lowercase) now
BUGFIX/FEATURE: Handling of unicode escapes should now work propertly.
The tokenizer resolves any unicodes escape sequences now so cssutils internally simple unicode strings are used.
The serializer should serialize a CSSStyleSheet properly escaped according to the relevant encoding defined in an @charset rule or defaulting to UTF-8. Characters not allowed in the current encoding are escaped the CSS way with a backslash followed by a uppercase 6 digit hex code point (always 6 digits to make it easier not to have to check if no hexdigit char is following).
This FEATURE was not present in any older version of cssutils.
BUGFIX: Names (of properties or values) which are normalized should be properly normalized now so simple escapes like c\olor but also unicode escapes like \43olor should result in the property name color now
BUGFIX: Selector did fail to parse negation :not( correctly
BUGFIX: CSSValueList treated a value like -1px as 2 entries, now they are correctly 1.
BUGFIX: Validation of values for background-position was wrong.
BUGFIX: CSSPrimitiveValue.primitiveValue was not recognized properly if e.g. a CSS_PX was given as '1PX' instead of '1px'.
BUGFIX/CHANGE: Reporting of line numbers should have improved as \n is now used instead of os.linesep.
CHANGE: Invalid Properties like $top which some UAs like Internet Explorer still are use are preserved. This makes the containing Property and CSSStyleDeclaration invalid (but still wellformed although they technically are not) so if the serializer is set to only output valid stuff they get stripped anyway.
This may change and also simply may be put in a cssutils wide "compatibility mode" feature.
CHANGE: If a CSSValue cannot be validated (no property context is set) the message describing this is set to DEBUG level now (was INFO).
IMPROVEMENT: "setup.py" catches exception if setuptools is not installed and emits message
FEATURE: Added a new module cssutils.codec that registers a codec that can be used for encoding and decoding CSS. (http://www.w3.org/TR/2006/WD-CSS21-20060411/syndata.html#q23)
FEATURE: Added implementation of stylesheets.MediaQuery which are part of stylesheets.MediaList. See the complete spec at http://www.w3.org/TR/css3-mediaqueries/ for details.
Not complete yet: Properties of MediaQueries are not validated for now and maybe some details are missing
FEATURE: Implemented cssutils.DOMImplementationCSS. This way it is possible to create a new StyleSheet by calling DOMImplementationCSS.createCSSStyleSheet(title, media). For most cases it is probably easier to make a new StyleSheet by getting an instance of cssutils.css.CSSStyleSheet though.
FEATURE: cssutils is registered to xml.dom.DOMImplementation claiming to implement CSS 1.0, CSS 2.0, StyleSheets 1.0 and StyleSheets 2.0. This is probably not absolutely correct as cssutils currently is not a fully compliant implementation but I guess this is used very rarely anyway.
FEATURE: Implemented css.CSSValue, css.CSSPrimitiveValue and css.CSSValueList.
- Not yet implemented are:
- css.CSSPrimitiveValue.getCounterValue and css. Counter
- css.CSSPrimitiveValue.getRGBColorValue and css.RGBColor
- css.CSSPrimitiveValue.getRectValue and css.Rect
- FEATURE: css.CSSValueList is iterable so may be used in a for loop
- FEATURE: CSSValue has property cssValueTypeString which is the name of the relevant cssValueType, e.g. "CSS_PRIMITIVE_TYPE". Mainly useful for debugging.
- FEATURE: CSSPrimitiveValue has property primitiveTypeString which is the name of the relevant primitiveType, e.g. "CSS_PX". Mainly useful for debugging.
- CSSValue has an init Parameter _propertyname to set a context property for validation. If none is set the value is always invalid. THIS MAY CHANGE!
FEATURE (experimental): CSSStyleDeclaration is iterable now. The iterator returns all properties set in this style as objects with properties name, cssValue and priority. Calling CSSStyleDeclaration.item(index) on the other hand simply returns a property name and also only the normalized name (once). Example:
sheet = cssutils.parseString('a { color: red; c\olor: blue; left: 0 !important }')
for rule in sheet.cssRules:
style = rule.style
for property in style:
name = property.name
cssValue = property.cssValue
priority = property.priority
print name, '=', cssValue.cssText, priority
# prints:
# color = red
# c\olor = blue
# left = 0 !important
for i in range(0, style.length):
name = style.item(i)
cssValue = style.getPropertyCSSValue(name)
priority = style.getPropertyPriority(name)
print name, '=', cssValue.cssText , priority
# prints:
# color = blue
# left = 0 !important
ATTENTION: This has been changed in 0.9.5, see details there!
FEATURE (experimental): added CSSStyleSheet.replaceUrls(replacer) which may be used to adjust all "url()" values in a style sheet (currently in CSSStyleDeclaration and CSSImportRules).
FEATURE: added CSSStyleDeclaration.getCssText(separator=None) which returns serialized property cssText, each property separated by given separator which may e.g. be u'' to be able to use cssText directly in an HTML style attribute. ";" is always part of each property (except the last one) and can not be set with separator!
FEATURE: href and media arguments can now be passed to parse() and parseString() functions and methods. This sets the appropriate attributes on the generated stylesheet objects.
FEATURE: CSSMediaRule has an init parameter mediaText synchronous to CSSImportRule now
FEATURE: The MediaList constructor can now be passed a list of media types.
FEATURE: CSSRule and subclasses have a property typeString which is the name of the relevant type, e.g. STYLE_RULE. Mainly useful for debugging.
FEATURE: cssutils.serialize.Preferences has a new option lineSeparator that is used as linefeed character(s). May also be set to u'' for CSSStyleDeclareation.cssText' to be directly usable in e.g. HTML style attributes
CHANGE (experimental!): CSSStyleDeclaration.getPropertyCSSValue() for shorthand properties like e.g. background should return None. cssutils returns a CSSValueList in these cases now. Use with care as this may change later
CHANGE: CSSValue default cssText is now u"" and not u"inherit" anymore
CHANGE: css.CSSStyleDeclaration.cssText indents its property not anymore.
CHANGE: cssutils.serialize.CSSSerializer has been refactored internally to support the lineSeparator option.
CHANGE: The Selector and SameNamePropertyList (which might be renamed as it is experimental) class are now available from cssutils.css too.
UPDATE: SameNamePropertyList removed in 0.9.4
CHANGE: Tokenizer strips HTML comment tokens CDO and CDC from tokenlist now.
CHANGE: Added __repr__ and __str__ methods to most classes. __str__ reports e.g. <cssutils.css.CSSImportRule object href=None at 0xaaa870>, __repr__ e.g. cssutils.css.CSSImportRule(href=None, mediaText=u'all') which is a valid contructor for the object in most cases (which might not be complete for all init parameter for all classes like in this case though). The following details are included:
FEATURE: Partly Implemented css.CSS2Properties so you can now use:
>>> sheet = cssutils.parseString('a { font-style: italic; }')
>>> style = sheet.cssRules[0].style
>>> style.fontStyle = 'normal'
>>> print style.fontStyle
normal
Each property can be retrieved from CSSStyleDeclaration object with its name as an object property. Names with "-" in it like font-style need to be called by the respective DOM name fontStyle. Setting a property value works the same way and even del which effectively removes a property from a CSSStyleDeclaration works. For details see CSSStyleDeclaration.
Not implemented are the finer details, see the module documentation of cssutils.css.cssproperties.
BUGFIX: CSSStyleDeclaration.getPropertyCSSValue returns None for all shorthand properties
refactored some parts and added more tests
CHANGE for Serializer preference options:
new name + defaultAtKeyword instead of normalkeyword + defaultPropertyName instead of normalpropertyname
camelcase now: + keepComments instead of keepComments + lineNumbers instead of linenumbers
replaced (see below) + keepAllProperties instead of keepsimilarnamedproperties
if True all properties given in the parsed CSS are kept. This may be useful for cases like:
background: url(1.gif) fixed;
background: url(2.gif) scroll;
Certain UAs may not know fixed and will therefor ignore property 1 but an application might simply like to prettyprint the stylesheet without loosing any information.
Defaults to False.
See examples/serialize.py for an usage example.
CSSStyleDeclaration.getSameNamePropertyList(name) Experimental method to retrieve a SameNamePropertyList object which holds all Properties with the given name. The object has an attribute name and a list of Property objects each with an actual name, value and priority.
UPDATE: SameNamePropertyList removed in 0.9.4
CSSStyleDeclaration.setProperty has a new positional parameter overwrite which defines if the property which is set overwrites any former value (or values, see getSameNamePropertyList) (default behaviour) or the given value is appended to any former value (overwrite=False). Useful for cases where a property should have different values for different UAs.
Example 1: CSS hacks:
width: 100px; /* wrong box model value for IE5-5.5 */
padding: 5px;
w\idth: 90px; /* correct box model value for later browsers */
Example 2: UA capabilities:
background: url(2.gif) scroll; /* Fallback for UA which do not understand fixed */
background: url(1.gif) fixed; /* UA which do know fixed */
FEATURE: Reimplemented csscapture, which uses the new serializer preference keepAllProperties
see examples/serialize.py
BUGFIX(minor): Parameter name for CSSStyleDeclaration.XXX(name)` is normalized now, so color, c\olor and COLOR are all equivalent
if True all properties with the same normalname but different actual names are kept, e.g. color, color, color. This is mainly useful to keep a stylesheet complete which uses xbrowser hacks as above.
UPDATE IN 0.9.1b3!
BUGFIX (minor): Serializer.prefs.normalpropertyname did not work properly if a property was set 2 times in the same declaration, e.g. color: red;c\olor: green setting the pref to False results in c\olor: green now.
BUGFIX (minor): Serializing of CSSStyleDeclaration did not work well when CSSComments were mixed with Properties.
FUTURE CHANGE: readonly will be removed from most rules. It is not used anyway, may be readded in a future release
CHANGE: order of constructor parameters changed in CSSImportRule. Should be no problem as positional parameters are discouraged anyway
CHANGE: cssutils needs Python 2.4 from the release on as it uses the buildin set
CHANGE: removed CSSMediaRule.addRule which was deprecated anyway
FEATURE: implemented @page CSSRule including testcases
FEATURE: implemented CSSRule.parentStyleSheet for all rules
FEATURE: implemented CSSRule.parentRule for relevant rules (all allowed in @media)
BUGFIX: Set parentStyleSheet and parentRule as instance vars in css.CSSRule instead as class vars
BUGFIX: CSSComment raised exception if setting cssText with empty string - fixed
DOCS: generated docs with epydoc which are then included in src dist. Source documentation is cleaned up a bit.
INTERNAL: Refactored some unittests
INTERNAL: implementation based on DOM Level 2 Style Recommendation as opposed to the Proposed Recommendation now. As there are no main changes I could find this does not make any difference...
CHANGE, renamed Serializer.prefs.srcatkeyword to Serializer.prefs.normalkeyword which work just the other way round but work as Serializer.prefs.normalpropertyname
BUGFIX in css.Selector and added support regarding handling of pseudoclasses (:x or :x()) and pseudoelements ::x
added Serializer.prefs.normalpropertyname, if True, property names are normalized if known (color), else literal form from CSS src is used (e.g. c\olor). Defaults to True.
removed Token.literal which value is in value now, normalized value is in normalvalue
removed Token.ESCAPE. Escapes are contained in IDENTifiers now.
internal change: WS is generally kept by tokenizer now, former normalized value u' ' is hold in Token.normalvalue. Serializer does not use it yet and some classes (like Selector) use normalvalue.
uses normalized form of @keyword in source CSS if True (e.g. @import), else literal form in CSS sourcefile (e.g. @i\mport). Defaults to True.
NEW Serializer.prefs.keepcomments removes all comments if False, defaults to True
NEW Serializer.prefs.srcatkeyword UPDATE see 9.91a1
fixed tokenizer to handle at least simple escapes like c\olor which is the same as color. The original value is preserved but not used yet except in CSSComments which preserve the original values. See also Serializer.prefs.srcatkeywords
setting of CSSImportRule.media removed, use methods of this object directly. Synchronized with CSSMediaRule.media
Synchronized with CSSMediaRule.insertRule
CSSStyleDeclaration bugfixes in parsing invalid tokens
stylesheets.MediaList bugfixes in parsing uppercase media values like PRINT
added more unittests (CSSMediaRule)
various bugfixes
atrules have a new property atkeyword which is the keyword used in the CSS provided. Normally something like "@import" but may also be an escaped version like "@import" or a custom one used in CSSUnknownRule.
(CSS3 see http://www.w3.org/TR/css3-selectors)
Improved parsing of "Unexpected end of string" according to spec
fixed serializing of CSSUnknownRule if valid == False
Properties may also be set with a numeric value now, before everything had to be a string. Direct use of _Property is discouraged though as it may well be changed again in a future version.
moved SelectorList, Selector and Property to own modules. Should not be used directly yet anyway.
Token: renamed IMPORTANT to IMPORTANT_SYM
refined EasyInstall (still some issues to be done)
NOT COMPLETE YET, E.G. BOM HANDLING
added tests for setting empty cssText for all @rules and CSSStyleRule
added new class cssutils.serialize.Preferences to control output or CSSSerializer
subpackages css and stylesheets are directly available from cssutils now
renamed module cssutils.cssparser to cssutils.parse which should not be used directly anyway. Always use cssutils.CSSParser or cssutils.parse (s.b)
added utility functions parse(cssText) and parse(filename, encoding='utf-8') to cssutils main package which work like the CSSParser functions with the same name and API
return value of .cssText is u'' and not None if empty now
from cssutils import *
cssutils has a property "ser" which is used by all classes to serialize themselves it is definable with a custom instance of cssutils.Serializer by setting cssutils.setCSSSerializer(newserializer)
usage of *.getFormatted emits DeprecationWarning now and returns *.cssText
lots of bugfixes and refactoring of modules, classes
extension and refactoring of unittests
renamed module "comment" to "csscomment" and class "Comment" to "CSSComment"
configurable Serializer instead of pprint
reimplemented CSSMediaRule
cssutils.css.CSSStyleSheet defines literalCssText property if property cssText is set. This is the unparsed cssText and might be different to cssText e.g. in case of parser errors.
custom log for CSSparser should work again
cssparser.py filename.css [encoding[, "debug"]] 1. encoding of the filename.css to parse 2. if called with "debug" debugging mode is enabled and default log prints all messages
cssutils.css.CSSUnknownRule reintegrated and Tests added
implements css.CSSRule, there a new typevalue COMMENT (=-1) is added
lexer does handle strings almost right now...
bugfixes
simplified lexer, still lots of simplification todo
new package cssutils.css which contains CSS interface implementations (css.CSSStyleSheet, css.CSSRuleList etc)
new package cssutils.stylesheets which contains Stylesheets interface implementations are in (stylesheets.StyleSheet, stylesheets.MediaList etc)
module cssutils.cssbuilder has therefor been removed and is replaced by packages cssutils.css and cssutils.stylesheets. (You may like to define your own cssbuilder module which imports all new classes with their old name if you do not want to change all your code at this time. Usage of the new names is recommended however and there are more subtle changes.)
CSS interfaces use W3 DOM names normally starting with CSS... now (e.g. CSSStyleSheet)
CSSStyleSheet now uses superclass stylesheets.StyleSheet
CSSImportRule is changed to comply to its specification (MediaList is after the URI and not before)
CSSFontfaceRule (cssutils FontfaceRule) is removed as CSS 2.1 removed this @ rule completely
CSSProperties is removed. Properties are useful in CSSStyleDeclaration only anyway and are used through that class now.
some parameters have been renamed to their respective DOM names (e.g. selector is selectorText now in CSSStyleRule constructor
Comment as a rule is removed currently, might be reintegrated in a future version.
some classes which have not been implemented fully anyway are not available until they are finished. This is mainly CSSMediaRule (will follow shortly), CSSUnknownRule, CSSValue and other value classes.
added modules to validate Properties and Values thanks to Kevin D. Smith
MediaList renamed media type "speech" to "aural"
API CHANGES
addProperty made/named private DEPRECATED anyway, use setProperty
parentRule raises NotImplementedError
RGBColor Implemented PrimitiveValue uses RGBColor
CSSParser uses setProperty instead of addProperty now StyleDeclaration, Value, ValueList, PrimitiveValue, RGBcolor done comparing spec and module docstrings
made list of TODOs
implement *Rule.cssText setting (UnknownRule not complete)
lexer has no log anymore, simply "logs" everything to the resulting tokenlist
cssstylesheet simplified
bugfixes
cssnormalizer renamed, does not work anyway at the moment
implemented StyleRule.cssText setting
cssproperties.Property has new init param raiseExceptions similar to the one of CSSParser. does not log yet and functionality might change as well * what will not change is that you can specify not officially specified properties (like moz-opacity etc)
some cleanup in various classes
simplified and cleaned up sources some bugfixes
test_cssrule test_csscharsetrule, test_cssfontfacerule, test_cssimportrule,
added unittest for __init__ module
!cssnormalizer does not work in this version - on hold for 1.0
new cssunknownrule.UnknownRule (moved out of module cssrule) parser now creates Unknown At-Rules in the resulting StyleSheet. they are no longer just dumped and reported in the parser log.
!cssnormalizer does not work in this version - on hold for 1.0
!cssnormalizer does not work in this version - on hold for 1.0
API CHANGES cssrule.SimpleAtRule DEPRECATED and empty cssmediarule.MediaRule init param "medias" renamed to "media" use subclasses of CSSRule (CharsetRule, ImportRule, FontFaceRule or PageRule) instead StyleRule constructor can be called with arguments (again...) Comment attribute "comment" renamed to "text"
implemented at least partly almost all DOM Level 2 CSS interfaces now so the API should be more stable from now on
new statemachine and lexer helper classes for parsing complete rewrite of CSSParser CSSParser and lexer put all error messages in a log now you might give your own log for messages CSSParser might be configured just to log errors or to raise xml.dom.DOMExceptions when finding an error
!cssnormalizer does not work in this version - on hold for 1.0
API CHANGES StyleSheet.getRules() returns a RuleList now class Selector removed, integrated into Rules now
!cssnormalizer does not work in this version
API CHANGES: cssbuilder.RuleList subclasses list cssbuilder.Selector moved to cssrules attribute style of class StyleRule made private (_style) removed StyleRule.clearStyleDeclaration attribute selectorlist of class Selector renamed to _selectors and made private
NEW: MediaList class
moved tests to directory test
made a dist package complete with setup.py
!cssnormalizer does not work in this version
API CHANGES: StyleDeclaration.addProperty is now DEPRECATED use StyleDeclaration.setProperty instead
removed cssexception module removed csscomment module, classes now directly in cssutils
more unittests, start with python cssutils/_test.py
more docs
integrated patches by Cory Dodt for SGML comments and Declaration additions added some w3c DOM methods
severe API changes renamed some classes to (almost) DOM names, the CSS prefix of DOM names is ommited though
the according methods are renamed as well
class hierarchy is changed as well, please see the example
classes are organized in new modules
and no comment end delimiter. (before it had to be a complete css comment including delimiters)
validates given media types new method: addMediaType(media_type)
cssparser updated to new cssbuilder interface and logic started unittests (v0.0.0.1..., not included yet)
new CSSNormalizer.normalizeDeclarationOrder(stylesheet)
cssbuilder: added methods needed by CSSNormalizer
CSSParser.parse bugfix
0.10 - 031221 first version to try if i can bring it to work at all
only a prettyprinter included, no builder