|
"""Integration code for CSS selectors using Soup Sieve (pypi: soupsieve).""" |
|
|
|
import warnings |
|
try: |
|
import soupsieve |
|
except ImportError as e: |
|
soupsieve = None |
|
warnings.warn( |
|
'The soupsieve package is not installed. CSS selectors cannot be used.' |
|
) |
|
|
|
|
|
class CSS(object): |
|
"""A proxy object against the soupsieve library, to simplify its |
|
CSS selector API. |
|
|
|
Acquire this object through the .css attribute on the |
|
BeautifulSoup object, or on the Tag you want to use as the |
|
starting point for a CSS selector. |
|
|
|
The main advantage of doing this is that the tag to be selected |
|
against doesn't need to be explicitly specified in the function |
|
calls, since it's already scoped to a tag. |
|
""" |
|
|
|
def __init__(self, tag, api=soupsieve): |
|
"""Constructor. |
|
|
|
You don't need to instantiate this class yourself; instead, |
|
access the .css attribute on the BeautifulSoup object, or on |
|
the Tag you want to use as the starting point for your CSS |
|
selector. |
|
|
|
:param tag: All CSS selectors will use this as their starting |
|
point. |
|
|
|
:param api: A plug-in replacement for the soupsieve module, |
|
designed mainly for use in tests. |
|
""" |
|
if api is None: |
|
raise NotImplementedError( |
|
"Cannot execute CSS selectors because the soupsieve package is not installed." |
|
) |
|
self.api = api |
|
self.tag = tag |
|
|
|
def escape(self, ident): |
|
"""Escape a CSS identifier. |
|
|
|
This is a simple wrapper around soupselect.escape(). See the |
|
documentation for that function for more information. |
|
""" |
|
if soupsieve is None: |
|
raise NotImplementedError( |
|
"Cannot escape CSS identifiers because the soupsieve package is not installed." |
|
) |
|
return self.api.escape(ident) |
|
|
|
def _ns(self, ns, select): |
|
"""Normalize a dictionary of namespaces.""" |
|
if not isinstance(select, self.api.SoupSieve) and ns is None: |
|
|
|
|
|
|
|
ns = self.tag._namespaces |
|
return ns |
|
|
|
def _rs(self, results): |
|
"""Normalize a list of results to a Resultset. |
|
|
|
A ResultSet is more consistent with the rest of Beautiful |
|
Soup's API, and ResultSet.__getattr__ has a helpful error |
|
message if you try to treat a list of results as a single |
|
result (a common mistake). |
|
""" |
|
|
|
from bs4.element import ResultSet |
|
return ResultSet(None, results) |
|
|
|
def compile(self, select, namespaces=None, flags=0, **kwargs): |
|
"""Pre-compile a selector and return the compiled object. |
|
|
|
:param selector: A CSS selector. |
|
|
|
:param namespaces: A dictionary mapping namespace prefixes |
|
used in the CSS selector to namespace URIs. By default, |
|
Beautiful Soup will use the prefixes it encountered while |
|
parsing the document. |
|
|
|
:param flags: Flags to be passed into Soup Sieve's |
|
soupsieve.compile() method. |
|
|
|
:param kwargs: Keyword arguments to be passed into SoupSieve's |
|
soupsieve.compile() method. |
|
|
|
:return: A precompiled selector object. |
|
:rtype: soupsieve.SoupSieve |
|
""" |
|
return self.api.compile( |
|
select, self._ns(namespaces, select), flags, **kwargs |
|
) |
|
|
|
def select_one(self, select, namespaces=None, flags=0, **kwargs): |
|
"""Perform a CSS selection operation on the current Tag and return the |
|
first result. |
|
|
|
This uses the Soup Sieve library. For more information, see |
|
that library's documentation for the soupsieve.select_one() |
|
method. |
|
|
|
:param selector: A CSS selector. |
|
|
|
:param namespaces: A dictionary mapping namespace prefixes |
|
used in the CSS selector to namespace URIs. By default, |
|
Beautiful Soup will use the prefixes it encountered while |
|
parsing the document. |
|
|
|
:param flags: Flags to be passed into Soup Sieve's |
|
soupsieve.select_one() method. |
|
|
|
:param kwargs: Keyword arguments to be passed into SoupSieve's |
|
soupsieve.select_one() method. |
|
|
|
:return: A Tag, or None if the selector has no match. |
|
:rtype: bs4.element.Tag |
|
|
|
""" |
|
return self.api.select_one( |
|
select, self.tag, self._ns(namespaces, select), flags, **kwargs |
|
) |
|
|
|
def select(self, select, namespaces=None, limit=0, flags=0, **kwargs): |
|
"""Perform a CSS selection operation on the current Tag. |
|
|
|
This uses the Soup Sieve library. For more information, see |
|
that library's documentation for the soupsieve.select() |
|
method. |
|
|
|
:param selector: A string containing a CSS selector. |
|
|
|
:param namespaces: A dictionary mapping namespace prefixes |
|
used in the CSS selector to namespace URIs. By default, |
|
Beautiful Soup will pass in the prefixes it encountered while |
|
parsing the document. |
|
|
|
:param limit: After finding this number of results, stop looking. |
|
|
|
:param flags: Flags to be passed into Soup Sieve's |
|
soupsieve.select() method. |
|
|
|
:param kwargs: Keyword arguments to be passed into SoupSieve's |
|
soupsieve.select() method. |
|
|
|
:return: A ResultSet of Tag objects. |
|
:rtype: bs4.element.ResultSet |
|
|
|
""" |
|
if limit is None: |
|
limit = 0 |
|
|
|
return self._rs( |
|
self.api.select( |
|
select, self.tag, self._ns(namespaces, select), limit, flags, |
|
**kwargs |
|
) |
|
) |
|
|
|
def iselect(self, select, namespaces=None, limit=0, flags=0, **kwargs): |
|
"""Perform a CSS selection operation on the current Tag. |
|
|
|
This uses the Soup Sieve library. For more information, see |
|
that library's documentation for the soupsieve.iselect() |
|
method. It is the same as select(), but it returns a generator |
|
instead of a list. |
|
|
|
:param selector: A string containing a CSS selector. |
|
|
|
:param namespaces: A dictionary mapping namespace prefixes |
|
used in the CSS selector to namespace URIs. By default, |
|
Beautiful Soup will pass in the prefixes it encountered while |
|
parsing the document. |
|
|
|
:param limit: After finding this number of results, stop looking. |
|
|
|
:param flags: Flags to be passed into Soup Sieve's |
|
soupsieve.iselect() method. |
|
|
|
:param kwargs: Keyword arguments to be passed into SoupSieve's |
|
soupsieve.iselect() method. |
|
|
|
:return: A generator |
|
:rtype: types.GeneratorType |
|
""" |
|
return self.api.iselect( |
|
select, self.tag, self._ns(namespaces, select), limit, flags, **kwargs |
|
) |
|
|
|
def closest(self, select, namespaces=None, flags=0, **kwargs): |
|
"""Find the Tag closest to this one that matches the given selector. |
|
|
|
This uses the Soup Sieve library. For more information, see |
|
that library's documentation for the soupsieve.closest() |
|
method. |
|
|
|
:param selector: A string containing a CSS selector. |
|
|
|
:param namespaces: A dictionary mapping namespace prefixes |
|
used in the CSS selector to namespace URIs. By default, |
|
Beautiful Soup will pass in the prefixes it encountered while |
|
parsing the document. |
|
|
|
:param flags: Flags to be passed into Soup Sieve's |
|
soupsieve.closest() method. |
|
|
|
:param kwargs: Keyword arguments to be passed into SoupSieve's |
|
soupsieve.closest() method. |
|
|
|
:return: A Tag, or None if there is no match. |
|
:rtype: bs4.Tag |
|
|
|
""" |
|
return self.api.closest( |
|
select, self.tag, self._ns(namespaces, select), flags, **kwargs |
|
) |
|
|
|
def match(self, select, namespaces=None, flags=0, **kwargs): |
|
"""Check whether this Tag matches the given CSS selector. |
|
|
|
This uses the Soup Sieve library. For more information, see |
|
that library's documentation for the soupsieve.match() |
|
method. |
|
|
|
:param: a CSS selector. |
|
|
|
:param namespaces: A dictionary mapping namespace prefixes |
|
used in the CSS selector to namespace URIs. By default, |
|
Beautiful Soup will pass in the prefixes it encountered while |
|
parsing the document. |
|
|
|
:param flags: Flags to be passed into Soup Sieve's |
|
soupsieve.match() method. |
|
|
|
:param kwargs: Keyword arguments to be passed into SoupSieve's |
|
soupsieve.match() method. |
|
|
|
:return: True if this Tag matches the selector; False otherwise. |
|
:rtype: bool |
|
""" |
|
return self.api.match( |
|
select, self.tag, self._ns(namespaces, select), flags, **kwargs |
|
) |
|
|
|
def filter(self, select, namespaces=None, flags=0, **kwargs): |
|
"""Filter this Tag's direct children based on the given CSS selector. |
|
|
|
This uses the Soup Sieve library. It works the same way as |
|
passing this Tag into that library's soupsieve.filter() |
|
method. More information, for more information see the |
|
documentation for soupsieve.filter(). |
|
|
|
:param namespaces: A dictionary mapping namespace prefixes |
|
used in the CSS selector to namespace URIs. By default, |
|
Beautiful Soup will pass in the prefixes it encountered while |
|
parsing the document. |
|
|
|
:param flags: Flags to be passed into Soup Sieve's |
|
soupsieve.filter() method. |
|
|
|
:param kwargs: Keyword arguments to be passed into SoupSieve's |
|
soupsieve.filter() method. |
|
|
|
:return: A ResultSet of Tag objects. |
|
:rtype: bs4.element.ResultSet |
|
|
|
""" |
|
return self._rs( |
|
self.api.filter( |
|
select, self.tag, self._ns(namespaces, select), flags, **kwargs |
|
) |
|
) |
|
|
