profiles¶
cssutils.profile
¶
A global object cssutils.profile
is used for validation of all properties. It is an instance of cssutils.profiles.Profiles
. Add or remove new profile definitions here.
Most important method is cssutils.profiles.Profiles.addProfile()
(use cssutils.profile.addProfile
) to add new properties to cssutils and the setting of defaultProfiles
.
Example of how to add a new profile:
>>> import cssutils
>>> sheet = cssutils.parseString('x { -test-custommacro: x }')
>>> print sheet.cssRules[0].style.getProperties()[0].valid
False
>>> M1 = {
... 'testvalue': 'x'
... }
>>> P1 = {
... '-test-tokenmacro': '({num}{w}){1,2}',
... '-test-macro': '{ident}|{percentage}',
... '-test-custommacro': '{testvalue}',
... # custom validation function
... '-test-funcval': lambda(v): int(v) > 0
... }
>>> cssutils.profile.addProfile('test', P1, M1)
>>> sheet = cssutils.parseString('x { -test-custommacro: x }')
>>> print sheet.cssRules[0].style.getProperties()[0].valid
True
An additional per CSSStyleSheet setting of a profile may be added soon.
Please note: This might change again, but only slightly as it has been refactored in 0.9.6a2.
cssutils.profiles.macros
and cssutils.profiles.properties
¶
Two dictionaries which contain macro and property definitions for the predefined property profiles.
Both use the additional macros defined in Profiles._TOKEN_MACROS
and Profiles._MACROS
which contain basic macros for definition of new properties. Things like ident, name or hexcolor are defined there and may be used in any new property definition as these two macro sets defined in Profiles
are added to any custom macro definition given. You may overwrite these basic macros with your own macros or simply define your own macros and use only these.
Use cssutils.profiles.macros
if you need any other predefined macro or cssutils.profiles.properties
if you want to add any known property to your custom property profile.
cssutils.profiles.Profiles
¶
- class cssutils.profiles.Profiles(log=None)¶
All profiles used for validation.
cssutils.profile
is a preset object of this class and used by all properties for validation.Predefined profiles are (use
propertiesByProfile()
to get a list of defined properties):~cssutils.profiles.Profiles.CSS_LEVEL_2
Properties defined by CSS2.1
~cssutils.profiles.Profiles.CSS3_BASIC_USER_INTERFACE
Currently resize and outline properties only
~cssutils.profiles.Profiles.CSS3_BOX
Currently overflow related properties only
~cssutils.profiles.Profiles.CSS3_COLOR
CSS 3 color properties
~cssutils.profiles.Profiles.CSS3_PAGED_MEDIA
As defined at http://www.w3.org/TR/css3-page/ (at 090307)
Predefined macros are:
~cssutils.profiles.Profiles._TOKEN_MACROS
Macros containing the token values as defined to CSS2
~cssutils.profiles.Profiles._MACROS
Additional general macros.
If you want to redefine any of these macros do this in your custom macros.
- addProfile(profile, properties, macros=None)¶
Add a new profile with name profile (e.g. ‘CSS level 2’) and the given properties.
- Parameters:
profile – the new profile’s name
properties –
a dictionary of
{ property-name: propery-value }
items where property-value is a regex which may use macros defined in givenmacros
or the standard macros Profiles.tokens and Profiles.generalvalues.propery-value
may also be a function which takes a single argument which is the value to validate and which should return True or False. Any exceptions which may be raised during this custom validation are reported or raised as all other cssutils exceptions depending on cssutils.log.raiseExceptions which e.g during parsing normally is False so the exceptions would be logged only.macros – may be used in the given properties definitions. There are some predefined basic macros which may always be used in
Profiles._TOKEN_MACROS
andProfiles._MACROS
.
- addProfiles(profiles)¶
Add a list of profiles at once. Useful as if profiles define custom macros these are used in one go. Using addProfile instead my be very slow instead.
- property defaultProfiles¶
Names of profiles to use for validation.To use e.g. the CSS2 profile set
cssutils.profile.defaultProfiles = cssutils.profile.CSS_LEVEL_2
- property knownNames¶
All known property names of all profiles.
- property profiles¶
Names of all profiles in order as defined.
- propertiesByProfile(profiles=None)¶
Generator: Yield property names, if no profiles is given all profile’s properties are used.
- Parameters:
profiles – a single profile name or a list of names.
- removeProfile(profile=None, all=False)¶
Remove profile or remove all profiles.
If the removed profile used custom macros all remaining profiles are reset to reflect the macro changes. This may be quite an expensive operation!
- Parameters:
profile – profile name to remove
all – if
True
removes all profiles to start with a clean state
- Exceptions:
cssutils.profiles.NoSuchProfileException
: If given profile cannot be found.
- validate(name, value)¶
Check if value is valid for given property name using any profile.
- Parameters:
name – a property name
value – a CSS value (string)
- Returns:
if the value is valid for the given property name in any profile
- validateWithProfile(name, value, profiles=None)¶
Check if value is valid for given property name returning
(valid, profile)
.- Parameters:
name – a property name
value – a CSS value (string)
profiles – internal parameter used by Property.validate only
- Returns:
valid, matching, profiles
wherevalid
is if the value is valid for the given property name in any profile,matching==True
if it is valid in the given profiles andprofiles
the profile names for which the value is valid (or[]
if not valid at all)
Example:
> cssutils.profile.defaultProfiles = cssutils.profile.CSS_LEVEL_2 > print(cssutils.profile.validateWithProfile('color', 'rgba(1,1,1,1)')) (True, False, Profiles.CSS3_COLOR)