selectors.attributes

Module with selectors that search for elements based on their attributes.

Classes

AttributeSelector - Selects element based on any attribute value.
IdSelector - Selects element based on ‘id’ attribute value.
ClassSelector - Selects element based on ‘class’ attribute value.

class AttributeSelector(name: str, value: Pattern[str] | str | None = None)[source]

Bases: SoupSelector

Selector for searching element based on its attribute value. Counterpart of css attribute selectors, that extends its capability with regex pattern matching.

Example

>>> AttributeSelector(name="role", value="widget")

matches all elements that have ‘role’ attribute with value “widget”.

Example

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

CSS counterpart can be represented as:

Example

>>> [role="widget"]

In case of using regex pattern, re.search is used to match the attribute value.

Example

>>> AttributeSelector(name="href", value=re.compile(r"wikipedia"))

Parameters

namestr: HTML element attribute name ex. “class”, “href”
valuestr | Pattern, optional: Value of the attribute to match. By default None, if not provided, default pattern matching any sequence of characters is used.

Notes

For more information about attribute selectors, see:

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

name: str

value: Pattern[str] | str | None = None

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.

__init__(name: str, value: Pattern[str] | str | None = None) → None

class SpecificAttributeSelector(value: Pattern[str] | str | None = None)[source]

Bases: AttributeSelector

Base class for specific attribute selectors, that wraps AttributeSelector with default attribute name for user convenience.

Child classes should define _NAME attribute with default attribute name, that will be used in the AttributeSelector.

__init__(value: Pattern[str] | str | None = None) → None[source]

Initializes specific attribute selector with default attribute name.

Parameters

valuestr | Pattern, optional: Value of the attribute to match. By default None, if not provided, default pattern matching any sequence of characters is used.

class IdSelector(value: Pattern[str] | str | None = None)[source]

Bases: SpecificAttributeSelector

Specific AttributeSelector for matching elements based on ‘id’ attribute value.

Example

>>> IdSelector("main")

matches all elements that have ‘id’ attribute with value “main”.

Example

>>> <div id="main">Hello World</div> ✔️
>>> <div id="content">Hello World</div> ❌

IdSelector is a convenience wrapper for AttributeSelector, thus example above is equivalent to using:

>>> AttributeSelector(name="id", value="main")

CSS counterpart can be represented as:

Example

>>> #main

In case of using regex pattern, re.search is used to match the attribute value.

Example

>>> IdSelector(re.compile(r"content[0-9]+"))

Notes

For more information about id attribute, see:

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

class ClassSelector(value: Pattern[str] | str | None = None)[source]

Bases: SpecificAttributeSelector

Specific AttributeSelector for matching elements based on ‘class’ attribute value.

Example

>>> ClassSelector("widget")

matches all elements that have ‘class’ attribute with value “widget”.

Example

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

ClassSelector is a convenience wrapper for AttributeSelector, thus example above is equivalent to using:

>>> AttributeSelector(name="class", value="widget")

CSS counterpart can be represented as:

Example

>>> .widget

In case of using regex pattern, re.search is used to match the attribute value.

Example

>>> ClassSelector(re.compile(r"nav"))

Notes

For more information about class attribute, see:

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