selectors.nth.selectors

Module provides nth-of-type selector implementations for SoupSelector. It allows you to search for the nth occurrence of an element, similar to how the CSS nth-of-type pseudo-class works. However, instead of being limited to css selectors, it works with any SoupSelector instance.

Classes

• NthOfSelector - Selects nth element matching given selector

• NthLastOfSelector - Selects nth last element matching given selector

• OnlyOfSelector - Selects only element matching given selector

class BaseNthOfSelector(selector: SoupSelector, nth: str)

Bases: SoupSelector

Base class for nth-of-selector and nth-last-of-selector that implements general logic for finding matching elements.

__init__(selector: SoupSelector, nth: str) → None

Initializes nth selector instance.

Parameters

selectorSoupSelector

Any SoupSelector instance used to match elements.

nthstr

CSS nth selector string. Accepts all valid css nth formulas.

Raises

NotSoupSelectorException

If selector is not an instance of SoupSelector.

property selector: SoupSelector

Returns selector instance used for matching elements in this nth selector.

Returns

SoupSelector

Selector used in this nth selector.

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

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 NthOfSelector(selector: SoupSelector, nth: str)

Bases: BaseNthOfSelector

Selector for finding nth-of elements in the soup among elements that match provided SoupSelector instance.

Example

>>> selector = NthOfSelector(ClassSelector("item"), "2n+1")

matches all odd elements with class “item”.

Example

>>> <div class="item">1</div> ✔️
... <div id="item"></div> ❌
... <div class="item">2</div> ❌
... <div class="item">3</div> ✔️
... <div class="widget"></div> ❌
... <div class="item">4</div> ❌

Notes

For more information about standard :nth-of-type pseudo-class, visit:

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

class NthLastOfSelector(selector: SoupSelector, nth: str)

Bases: BaseNthOfSelector

Selector for finding nth-last-of elements in the soup among elements that match provided SoupSelector instance.

Example

>>> selector = NthLastOfSelector(ClassSelector("item"), "2n+1")

matches all odd elements with class “item” starting from the last element.

Example

>>> <div class="item">1</div> ❌
... <div id="item"></div> ❌
... <div class="item">2</div> ✔️
... <div class="item">3</div> ❌
... <div class="widget"></div> ❌
... <div class="item">4</div> ✔️

Notes

For more information about standard :nth-of-type pseudo-class, visit:

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

class OnlyOfSelector(selector: SoupSelector)

Bases: SoupSelector

Selector for finding the only element, that matches provided SoupSelector instance among its siblings.

Example

>>> selector = OnlyOfSelector(ClassSelector("item"))

matches all elements with class “item” that are the only child of their parent that matches the selector.

Example

>>> <div><div class="item"></div><a class="item"></a></div> ❌
>>> <div><div class="item"></div><a class="widget"></a></div> ✔️
>>> <div><div class="item"></div></div> ✔️
>>> <div><div class="widget"></div></div> ❌

Notes

For more information about standard :only-of-type pseudo-class, visit:

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

__init__(selector: SoupSelector) → None

Initializes OnlyOfSelector instance.

Parameters

selectorSoupSelector

Any SoupSelector instance used to match elements.

Raises

NotSoupSelectorException

If selector is not an instance of SoupSelector.

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

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.