parsel

library1.11.0pypypi✓ verified 52d ago

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.

http-networking serialization data

pip install parsel

github ↗package ↗homepage ↗docs ↗changelog ↗

Install & Compatibility

Where this runs

tested against v1.11.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.254s · 31.1MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 2.3s · import 0.233s · 32MB

29MB installed

● package 29MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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}")

Debug

Known issues

breakingSupport 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.

affects: 1.7.0, 1.9.0, 1.10.0, 1.11.0

breakingThe `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.

affects: 1.7.0 - 1.11.0

breakingThe 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"`.

affects: 1.10.0+

breakingMinimum 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`).

affects: 1.9.0, 1.11.0+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'parsel'

The 'parsel' library is not installed in the Python environment being used, or there is a mismatch between the Python environment where it was installed and the one executing the script.

fix

Install the parsel library using pip: `pip install parsel`

ValueError: XPath error: exception

The XPath expression provided to the parsel Selector contains a syntax error or is malformed.

fix

Carefully review and correct the XPath syntax. Use browser developer tools or online XPath validators to test and verify the XPath expression against your document.

No data extracted (or empty list returned by .css()/.xpath())

The CSS or XPath selector provided does not match any elements in the HTML/XML document, or the content you are trying to extract is dynamically loaded via JavaScript and is not present in the initial HTML source.

fix

Inspect the HTML structure using browser developer tools to ensure the selector is correct and matches the desired elements. If the content is dynamic, consider using a tool like Selenium to render the JavaScript before parsing.

AttributeError: 'Selector' object has no attribute '_default_type'

This error typically indicates an incompatibility between the `parsel` library and a dependent library (such as Scrapy) that expects a specific internal attribute or method which has been changed or removed in a newer `parsel` version.

fix

Update both `parsel` and the dependent library (e.g., Scrapy) to their latest compatible versions, or pin `parsel` to a version known to be compatible with your current dependent library version. For instance, `pip install parsel==<compatible_version> Scrapy==<compatible_version>`.

Upgrade

Version history

1.11.0latest on PyPI

Audit

Dependencies

lxmlrequiredCore parsing engine for HTML/XML. Minimum version >= 5.1.0 since Parsel 1.11.0.

packagingrequiredUsed for version comparisons within the library. Minimum version >= 23.0 since Parsel 1.11.0.

jmespathrequiredEnables JMESPath queries for JSON documents. Minimum version >= 1.0.0 since Parsel 1.11.0. Introduced in Parsel 1.8.0.

cssselectrequiredEnables CSS selector functionality. Minimum version >= 1.2.0 since Parsel 1.9.0 (though required since 1.8.0).

Agent activity

13 hits · last 30 days

seranking-bot

ahrefsbot

node

amazonbot