Permalink
Browse files

Update the documentation for 0.2

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

0 comments on commit c52dab0

Please sign in to comment.