selectors.logical

Module with selectors that represent logical operations on multiple selectors.

Classes

AndSelector - intersection of multiple selectors (&)
NotSelector - negation of a selector (~)
XORSelector - exclusive OR of multiple selectors (^)
SelectorList - counterpart of CSS selector list or :is() pseudo-class (|)
OrSelector - union of multiple selectors - alias of SelectorList (|)

class SelectorList(selector1: SoupSelector, selector2: SoupSelector, /, *selectors: SoupSelector)[source]

Bases: CompositeSoupSelector

Counterpart of CSS selector list. At least one selector from list must match the element to be included.

Example

>>> SelectorList(TypeSelector("a"), AttributeSelector(name="class", value="widget"))

matches all elements that have “a” tag name OR ‘class’ attribute “widget”.

Example

>>> <a>Hello World</a> ✔️
>>> <div class="widget">Hello World</div> ✔️
>>> <div>Hello Python</div> ❌

Object can be created as well by using pipe operator | on SoupSelector objects.

Example

>>> TypeSelector("a") | ClassSelector("widget")

CSS counterpart can be represented as:

Example

>>> a, .widget
>>> :is(a, .widget)

Notes

For more information on selector list, see:

https://developer.mozilla.org/en-US/docs/Web/CSS/Selector_list

__init__(selector1: SoupSelector, selector2: SoupSelector, /, *selectors: SoupSelector) → None[source]

Initializes SelectorList object with provided positional arguments.

Parameters

selectors: SoupSelector: At least two SoupSelector objects to match accepted as positional arguments.

Raises

NotSoupSelectorException: If any of provided parameters is not an instance of SoupSelector.

find_all(tag: IElement, recursive: bool = True, limit: int | None = None) → list[IElement][source]

Finds all elements matching selector in provided IElement.

Parameters

tagIElement: Any IElement object to search within.
recursivebool, optional: Specifies if search should be recursive. If set to False, only direct children of the element will be searched. By default True.
limitint, optional: Specifies maximum number of elements to return. By default None, all found elements are returned.

Returns

list[IElement]: List of IElement objects matching selector. If none found, the list is empty.

OrSelector: alias of SelectorList

class NotSelector(selector: SoupSelector, /, *selectors: SoupSelector)[source]

Bases: CompositeSoupSelector

Selector for finding elements that do not match provided selector(s). Counterpart of CSS :not() pseudo-class.

Example

>>> NotSelector(TypeSelector("div"))

matches all elements that do not have “div” tag name.

Example

>>> <span> class="widget">Hello World</span> ✔️
>>> <div class="menu">Hello World</div> ❌

Object can be created as well by using bitwise NOT operator ~ on SoupSelector object.

Example

>>> ~TypeSelector("div")

Which is equivalent to the first example.

This is CSS counterpart of :not() pseudo-class.

Example

>>> :not(div)

Notes

For more information on :not() pseudo-class, see:

https://developer.mozilla.org/en-US/docs/Web/CSS/:not

__init__(selector: SoupSelector, /, *selectors: SoupSelector) → None[source]

Initializes NotSelectors object with provided positional arguments as selectors.

Parameters

selectors: SoupSelector: At least one SoupSelector objects to negate match accepted as positional arguments.

Raises

NotSoupSelectorException: If any of provided parameters is not an instance of SoupSelector.

find_all(tag: IElement, recursive: bool = True, limit: int | None = None) → list[IElement][source]

Finds all elements matching selector in provided IElement.

Parameters

tagIElement: Any IElement object to search within.
recursivebool, optional: Specifies if search should be recursive. If set to False, only direct children of the element will be searched. By default True.
limitint, optional: Specifies maximum number of elements to return. By default None, all found elements are returned.

Returns

list[IElement]: List of IElement objects matching selector. If none found, the list is empty.

class AndSelector(selector1: SoupSelector, selector2: SoupSelector, /, *selectors: SoupSelector)[source]

Bases: CompositeSoupSelector

Selector representing an intersection of multiple selectors, where element must be matched by all provided selectors. Counterpart of CSS compound selector.

Example

>>> AndSelector(TypeSelector("div"), ClassSelector("widget"))

matches all elements that have “div” tag name AND ‘class’ attribute “widget”.

Example

>>> <div class="widget">Hello World</div> ✔️
>>> <span class="widget">Hello World</span> ❌
>>> <div class="menu">Hello World</div> ❌

Object can be created as well by using bitwise AND operator & on SoupSelector objects.

Example

>>> TypeSelector("div") & ClassSelector("widget")

CSS counterpart can be represented as:

Example

>>> div.widget

Notes

For more information on compound selectors ,see:

https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selector_structure#compound_selector

__init__(selector1: SoupSelector, selector2: SoupSelector, /, *selectors: SoupSelector) → None[source]

Initializes AndSelector object with provided positional arguments as selectors.

Parameters

selectors: SoupSelector: At least two SoupSelector objects to match accepted as positional arguments.

Raises

NotSoupSelectorException: If any of provided parameters is not an instance of SoupSelector.

find_all(tag: IElement, recursive: bool = True, limit: int | None = None) → list[IElement][source]

Finds all elements matching selector in provided IElement.

Parameters

tagIElement: Any IElement object to search within.
recursivebool, optional: Specifies if search should be recursive. If set to False, only direct children of the element will be searched. By default True.
limitint, optional: Specifies maximum number of elements to return. By default None, all found elements are returned.

Returns

list[IElement]: List of IElement objects matching selector. If none found, the list is empty.

class XORSelector(selector1: SoupSelector, selector2: SoupSelector, /, *selectors: SoupSelector)[source]

Bases: CompositeSoupSelector

Selector representing an exclusive OR of multiple selectors, where element must be matched by exactly one of them.

Example

>>> XORSelector(TypeSelector("div"), ClassSelector("widget"))

Matches all elements that have either “div” tag name or ‘class’ attribute “widget”. Elements with both “div” tag name and ‘class’ attribute “widget” do not match selector.

Object can be created as well by using xor operator ^ (caret) on SoupSelector objects.

Example

>>> TypeSelector("div") ^ ClassSelector("widget")

This is a shortcut for defining XOR operation between two selectors like this:

Example

>>> selector1 = TypeSelector("div")
... selector2 = ClassSelector("widget")
... xor = (selector1 & (~selector2)) | ((~selector1) & selector2)

__init__(selector1: SoupSelector, selector2: SoupSelector, /, *selectors: SoupSelector) → None[source]

Initializes XORSelector object with provided positional arguments as selectors.

Parameters

selectors: SoupSelector: At least two SoupSelector objects to match accepted as positional arguments.

Raises

NotSoupSelectorException: If any of provided parameters is not an instance of SoupSelector.

find_all(tag: IElement, recursive: bool = True, limit: int | None = None) → list[IElement][source]

Finds all elements matching selector in provided IElement.

Parameters

tagIElement: Any IElement object to search within.
recursivebool, optional: Specifies if search should be recursive. If set to False, only direct children of the element will be searched. By default True.
limitint, optional: Specifies maximum number of elements to return. By default None, all found elements are returned.

Returns

list[IElement]: List of IElement objects matching selector. If none found, the list is empty.