========================
package ``cssutils.css``
========================

.. module:: cssutils.css

Classes implementing `DOM Level 2 CSS <http://www.w3.org/TR/DOM-Level-2-Style/css.html>`_ and `CSS Module: Namespaces (W3C Working Draft 28 August 2006) <http://www.w3.org/TR/css3-namespace/>`_



``CSSStyleSheet``
=================

A CSSStyleSheet contains all rules. It consists of the different CSS rules like :class:`~cssutils.css.CSSImportRule`, :class:`~cssutils.css.CSSStyleRule` etc. It also defines the encoding of the style sheet used for serialization. The encoding might by set with an :class:`~cssutils.css.CSSCharsetRule` rule or simpler with the :attr:`~cssutils.css.CSSStyleSheet.encoding` attribute. The serialized sheet may be obtained from :attr:`~cssutils.css.CSSStyleSheet.cssText`. All rules are present in :attr:`~cssutils.css.CSSStyleSheet.cssRules`, a stylesheet iterates on its rules so this might be easier. Namespaces are available via :attr:`~cssutils.css.CSSStyleSheet.namespaces` (do not rely on prefixes, see http://www.w3.org/TR/REC-xml-names/ how these work).


.. autoclass:: cssutils.css.CSSStyleSheet
   :members:
   :inherited-members:

CSS rules: @rules and ``CSSStyleRule``
======================================

CSSRuleList
-----------
.. autoclass:: cssutils.css.CSSRuleList
   :members:
   :inherited-members:

CSSRule
-------
.. autoclass:: cssutils.css.CSSRule
   :members:
   :inherited-members:


CSSCharsetRule
--------------
.. autoclass:: cssutils.css.CSSCharsetRule
   :members:
   :inherited-members:

CSSComment
----------
.. autoclass:: cssutils.css.CSSComment
   :members:
   :inherited-members:

CSSNamespaceRule
----------------
.. autoclass:: cssutils.css.CSSNamespaceRule
   :members:
   :inherited-members:

CSSImportRule
-------------
.. autoclass:: cssutils.css.CSSImportRule
   :members:
   :inherited-members:

CSSMediaRule
------------
.. autoclass:: cssutils.css.CSSMediaRule
   :members:
   :inherited-members:

CSSFontFaceRule
---------------
.. autoclass:: cssutils.css.CSSFontFaceRule
   :members:
   :inherited-members:

CSSPageRule
-----------
.. autoclass:: cssutils.css.CSSPageRule
   :members:
   :inherited-members:

CSSStyleRule
------------
.. autoclass:: cssutils.css.CSSStyleRule
   :members:
   :inherited-members:



Selector related classes: ``SelectorList`` and ``Selector``
===========================================================

SelectorList
------------
.. autoclass:: cssutils.css.SelectorList
   :members:
   :inherited-members:

Selector
--------
.. autoclass:: cssutils.css.Selector
   :members:
   :inherited-members:



Style related classes: ``CSSStyleDeclaration``, ``Property``, ``CSSValue`` etc
==============================================================================================


CSSStyleDeclaration
-------------------
.. autoclass:: cssutils.css.CSSStyleDeclaration
   :members:
   :inherited-members:

The official DOM provides no method to obtain all values set for a property. Cssutils from 0.9.4 implements the additional method :meth:`~cssutils.css.CSSStyleDeclaration.getProperties`, example::

    >>> cssText = '''background: white url(paper.png) scroll; /* for all UAs */
    ... background: white url(ledger.png) fixed; /* for UAs that do fixed backgrounds */
    ... '''
    >>> # omit comments for this example
    >>> cssutils.ser.prefs.keepComments = False
    >>> style = cssutils.css.CSSStyleDeclaration(cssText=cssText)
    >>> print style.cssText
    background: white url(paper.png) scroll;
    background: white url(ledger.png) fixed;
    >>> # work with properties:
    >>> proplist = style.getProperties('background', all=True)
    >>> proplist
    [cssutils.css.Property(name='background', value=u'white url(paper.png) scroll', priority=u''), cssutils.css.Property(name='background', value=u'white url(ledger.png) fixed', priority=u'')]
    >>> for prop in proplist: print prop.value
    white url(paper.png) scroll
    white url(ledger.png) fixed
    >>> # overwrite the current property, to overwrite all iterate over proplist
    >>> style['background'] = ('red', '!important')
    >>> # importance in DOM ist 'important' but '!important' works too
    >>> print style['background'], style.getPropertyPriority('background')
    red important
    >>> print style.cssText
    background: white url(paper.png) scroll;
    background: red !important;
    >>> # output only "effective" properties
    >>> cssutils.ser.prefs.keepAllProperties = False
    >>> print style.cssText
    background: red !important;


Property
--------
.. autoclass:: cssutils.css.Property
   :members:
   :inherited-members:


Values
------

CSSValue
~~~~~~~~
.. autoclass:: cssutils.css.CSSValue
    :members:
    :inherited-members:

CSSPrimitiveValue
~~~~~~~~~~~~~~~~~
.. autoclass:: cssutils.css.CSSPrimitiveValue
    :members:
    :inherited-members:

CSSValueList
~~~~~~~~~~~~
.. autoclass:: cssutils.css.CSSValueList
    :members:
    :inherited-members:


CSSFunction
~~~~~~~~~~~
.. autoclass:: cssutils.css.cssvalue.CSSFunction
    :members:

..
    RGBColor
    ~~~~~~~~
    .. autoclass:: cssutils.css.RGBColor
        :members:
        :inherited-members:

ExpressionValue
~~~~~~~~~~~~~~~
.. autoclass:: cssutils.css.cssvalue.ExpressionValue
    :members:


Additional Info
===============
Some classes in this package support standard Python idioms like iteration on certain attributes::

    >>> import cssutils
    >>> sheet = cssutils.css.CSSStyleSheet()
    >>> sheet.cssText = '@charset "ascii";a { color: green }'
    >>> for rule in sheet:
    ...     print rule
    ...
    <cssutils.css.CSSCharsetRule object encoding='ascii' at 0x2ce7
    <cssutils.css.CSSStyleRule object selector=u'a' style=u'color:
    s=<cssutils.util._Namespaces object at 0x02CE7B30> at 0x2ce7d3

``for in`` is supported by :class:`~cssutils.css.CSSStyleSheet` and  :class:`~cssutils.css.CSSMediaRule` (iterating over the contained :class:`~cssutils.css.CSSRule` objects, :class:`~cssutils.css.CSSStyleDeclaration` (over the names of the contained :class:`~cssutils.css.Property` objects), :class:`~cssutils.css.CSSValueList` (over the :class:`~cssutils.css.CSSValue` objects in the list).


