selectors.css.selectors

Module with classes for element selection based on CSS selectors.

Contains implementation of basic CSS pseudo-classes like :only-child, :empty, :nth-child().

They can be used in combination with other SoupSelector objects to create more complex search procedures.

Classes

OnlyChild
Empty
FirstChild
LastChild
NthChild
NthLastChild
FirstOfType
LastOfType
NthOfType
NthLastOfType
OnlyOfType
CSS - wrapper for simple search with CSS selectors

class CSSSoupSelector[source]

Bases: SoupSelector, SelectableCSS

Base class for selectors based on css selectors. Classes that base their selection on CSS selectors should inherit from this class and implement the selector property.

By default, the find methods are implemented using the soupsieve library to match the selector.

CSSSoupSelector objects inherit from SoupSelector and can be easily used in combination with other SoupSelector objects.

SELECTOR: str

__init__() → None[source]

property css: str: Returns string representing element css selector.

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 OnlyChild[source]

Bases: CSSSoupSelector

Selector for finding elements, that do not have any siblings. Counterpart of the CSS selector :only-child pseudo-class.

Example

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

Notes

For more information on the :only-child pseudo-class, see:

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

SELECTOR: str = ':only-child'

class Empty[source]

Bases: CSSSoupSelector

Selector for finding empty elements, i.e., that have no children. Counterpart of the CSS selector :empty pseudo-class.

Example

>>> <div class="widget"> ❌
...    <div class="menu"></div> ✔️
... </div>

Any text node is considered as a child and makes the element non-empty.

Example

>>> <div class="widget">Hello World</div> ❌
... <div class="widget"> </div> ❌

These elements are not empty and do not match the selector.

Notes

For more information on the :empty selector, see:

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

SELECTOR: str = ':empty'

class FirstChild[source]

Bases: CSSSoupSelector

Selector for finding elements, that are the first child of their parent. Counterpart of the CSS selector :first-child pseudo-class.

Example

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

Notes

FirstChild object is essentially the same as NthChild(“1”).

For more information on the :first-child selector, see:

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

SELECTOR: str = ':first-child'

class LastChild[source]

Bases: CSSSoupSelector

Selector for finding elements, that are the last child of their parent. Counterpart of the CSS selector :last-child pseudo-class.

Example

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

Notes

LastChild object is essentially the same as NthLastChild(“1”). Element that is the first and only child is matched as well.

For more information on the :last-child selector, see:

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

SELECTOR: str = ':last-child'

class NthBaseSelector(nth: str)[source]

Bases: CSSSoupSelector

Base class for selectors based on nth formula.

__init__(nth: str) → None[source]

Initialize the selector with the nth formula.

Parameters

nthstr, positional: Nth formula used to select the elements.

SELECTOR: str

class NthChild(nth: str)[source]

Bases: NthBaseSelector

Selector for finding elements, that are the nth child of their parent. Counterpart of the CSS selector :nth-child(n).

Example

>>> NthChild("2").selector
:nth-child(2)
>>> NthChild("2n+1").selector
:nth-child(2n+1)
>>> NthChild("odd").selector
:nth-child(odd)

Notes

For more information on the formula, see:

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

SELECTOR: str = ':nth-child({})'

class NthLastChild(nth: str)[source]

Bases: NthBaseSelector

Selector for finding elements, that are the nth last child of their parent. Counterpart of the CSS selector :nth-last-child(n).

Example

>>> NthLastChild("2").selector
:nth-last-child(2)
>>> NthLastChild("2n+1").selector
:nth-last-child(2n+1)
>>> NthLastChild("odd").selector
:nth-last-child(odd)

Notes

For more information on the formula, see:

https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-last-child

SELECTOR: str = ':nth-last-child({})'

class FirstOfType[source]

Bases: CSSSoupSelector

Selector for finding elements, that are the first of their type in their parent. Counterpart of the CSS selector :first-of-type pseudo-class.

Example

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

Notes

For this selector the first element of any type is selected, which in case of finding single element is equivalent to FirstChild results.

For more information on the formula, see:

https://developer.mozilla.org/en-US/docs/Web/CSS/:first-of-type

SELECTOR: str = ':first-of-type'

class LastOfType[source]

Bases: CSSSoupSelector

Selector for finding elements, that are the last of their type in their parent. Counterpart of the CSS selector :last-of-type pseudo-class.

Example

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

Notes

For this selector the last element of any type is selected, which in case of finding single element is the equivalent to LastChild results.

For more information on the formula, see:

https://developer.mozilla.org/en-US/docs/Web/CSS/:last-of-type

SELECTOR: str = ':last-of-type'

class NthOfType(nth: str)[source]

Bases: NthBaseSelector

Selector for finding elements, that are the nth of their type in their parent. Counterpart of the CSS selector :nth-of-type(n).

Example

>>> NthOfType("2").selector
:nth-of-type(2)
>>> NthOfType("2n+1").selector
:nth-of-type(2n+1)
>>> NthOfType("even").selector
:nth-of-type(even)

Notes

For more information on the formula, see:

https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-of-type

SELECTOR: str = ':nth-of-type({})'

class NthLastOfType(nth: str)[source]

Bases: NthBaseSelector

Selector for finding elements, that are the nth last of their type in their parent. Counterpart of the CSS selector :nth-last-of-type(n).

Example

>>> NthLastOfType("2").selector
:nth-last-of-type(2)
>>> NthLastOfType("2n+1").selector
:nth-last-of-type(2n+1)
>>> NthLastOfType("even").selector
:nth-last-of-type(even)

Notes

For more information on the formula, see:

https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-last-of-type

SELECTOR: str = ':nth-last-of-type({})'

class OnlyOfType[source]

Bases: CSSSoupSelector

Selector for finding elements, that don’t have siblings of the same type. Counterpart of the CSS selector :only-of-type pseudo-class.

Example

>>> <div class="widget"> ❌
...    <div class="menu">Hello World</div> ✔️
... </div>
... <div class="widget"> ❌
...    <div class="menu">Hello World</div> ✔️
...    <span class="menu">Hello World 2 </span> ❌
...    <span class="menu">Hello World 3 </span> ❌
... </div>
... <a class="widget"></a> ✔️

Notes

For more information on the :only-of-type selector, see:

https://developer.mozilla.org/en-US/docs/Web/CSS/:only-of-type

SELECTOR: str = ':only-of-type'

class CSS(css: str)[source]

Bases: CSSSoupSelector

Selector for finding elements based on any provided CSS selector. soupsieve adapter, that allows any supported css selector to be used with other soupsavvy components.

Example

>>> CSS("div.menu")

Would match:

Example

>>> <div class="widget"> ❌
...    <div class="menu">Hello World</div> ✔️
... </div>
... <div class="menu_main"> ❌
...    <a class="menu">Hello World</a> ❌
... </div>
... <div class="menu"></div> ✔️

Notes

Implemented selectors may vary between implementations, as each of them uses specific compatible libraries for css selection.

SELECTOR: str = '{}'

__init__(css: str) → None[source]

Initializes the selector with the provided css selector.

Parameters

cssstr: CSS selector to be used for selecting elements.