> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/D4Vinci/Scrapling/llms.txt
> Use this file to discover all available pages before exploring further.

# Selectors

> A list-like container for multiple Selector objects

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

```python theme={null}
@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:**

```python theme={null}
selectors = page.css('.product')
first_product = selectors.first
```

### last

```python theme={null}
@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:**

```python theme={null}
selectors = page.css('.item')
last_item = selectors.last
```

### length

```python theme={null}
@property
def length(self) -> int
```

Returns the length of the current list.

**Returns:** The number of selectors in the list

**Example:**

```python theme={null}
selectors = page.css('.card')
total = selectors.length  # Same as len(selectors)
```

## Selection Methods

### xpath()

```python theme={null}
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.

<ParamField path="selector" type="str" required>
  The XPath selector to be used
</ParamField>

<ParamField path="identifier" type="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)
</ParamField>

<ParamField path="auto_save" type="bool" default="false">
  Automatically save new elements for adaptive later
</ParamField>

<ParamField path="percentage" type="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
</ParamField>

<ParamField path="**kwargs" type="Any">
  Additional keyword arguments will be passed as XPath variables in the XPath expression
</ParamField>

**Returns:** A `Selectors` object with flattened results

**Example:**

```python theme={null}
products = page.css('.product')
prices = products.xpath('.//span[@class="price"]/text()')
```

### css()

```python theme={null}
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.

<ParamField path="selector" type="str" required>
  The CSS3 selector to be used
</ParamField>

<ParamField path="identifier" type="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)
</ParamField>

<ParamField path="auto_save" type="bool" default="false">
  Automatically save new elements for adaptive later
</ParamField>

<ParamField path="percentage" type="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
</ParamField>

**Returns:** A `Selectors` object with flattened results

**Example:**

```python theme={null}
cards = page.css('.card')
titles = cards.css('.title')
```

## Extraction Methods

### get()

```python theme={null}
def get(self, default=None) -> Optional[TextHandler]
```

Returns the serialized string of the first element, or `default` if empty.

<ParamField path="default" type="Any" default="None">
  The default value to return if the current list is empty
</ParamField>

**Returns:** A `TextHandler` containing the first element's content, or the default value

**Example:**

```python theme={null}
title = page.css('h1').get()
optional = page.css('.missing').get('Not found')
```

### getall()

```python theme={null}
def getall(self) -> TextHandlers
```

Serialize all elements and return as a TextHandlers list.

**Returns:** A `TextHandlers` list containing all elements' content

**Example:**

```python theme={null}
all_links = page.css('a::attr(href)').getall()
all_text = page.css('.description::text').getall()
```

### re()

```python theme={null}
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.

<ParamField path="regex" type="str | Pattern" required>
  Can be either a compiled regular expression or a string
</ParamField>

<ParamField path="replace_entities" type="bool" default="true">
  If enabled, character entity references are replaced by their corresponding character
</ParamField>

<ParamField path="clean_match" type="bool" default="false">
  If enabled, this will ignore all whitespaces and consecutive spaces while matching
</ParamField>

<ParamField path="case_sensitive" type="bool" default="true">
  If disabled, the function will set the regex to ignore the letters case while compiling it
</ParamField>

**Returns:** A `TextHandlers` list with all matches from all elements

**Example:**

```python theme={null}
prices = page.css('.price').re(r'\$([\d.]+)')
```

### re\_first()

```python theme={null}
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.

<ParamField path="regex" type="str | Pattern" required>
  Can be either a compiled regular expression or a string
</ParamField>

<ParamField path="default" type="Any" default="None">
  The default value to be returned if there is no match
</ParamField>

<ParamField path="replace_entities" type="bool" default="true">
  If enabled, character entity references are replaced by their corresponding character
</ParamField>

<ParamField path="clean_match" type="bool" default="false">
  If enabled, this will ignore all whitespaces and consecutive spaces while matching
</ParamField>

<ParamField path="case_sensitive" type="bool" default="true">
  If disabled, the function will set the regex to ignore the letters case while compiling it
</ParamField>

**Returns:** A `TextHandler` with the first match or the default value

**Example:**

```python theme={null}
first_price = page.css('.price').re_first(r'\$([\d.]+)', '0.00')
```

## Filter Methods

### search()

```python theme={null}
def search(self, func: Callable[[Selector], bool]) -> Optional[Selector]
```

Loop over all current elements and return the first element that matches the passed function.

<ParamField path="func" type="Callable[[Selector], bool]" required>
  A function that takes each element as an argument and returns True/False
</ParamField>

**Returns:** The first `Selector` that matches the function or `None` otherwise

**Example:**

```python theme={null}
active = selectors.search(lambda s: s.has_class('active'))
```

### filter()

```python theme={null}
def filter(self, func: Callable[[Selector], bool]) -> Selectors
```

Filter current elements based on the passed function.

<ParamField path="func" type="Callable[[Selector], bool]" required>
  A function that takes each element as an argument and returns True/False
</ParamField>

**Returns:** A new `Selectors` object containing only matching elements, or empty list

**Example:**

```python theme={null}
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\_\_()

```python theme={null}
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:**

```python theme={null}
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:**

```python theme={null}
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