Skip to content
This repository
Browse code

Update the documentation for 0.2

  • Loading branch information...
commit c52dab00d027c23309e46726b9f4cb7a3f58f4e3 1 parent dfad9fc
Simon Sapin authored
49 CHANGES
... ... @@ -1,34 +1,40 @@
1   -Planned
2   -=======
3   -
4   -* Give the docs some love
5   -* Implement :target, :hover, :focus and :active as never matching
6   -* Make a new HTML-specific Translator subclass. There, implement :enabled,
7   - :disabled, :link and :visited (with all links "not visited").
8   -* Move :checked to the new HTMLTranslator, make it unsupported for
9   - "generic" XML.
  1 +Changelog
  2 +=========
  3 +
  4 +Planned changes
  5 +---------------
  6 +
  7 +* Implement ``:target``, ``:hover``, ``:focus`` and ``:active``
  8 + as never matching
  9 +* Make a new HTML-specific ``Translator`` subclass. There, implement
  10 + ``:enabled``, ``:disabled``, ``:link`` and ``:visited``
  11 + (with all links "not visited"). Move ``:checked`` to this new
  12 + ``HTMLTranslator``
  13 +* Make all of these never match for "generic" XML. (Unless otherwise specified,
  14 + there is no link, checkbox, etc.)
10 15 * Add some support for pseudo-elements by separating them from the
11 16 rest of the selector.
12 17 * Add specificity calculation.
13 18
14   -Discussion is open if anyone is interested in implementing eg. :target or
15   -:visited differently, but they can always do it in a Translator subclass.
  19 +Discussion is open if anyone is interested in implementing eg. ``:target``
  20 +or ``:visited`` differently, but they can always do it in a ``Translator``
  21 +subclass.
16 22
17 23
18 24 Version 0.2
19   -===========
  25 +-----------
20 26
21 27 Not released yet.
22 28
23   -* Remove the CSSSelector class. (The css_to_xpath function is now the
24   - main API.)
  29 +* Remove the ``CSSSelector`` class. (The ``css_to_xpath()`` function is now
  30 + the main API.)
25 31 * Remove support for the ``:contains()`` pseudo-class.
26 32
27 33 These changes allow cssselect to be used without lxml. (Hey, this was
28 34 the whole point of this project.) The tests still require lxml, though.
29 35 The removed parts are expected to stay in lxml for backward-compatibility.
30 36
31   -:contains() only existed in an `early draft
  37 +``:contains()`` only existed in an `early draft
32 38 <http://www.w3.org/TR/2001/CR-css3-selectors-20011113/#content-selectors>`_
33 39 of the Selectors specification, and was removed before Level 3 stabilized.
34 40 Internally, it used a custom XPath extension function which can be
@@ -36,22 +42,21 @@ difficult to express outside of lxml.
36 42
37 43
38 44 * Separate the XPath translation from the parsed objects into a new
39   - Translator class.
40   -* Make css_to_xpath() accept a Translator instance as a parameter.
  45 + ``Translator`` class.
41 46
42   -Subclasses of Translator can be made to change the way that some selector
  47 +Subclasses of ``Translator`` can be made to change the way that some selector
43 48 (eg. a pseudo-class) is implemented.
44 49
45 50
46 51 Version 0.1
47   -===========
  52 +-----------
48 53
49 54 Released on 2012-04-13.
50 55
51 56 Extract lxml.cssselect from the rest of lxml and make it a stand-alone project.
52 57
53   -The 'master' branch from lxml’s git repository was taken on 2012-04-11
54   -(commit ea53ceaf7e44ba4fbb5c818ae31370932f47774e). This is somewhere
  58 +Commit ``ea53ceaf7e44ba4fbb5c818ae31370932f47774e`` was taken on 2012-04-11
  59 +from the 'master' branch of lxml’s git repository. This is somewhere
