Parsel

1.11.0 · active · verified Thu Apr 09

Parsel is a powerful Python library designed to extract data from HTML and XML documents using XPath and CSS selectors. It provides a flexible and efficient way to navigate and query web content, making it a common dependency for web scraping tools. The current version is 1.11.0, and it maintains an active development cycle with frequent updates, often tied to Python version support and dependency requirement changes.

Warnings

breaking Support for older Python versions (3.9, PyPy 3.10) has been removed in 1.11.0. Earlier versions (3.8, 3.7, 3.6, 3.5, 2.7) were removed in previous releases.
Fix: Ensure your project runs on Python 3.10 or newer (Parsel 1.11.0 requires >=3.10). Refer to the release notes for specific version requirements.
breaking The `Selector.remove()` and `SelectorList.remove()` methods, deprecated in 1.7.0, have been entirely removed.
Fix: Migrate your code to use the `Selector.drop()` and `SelectorList.drop()` methods, which provide similar functionality, instead of the removed `remove()` methods.
breaking The default encoding name for documents loaded via `body` or when parsing changed from `"utf8"` to `"utf-8"` due to compatibility issues in some environments.
Fix: If you relied on the implicit `"utf8"` encoding name, explicitly specify `encoding='utf8'` in `Selector` constructor or update your code to use the standard `"utf-8"`.
breaking Minimum supported versions for core dependencies like `lxml`, `packaging`, `jmespath`, and `cssselect` have been bumped.
Fix: Update your project's dependencies to satisfy Parsel's new minimum requirements (e.g., `lxml >= 5.1.0`, `packaging >= 23.0`, `jmespath >= 1.0.0`, `cssselect >= 1.2.0`).

Install

pip install parsel Install stable version

Imports

Selector
```
from parsel import Selector
```
SelectorList
```
from parsel import SelectorList
```
Typically obtained as a result of a Selector method, but can be imported directly for type hinting or specific use cases.

Quickstart

This quickstart demonstrates how to initialize a `Selector` from HTML or JSON text, and then use both CSS selectors and XPath expressions to extract data. It also includes an example of JMESPath usage for JSON documents, introduced in Parsel 1.8.0.

from parsel import Selector

html_doc = '''
<html>
<head><title>My Awesome Page</title></head>
<body>
    <div id="main">
        <h1>Hello Parsel!</h1>
        <p class="intro">This is an <a href="/example">introductory</a> paragraph.</p>
        <ul>
            <li>Item 1</li>
            <li>Item 2</li>
        </ul>
    </div>
</body>
</html>
'''

# Create a Selector from HTML text
selector = Selector(text=html_doc)

# Extract title using CSS selector
title = selector.css('title::text').get()
print(f"Title: {title}")

# Extract H1 text using XPath
h1_text = selector.xpath('//h1/text()').get()
print(f"H1 Text: {h1_text}")

# Extract all list items using CSS selector
list_items = selector.css('ul li::text').getall()
print(f"List Items: {list_items}")

# Extract attribute using CSS selector
link_href = selector.css('.intro a::attr(href)').get()
print(f"Link href: {link_href}")

# Example with JSON and JMESPath (Parsel >= 1.8.0)
json_doc = '{"data": {"products": [{"id": 1, "name": "Laptop"}, {"id": 2, "name": "Mouse"}]}}'
json_selector = Selector(text=json_doc, type='json')
product_names = json_selector.jmespath('data.products[*].name').getall()
print(f"Product names (JMESPath): {product_names}")

view raw JSON →