Author: | cthedot |
---|---|
Copyright: | 2004-2007 Christof Hoeke |
Date: | 2007-11-06 22:22:15 +0100 (Di, 06 Nov 2007) |
Version: | (rev 649) |
cssparse script does not work correctly in version 0.9.4 yet.
css.UnknownRule is not handled properly in cases, tests are spotty there too. it also seems to have been removed in CSSOM but seems useful so is still present
Some methods of css.CSSPrimitiveValue and subclasses Rect, Counter and RGBColor are not yet implemented. As CSSOM defines a completely different DOM for Property values they may never be implemented as defined in DOM Level 2.
CSS2Properties not implemented completely (setting a property does not set related properties like setting margin does not set margin-left etc) (0.9.5 but again as CSSOM defined something else this may change))
Preferences.removeInvalid, .validOnly and .wellformedOnly are in experimental stage, the first option will probably removed (maybe even in the final 0.9.4 release), so use sparingly. If you need these functionality or have suggestions what you like the lib to behave contact me.
Properties are not bound to any CSS Version, so all properties are handled so NOT as described in http://www.w3.org/TR/CSS21/syndata.html#parsing-errors "Illegal values". (A future version might be customizable to a specific CSS version like 2.1 or 3)
although cssutils tries to preserve CSS hacks not all are yet (and some probably will never be). The following hacks are known to not (yet) be preserved:
*html without any whitespace
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.
TODO
- CSSParse
- use codec
- CSSCapture:
- for all stuff, use order of specific things (HTTP Header, @charset , ... )
- save inline styles in same folder as all other sheets
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
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