55 60 between versions 2.3.4 and 2.4.
56 61
57 62 The commit history has been rewritten to:
@@ -65,7 +70,7 @@ code itself is unchanged and still depends on lxml.
65 70
66 71
67 72 Earlier history
68   -===============
  73 +---------------
69 74
70 75 Search for *cssselect* in `lxml’s changelog
71 76 <https://github.com/lxml/lxml/blob/master/CHANGES.txt>`_
2  MANIFEST.in
... ... @@ -1,3 +1,3 @@
1   -include AUTHORS CHANGES LICENSE README tox.ini
  1 +include AUTHORS CHANGES LICENSE README.rst tox.ini
2 2 recursive-include docs *
3 3 prune docs/_build
111 README
... ... @@ -1,111 +0,0 @@
1   -=========
2   -cssselect
3   -=========
4   -
5   -`cssselect` is a parser for `CSS Selectors` Level 3 that can also translate
6   -selectors to `XPath 1.0`_ queries. Such queries can be used in lxml_ to find
7   -the matching elements in an XML or HTML document.
8   -
9   -This module used to live inside of lxml as ``lxml.cssselect`` before it was
10   -extracted as a stand-alone project.
11   -
12   -.. _CSS Selectors: http://www.w3.org/TR/selectors/
13   -.. _XPath 1.0: http://www.w3.org/TR/xpath/
14   -.. _lxml: http://lxml.de/
15   -
16   -
17   -.. contents::
18   -..
19   - 1 The CSSSelector class
20   - 2 CSS Selectors
21   - 2.1 Namespaces
22   - 3 Limitations
23   -
24   -
25   -The CSSSelector class
26   -=====================
27   -
28   -The most important class in the ``cssselect`` module is ``CSSSelector``. It
29   -provides the same interface as lxml’s XPath_ class, but accepts a CSS selector
30   -expression as input:
31   -
32   -.. _XPath: http://lxml.de/xpathxslt.html#xpath
33   -
34   -.. sourcecode:: pycon
35   -
36   - >>> from cssselect import CSSSelector
37   - >>> sel = CSSSelector('div.content')
38   - >>> sel #doctest: +ELLIPSIS
39   - <CSSSelector ... for 'div.content'>
40   - >>> sel.css
41   - 'div.content'
42   -
43   -The selector actually compiles to XPath, and you can see the
44   -expression by inspecting the object:
45   -
46   -.. sourcecode:: pycon
47   -
48   - >>> sel.path
49   - "descendant-or-self::div[contains(concat(' ', normalize-space(@class), ' '), ' content ')]"
50   -
51   -To use the selector, simply call it with a document or element
52   -object:
53   -
54   -.. sourcecode:: pycon
55   -
56   - >>> from lxml.etree import fromstring
57   - >>> h = fromstring('''<div id="outer">
58   - ... <div id="inner" class="content body">
59   - ... text
60   - ... </div></div>''')
61   - >>> [e.get('id') for e in sel(h)]
62   - ['inner']
63   -
64   -
65   -CSS Selectors
66   -=============
67   -
68   -This libraries attempts to implement CSS selectors `as described in
69   -the w3c specification
70   -<http://www.w3.org/TR/2001/CR-css3-selectors-20011113/>`_. Many of
71   -the pseudo-classes do not apply in this context, including all
72   -`dynamic pseudo-classes
73   -<http://www.w3.org/TR/2001/CR-css3-selectors-20011113/#dynamic-pseudos>`_.
74   -In particular these will not be available:
75   -
76   -* link state: ``:link``, ``:visited``, ``:target``
77   -* actions: ``:hover``, ``:active``, ``:focus``
78   -* UI states: ``:enabled``, ``:disabled``, ``:indeterminate``
79   - (``:checked`` and ``:unchecked`` *are* available)
80   -
81   -Also, none of the pseudo-elements apply, because the selector only
82   -returns elements and pseudo-elements select portions of text, like
83   -``::first-line``.
84   -
85   -
86   -Namespaces
87   -==========
88   -
89   -In CSS you can use ``namespace-prefix|element``, similar to
90   -``namespace-prefix:element`` in an XPath expression. In fact, it maps
91   -one-to-one, and the same rules are used to map namespace prefixes to
92   -namespace URIs.
93   -
94   -
95   -Limitations
96   -===========
97   -
98   -These applicable pseudoclasses are not yet implemented:
99   -
100   -* ``:lang(language)``
101   -* ``*:first-of-type``, ``*:last-of-type``, ``*:nth-of-type``,
102   - ``*:nth-last-of-type``, ``*:only-of-type``. All of these work when
103   - you specify an element type, but not with ``*``
104   -
105   -Unlike XPath you cannot provide parameters in your expressions -- all
106   -expressions are completely static.
107   -
108   -XPath has underspecified string quoting rules (there seems to be no
109   -string quoting at all), so if you use expressions that contain
110   -characters that requiring quoting you might have problems with the
111   -translation from CSS to XPath.
25 README.rst
Source Rendered
... ... @@ -0,0 +1,25 @@
  1 +===================================
  2 +cssselect: CSS Selectors for Python
  3 +===================================
  4 +
  5 +*cssselect* parses `CSS3 Selectors`_ and translate them to `XPath 1.0`_
  6 +expressions. Such expressions can be used in lxml_ or another XPath engine
  7 +to find the matching elements in an XML or HTML document.
  8 +
  9 +This module used to live inside of lxml as ``lxml.cssselect`` before it was
  10 +extracted as a stand-alone project.
  11 +
  12 +.. _CSS3 Selectors: http://www.w3.org/TR/2011/REC-css3-selectors-20110929/
  13 +.. _XPath 1.0: http://www.w3.org/TR/xpath/
  14 +.. _lxml: http://lxml.de/
  15 +
  16 +
  17 +Quick facts:
  18 +
  19 +* Free software: BSD licensed
  20 +* Compatible with Python 2.4+ and 3.x
  21 +* Latest documentation `on python.org <http://packages.python.org/cssselect/>`_
  22 +* Source, issues and pull requests `on Github
  23 + <https://github.com/SimonSapin/cssselect/>`_
  24 +* Releases `on PyPI <http://pypi.python.org/pypi/cssselect>`_
  25 +* Install with ``pip install cssselect``
