Skip to main content
The Selectors class is a subclass of Python’s builtin List class that provides additional methods for working with collections of Selector objects. It maintains all standard list functionality while adding powerful batch processing capabilities.

​
Overview

Selectors is returned by most selection methods like css(), xpath(), find_all(), and others when multiple elements are found. It allows you to perform operations on all contained selectors at once.

​
Properties

​
first

@property
def first(self) -> Optional[Selector]
Returns the first Selector item of the current list. Returns: The first Selector or None if the list is empty Example: 
selectors = page.css('.product')
first_product = selectors.first

​
last

@property
def last(self) -> Optional[Selector]
Returns the last Selector item of the current list. Returns: The last Selector or None if the list is empty Example: 
selectors = page.css('.item')
last_item = selectors.last

​
length

@property
def length(self) -> int
Returns the length of the current list. Returns: The number of selectors in the list Example: 
selectors = page.css('.card')
total = selectors.length  # Same as len(selectors)

​
Selection Methods

​
xpath()

def xpath(
    self,
    selector: str,
    identifier: str = "",
    auto_save: bool = False,
    percentage: int = 0,
    **kwargs: Any,
) -> Selectors
Call the .xpath() method for each element in this list and return their results as another Selectors object.
​
selector
str
required
The XPath selector to be used
​
identifier
str
default:""
A string that will be used to retrieve element’s data in adaptive, otherwise the selector will be used. Recommended if you plan to use a different selector later and want to relocate the same element(s)
​
auto_save
bool
default:"false"
Automatically save new elements for adaptive later
​
percentage
int
default:"0"
The minimum percentage to accept while adaptive is working. Don’t play with this number unless you know what you’re doing
​
**kwargs
Any
Additional keyword arguments will be passed as XPath variables in the XPath expression
Returns: A Selectors object with flattened results Example: 
products = page.css('.product')
prices = products.xpath('.//span[@class="price"]/text()')

​
css()

def css(
    self,
    selector: str,
    identifier: str = "",
    auto_save: bool = False,
    percentage: int = 0,
) -> Selectors
Call the .css() method for each element in this list and return their results flattened as another Selectors object.
​
selector
str
required
The CSS3 selector to be used
​
identifier
str
default:""
A string that will be used to retrieve element’s data in adaptive, otherwise the selector will be used. Recommended if you plan to use a different selector later and want to relocate the same element(s)
​
auto_save
bool
default:"false"
Automatically save new elements for adaptive later
​
percentage
int
default:"0"
The minimum percentage to accept while adaptive is working. Don’t play with this number unless you know what you’re doing
Returns: A Selectors object with flattened results Example: 
cards = page.css('.card')
titles = cards.css('.title')

​
Extraction Methods

​
get()

def get(self, default=None) -> Optional[TextHandler]
Returns the serialized string of the first element, or default if empty.
​
default
Any
default:"None"
The default value to return if the current list is empty
Returns: A TextHandler containing the first element’s content, or the default value Example: 
title = page.css('h1').get()
optional = page.css('.missing').get('Not found')

​
getall()

def getall(self) -> TextHandlers
Serialize all elements and return as a TextHandlers list. Returns: A TextHandlers list containing all elements’ content Example: 
all_links = page.css('a::attr(href)').getall()
all_text = page.css('.description::text').getall()

​
re()

def re(
    self,
    regex: str | Pattern,
    replace_entities: bool = True,
    clean_match: bool = False,
    case_sensitive: bool = True,
) -> TextHandlers
Call the .re() method for each element in this list and return their results flattened as a list of TextHandler.
​
regex
str | Pattern
required
Can be either a compiled regular expression or a string
​
replace_entities
bool
default:"true"
If enabled, character entity references are replaced by their corresponding character
​
clean_match
bool
default:"false"
If enabled, this will ignore all whitespaces and consecutive spaces while matching
​
case_sensitive
bool
default:"true"
If disabled, the function will set the regex to ignore the letters case while compiling it
Returns: A TextHandlers list with all matches from all elements Example: 
prices = page.css('.price').re(r'\$([\d.]+)')

​
re_first()

def re_first(
    self,
    regex: str | Pattern,
    default: Any = None,
    replace_entities: bool = True,
    clean_match: bool = False,
    case_sensitive: bool = True,
) -> TextHandler
Call the .re_first() method for each element in this list and return the first result or the default value otherwise.
​
regex
str | Pattern
required
Can be either a compiled regular expression or a string
​
default
Any
default:"None"
The default value to be returned if there is no match
​
replace_entities
bool
default:"true"
If enabled, character entity references are replaced by their corresponding character
​
clean_match
bool
default:"false"
If enabled, this will ignore all whitespaces and consecutive spaces while matching
​
case_sensitive
bool
default:"true"
If disabled, the function will set the regex to ignore the letters case while compiling it
Returns: A TextHandler with the first match or the default value Example: 
first_price = page.css('.price').re_first(r'\$([\d.]+)', '0.00')

​
Filter Methods

def search(self, func: Callable[[Selector], bool]) -> Optional[Selector]
Loop over all current elements and return the first element that matches the passed function.
​
func
Callable[[Selector], bool]
required
A function that takes each element as an argument and returns True/False
Returns: The first Selector that matches the function or None otherwise Example: 
active = selectors.search(lambda s: s.has_class('active'))

​
filter()

def filter(self, func: Callable[[Selector], bool]) -> Selectors
Filter current elements based on the passed function.
​
func
Callable[[Selector], bool]
required
A function that takes each element as an argument and returns True/False
Returns: A new Selectors object containing only matching elements, or empty list Example: 
visible = selectors.filter(lambda s: 'display:none' not in s.attrib.get('style', ''))
expensive = products.filter(lambda p: float(p.css('.price::text').re_first(r'\d+', '0')) > 100)

​
Magic Methods

​
__getitem__()

def __getitem__(self, pos: SupportsIndex | slice) -> Union[Selector, Selectors]
Access elements by index or slice. Returns: A single Selector when using an index, or a new Selectors object when using a slice Example: 
first = selectors[0]
last = selectors[-1]
first_three = selectors[:3]
every_other = selectors[::2]

​
List Operations

Since Selectors is a subclass of list, all standard list methods are available:
  • append(item) - Add a selector to the end
  • extend(items) - Add multiple selectors
  • insert(index, item) - Insert at a specific position
  • remove(item) - Remove first occurrence
  • pop(index) - Remove and return item at index
  • clear() - Remove all items
  • index(item) - Find index of item
  • count(item) - Count occurrences
  • reverse() - Reverse in place
  • sort() - Sort in place
Example: 
selectors = page.css('.item')
for selector in selectors:
    print(selector.text)

# Check if empty
if selectors:
    print(f"Found {len(selectors)} items")

# Iteration
for i, sel in enumerate(selectors):
    print(f"Item {i}: {sel.text}")

​
Aliases

For compatibility with Scrapy/Parsel:
  • extract() - alias for getall()
  • extract_first() - alias for get()

​
Notes

  • Results from css() and xpath() methods are automatically flattened, so nested selections work seamlessly
  • The class cannot be pickled due to underlying lxml limitations
  • Empty Selectors objects evaluate to False in boolean contexts

Build docs developers (and LLMs) love

Get started for freeTalk to us