21 cssselect/xpath.py
@@ -171,6 +171,27 @@ def css_to_xpath(self, css, prefix='descendant-or-self::'):
171 171 :param css: An Unicode string or a parsed selector object.
172 172 :returns: An Unicode string.
173 173
  174 + .. sourcecode:: pycon
  175 +
  176 + >>> from cssselect import css_to_xpath
  177 + >>> exrpession = css_to_xpath('div.content')
  178 + >>> exrpession
  179 + "descendant-or-self::div[contains(concat(' ', normalize-space(@class), ' '), ' content ')]"
  180 +
  181 + The resulting expression can be used with lxml’s `XPath engine`_:
  182 +
  183 + .. _XPath engine: http://lxml.de/xpathxslt.html#xpath
  184 +
  185 + .. sourcecode:: pycon
  186 +
  187 + >>> from lxml.etree import fromstring
  188 + >>> document = fromstring('''<div id="outer">
  189 + ... <div id="inner" class="content body">
  190 + ... text
  191 + ... </div></div>''')
  192 + >>> [e.get('id') for e in document.xpath(expression)]
  193 + ['inner']
  194 +
174 195 """
175 196 if isinstance(css, _basestring):
176 197 selector = parse(css)
4 docs/conf.py
@@ -27,7 +27,7 @@
27 27 # Add any Sphinx extension module names here, as strings. They can be extensions
28 28 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
29 29 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
30   - 'sphinx.ext.viewcode', 'sphinx.ext.doctest']
  30 + 'sphinx.ext.doctest']
31 31
32 32 # Add any paths that contain templates here, relative to this directory.
33 33 templates_path = ['_templates']
@@ -122,7 +122,7 @@
122 122 # Add any paths that contain custom static files (such as style sheets) here,
123 123 # relative to this directory. They are copied after the builtin static files,
124 124 # so a file named "default.css" will overwrite the builtin "default.css".
125   -html_static_path = ['_static']
  125 +#html_static_path = ['_static']
126 126
127 127 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
128 128 # using the given strftime format.
54 docs/index.rst
Source Rendered
... ... @@ -1 +1,53 @@
1   -.. include:: ../README
  1 +.. include:: ../README.rst
  2 +
  3 +User API
  4 +========
  5 +
  6 +.. module:: cssselect
  7 +
  8 +Currently, the only public API is the ``css_to_xpath()`` function. This API
  9 +expected to expand to provide more information about the parsed selectors,
  10 +and to allow customization of the translation.
  11 +
  12 +.. autofunction:: css_to_xpath(css, prefix='descendant-or-self::')
  13 +
  14 +
  15 +Namespaces
  16 +==========
  17 +
  18 +In CSS you can use ``namespace-prefix|element``, similar to
  19 +``namespace-prefix:element`` in an XPath expression. In fact, it maps
  20 +one-to-one. How prefixes are mapped to namespace URIs depends on the
  21 +XPath implementation.
  22 +
  23 +
  24 +Limitations and supported selectors
  25 +===================================
  26 +
  27 +This library attempts to implement CSS3 selectors as described in
  28 +`the W3C specification
  29 +<http://www.w3.org/TR/2011/REC-css3-selectors-20110929/>`_. Some of
  30 +the pseudo-classes do not apply in this context.
  31 +In particular these will not be available:
  32 +
  33 +* link state: ``:link``, ``:visited``, ``:target``
  34 +* actions: ``:hover``, ``:active``, ``:focus``
  35 +* UI states: ``:enabled``, ``:disabled`` (``:checked`` *is* available)
  36 +
  37 +Also, none of the pseudo-elements apply since XPath only knows about “real”
  38 +elements.
  39 +
  40 +
  41 +These applicable pseudoclasses are not yet implemented:
  42 +
  43 +* ``:lang(language)``
  44 +* ``*:first-of-type``, ``*:last-of-type``, ``*:nth-of-type``,
  45 + ``*:nth-last-of-type``, ``*:only-of-type``. All of these work when
  46 + you specify an element type, but not with ``*``
  47 +
  48 +XPath has underspecified string quoting rules (there seems to be no
  49 +string quoting at all), so if you use expressions that contain
  50 +characters that requiring quoting you might have problems with the
  51 +translation from CSS to XPath.
  52 +
  53 +.. include:: ../CHANGES
8 setup.py
@@ -2,7 +2,7 @@
2 2 from setuptools import setup
3 3
4 4
5   -README = open(os.path.join(os.path.dirname(__file__), 'README')).read()
  5 +README = open(os.path.join(os.path.dirname(__file__), 'README.rst')).read()
6 6
7 7
8 8 setup(
@@ -12,14 +12,14 @@
12 12 author_email='ianb@colorstudy.com',
13 13 maintainer='Simon Sapin',
14 14 maintainer_email='simon.sapin@exyr.org',
15   - description='cssselect is a parser for CSS Selectors that can translate '
16   - 'to XPath 1.0',
  15 + description=
  16 + 'cssselect parses CSS3 Selectors and translates them to XPath 1.0',
17 17 long_description=README,
18 18 url='http://packages.python.org/cssselect/',
19 19 license='BSD',
20 20 install_requires='lxml',
21 21 packages=['cssselect'],
22   - test_suite='test_cssselect',
  22 + test_suite='cssselect.tests',
23 23 classifiers=[
24 24 'Development Status :: 4 - Beta',
25 25 'Intended Audience :: Developers',

0 comments on commit c52dab0

Please sign in to comment.
Something went wrong with that request. Please try again.