Soup Sieve

https://facelessuser.github.io/soupsieve/
Admin
Soup Sieve is a CSS selector library for Beautiful Soup 4 that provides modern CSS selector support...
Tokens:28,385
Snippets:330
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Build Tools

Source: https://facelessuser.github.io/soupsieve

Install the 'build' package, which is required for manually building and installing Soup Sieve from source.

```bash
pip install build
```

--------------------------------

### Install Documentation Dependencies

Source: https://facelessuser.github.io/soupsieve/about/development

Install all required packages for building and previewing documentation.

```bash
pip install -r requirements/docs.txt
```

--------------------------------

### PEP440 Versioning Examples

Source: https://facelessuser.github.io/soupsieve/about/security

Examples of versioning following the PEP440 standard, including major, minor, and patch releases.

```text
8.0
8.1
8.1.3

```

--------------------------------

### Install tox

Source: https://facelessuser.github.io/soupsieve/about/development

Installs the tox automation tool for managing virtual environments.

```bash
pip install tox
```

--------------------------------

### Build and Install Soup Sieve from Source

Source: https://facelessuser.github.io/soupsieve

Manually build the wheel package for Soup Sieve and install it. Replace '<ver>' with the specific version number. This method is for advanced users or when installing from a local source.

```bash
python -m build -w
```

```bash
pip install dist/soupsieve-<ver>-py3-none-any.whl
```

--------------------------------

### Build and Preview Documentation

Source: https://facelessuser.github.io/soupsieve/about/development

Start a local server to build and preview documentation at localhost:8000.

```bash
python3 -m zensical serve -f zensical.yml
```

--------------------------------

### Install Beautiful Soup 4

Source: https://facelessuser.github.io/soupsieve

Install the Beautiful Soup 4 library, a prerequisite for Soup Sieve. This command is typically run using pip.

```bash
pip install beautifulsoup4
```

--------------------------------

### Install Soup Sieve

Source: https://facelessuser.github.io/soupsieve

Install the Soup Sieve library directly using pip. This is the standard method if Soup Sieve is not automatically included with Beautiful Soup 4.

```bash
pip install soupsieve
```

--------------------------------

### Define CSS Namespaces

Source: https://facelessuser.github.io/soupsieve/api

Example of CSS @namespace rules for XHTML and SVG.

```css
@namespace url("http://www.w3.org/1999/xhtml");
@namespace svg url("http://www.w3.org/2000/svg");
```

--------------------------------

### Using :nth-of-type() with BeautifulSoup

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Examples of selecting elements by type and position using SoupSieve within a BeautifulSoup environment.

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <p id="0"></p>
... <p id="1"></p>
... <span id="2"></span>
... <span id="3"></span>
... <span id="4"></span>
... <span id="5"></span>
... <span id="6"></span>
... <p id="7"></p>
... <p id="8"></p>
... <p id="9"></p>
... <p id="10"></p>
... <span id="11"></span>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('span:nth-of-type(even)'))
[<span id="3"></span>, <span id="5"></span>, <span id="11"></span>]
>>> print(soup.select('span:nth-of-type(odd)'))
[<span id="2"></span>, <span id="4"></span>, <span id="6"></span>]
>>> print(soup.select('p:nth-of-type(2)'))
[<p id="1"></p>]
>>> print(soup.select('p:nth-of-type(-n+3)'))
[<p id="0"></p>, <p id="1"></p>, <p id="7"></p>]
```

--------------------------------

### Python Soup Sieve :nth-child Examples

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Demonstrates selecting elements by position using BeautifulSoup and Soup Sieve.

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <p id="0"></p>
... <p id="1"></p>
... <p id="2"></p>
... <p id="3"></p>
... <p id="4"></p>
... <p id="5"></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('p:nth-child(even)'))
[<p id="1"></p>, <p id="3"></p>, <p id="5"></p>]
>>> print(soup.select('p:nth-child(odd)'))
[<p id="0"></p>, <p id="2"></p>, <p id="4"></p>]
>>> print(soup.select('p:nth-child(2)'))
[<p id="1"></p>]
>>> print(soup.select('p:nth-child(-n+3)'))
[<p id="0"></p>, <p id="1"></p>, <p id="2"></p>]
```

--------------------------------

### Selecting elements with :placeholder-shown

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Example usage with BeautifulSoup to select elements displaying placeholder text.

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <input id="0" placeholder="This is some text">
... <textarea id="1" placeholder="This is some text"></textarea>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select(':placeholder-shown'))
[<input id="0" placeholder="This is some text"/>, <textarea id="1" placeholder="This is some text"></textarea>]
```

--------------------------------

### CSS :nth-last-of-type() Syntax Examples

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Common syntax patterns for the :nth-last-of-type() selector.

```css
element:nth-last-of-type(even)
element:nth-last-of-type(odd)
element:nth-last-of-type(2)
element:nth-last-of-type(2n+2)
```

--------------------------------

### Soup Sieve :nth-last-child() Level 3 Examples

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Python examples demonstrating the use of :nth-last-child() with BeautifulSoup and Soup Sieve.

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <p id="0"></p>
... <p id="1"></p>
... <p id="2"></p>
... <p id="3"></p>
... <p id="4"></p>
... <p id="5"></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('p:nth-last-child(even)'))
[<p id="0"></p>, <p id="2"></p>, <p id="4"></p>]
>>> print(soup.select('p:nth-last-child(odd)'))
[<p id="1"></p>, <p id="3"></p>, <p id="5"></p>]
>>> print(soup.select('p:nth-last-child(2)'))
[<p id="4"></p>]
>>> print(soup.select('p:nth-last-child(-n+3)'))
[<p id="3"></p>, <p id="4"></p>, <p id="5"></p>]
```

--------------------------------

### Soup Sieve :nth-last-child() Level 4 Example

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Python example demonstrating the use of the 'of S' selector list extension in Soup Sieve.

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <p id="0"></p>
... <p id="1"></p>
... <p id="2"></p>
... <p id="3"></p>
... <p id="4"></p>
... <p id="5"></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('*:nth-last-child(-n+3 of [id])'))
[<p id="3"></p>, <p id="4"></p>, <p id="5"></p>]
```

--------------------------------

### Python Soup Sieve :nth-child Level 4 Example

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Demonstrates using the 'of' selector list pattern with complex selectors.

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <p id="0"></p>
... <p id="1"></p>
... <p id="2"></p>
... <p id="3"></p>
... <p id="4"></p>
... <p id="5"></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('*:nth-child(-n+3 of [id])'))
[<p id="0"></p>, <p id="1"></p>, <p id="2"></p>]
```

--------------------------------

### Select Elements with Attribute Value Starting With a Prefix

Source: https://facelessuser.github.io/soupsieve/selectors/basic

Use `[attribute|=value]` to select elements where an attribute's value starts with a specific string, followed by a hyphen or the end of the string. Useful for language codes.

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <div lang="en">Some text</div>
... <div lang="en-US">Some more text</div>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('div[lang|="en"]'))
[<div lang="en">Some text</div>, <div lang="en-US">Some more text</div>]
```

--------------------------------

### Selecting Elements Without Explicit Namespace

Source: https://facelessuser.github.io/soupsieve/selectors/basic

Shows how a simple element selector `a` matches elements from any namespace if no default namespace is specified. This includes elements from the SVG namespace in this example.

```python
>>> print(soup.select('a', namespaces={'svg': 'http://www.w3.org/2000/svg'}))
[<a href="http://facelessuser.github.io/soupsieve/">Soup Sieve Docs</a>, <a xlink:href="https://developer.mozilla.org/"><text x="10" y="25">MDN Web Docs</text></a>]
```

--------------------------------

### Define Custom Selectors

Source: https://facelessuser.github.io/soupsieve/api

Assigns complex selectors to custom pseudo-class names starting with :--.

```python
import soupsieve as sv
import bs4

markup = """
<html>
<body>
<h1 id="1">Header 1</h1>
<h2 id="2">Header 2</h2>
<p id="3"></p>
<p id="4"><span>child</span></p>
</body>
</html
"""

soup = bs4.BeautifulSoup(markup, 'lxml')
print(sv.select(':--header', soup, custom={':--header': 'h1, h2, h3, h4, h5, h6'}))
```

```python
[<h1 id="1">Header 1</h1>, <h2 id="2">Header 2</h2>]
```

```python
custom = {
    ":--parent": ":has(> *|*)",
    ":--parent-paragraph": "p:--parent"
}
print(sv.select(':--parent-paragraph', soup, custom=custom))
```

```python
[<p id="4"><span>child</span></p>]
```

--------------------------------

### Select Elements with Attribute Value Starting With a Substring

Source: https://facelessuser.github.io/soupsieve/selectors/basic

Use `[attribute^=value]` to select elements where an attribute's value begins with a specified substring. This is case-sensitive.

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <ul>
...   <li><a href="#internal">Internal link</a></li>
...   <li><a href="http://example.com">Example link</a></li>
...   <li><a href="#InSensitive">Insensitive internal link</a></li>
...   <li><a href="http://example.org">Example org link</a></li>
... </ul>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('[href^=http]'))
[<a href="http://example.com">Example link</a>, <a href="http://example.org">Example org link</a>]
```

--------------------------------

### Handle CSS Identifiers Starting with Numbers

Source: https://facelessuser.github.io/soupsieve/differences

Soup Sieve requires CSS identifiers (like class names) to be valid. Use CSS escapes for selectors starting with numbers, e.g., `.2class` becomes `r'.\32 class'`.

```python
soup.select(r'.\32 class')
```

--------------------------------

### Build Documentation for Spell Checking

Source: https://facelessuser.github.io/soupsieve/about/development

Build the documentation files before running the spell checker.

```bash
python3 -m zensical build --clean -f zensical.yml
```

--------------------------------

### Syntax for :placeholder-shown

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

The basic CSS syntax for the pseudo-class.

```css
:placeholder-shown
```

--------------------------------

### View Module File Structure

Source: https://facelessuser.github.io/soupsieve/about/development

Displays the directory layout of the soupseive package.

```text
soupseive
├── __init__.py
├── __meta__.py
├── css_match.py
├── css_parser.py
├── css_types.py
└── util.py
```

--------------------------------

### Using the :open pseudo-class

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Targets <details> and <dialog> elements that possess the open attribute.

```text
:open
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <details open>
... <summary>A summary</summary>
... <p>Content</p>
... </details>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('details:open'))
[<details open="">
<summary>A summary</summary>
<p>Content</p>
</details>]
```

--------------------------------

### Run tox documentation tasks

Source: https://facelessuser.github.io/soupsieve/about/development

Executes spell checking and document building via tox.

```bash
tox -e documents
```

--------------------------------

### Initialize SelectorLang class

Source: https://facelessuser.github.io/soupsieve/about/development

Defines the structure for language-based selector matching using regular expressions.

```python
class SelectorLang:
    """Selector language rules."""

    def __init__(self, languages):
        """Initialize."""
```

--------------------------------

### Project Directory Structure

Source: https://facelessuser.github.io/soupsieve/about/development

Visual representation of the project's root directory layout.

```text
├── docs
│   └── src
│       ├── dictionary
│       └── markdown
├── soupsieve
├── requirements
└── tests
```

--------------------------------

### Host-context Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :host-context pseudo-class.

```css
:host-context(parent descendant)
```

--------------------------------

### Run Local Spell Check

Source: https://facelessuser.github.io/soupsieve/about/development

Execute the spell checker to identify potential misspellings in the documentation.

```bash
pyspelling
```

--------------------------------

### Select muted media elements

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Demonstrates selecting video elements with the muted attribute.

```text
:muted
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <video id="vid1" width="320" height="240" controls muted>
...   <source src="movie.mp4" type="video/mp4">
...   <source src="movie.ogg" type="video/ogg">
...   Your browser does not support the video tag.
... </video>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('video:muted'))
[<video controls="" height="240" id="vid1" muted="" width="320">
  <source src="movie.mp4" type="video/mp4"/>
  <source src="movie.ogg" type="video/ogg"/>
  Your browser does not support the video tag.
</video>]
```

--------------------------------

### Run tox environments

Source: https://facelessuser.github.io/soupsieve/about/development

Executes tests across all configured tox environments.

```bash
tox
```

--------------------------------

### soupsieve.compile(pattern, namespaces=None, flags=0, **kwargs)

Source: https://facelessuser.github.io/soupsieve/api

Pre-compiles a CSS selector pattern into a SoupSieve object for efficient reuse.

```APIDOC
## soupsieve.compile(pattern, namespaces=None, flags=0, **kwargs)

### Description
Compiles a CSS selector pattern, returning a SoupSieve object that provides methods like match, closest, filter, select, and select_one.

### Parameters
- **pattern** (string) - Required - The CSS selector pattern.
- **namespaces** (dict) - Optional - Namespace mappings.
- **flags** (int) - Optional - Compilation flags.
- **kwargs** (dict) - Optional - Additional keyword arguments.
```

--------------------------------

### Host Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :host pseudo-class and its functional form.

```css
:host
:host(selector1, selector2)
```

--------------------------------

### Multi-line Selectors with Soup Sieve

Source: https://facelessuser.github.io/soupsieve

Demonstrates using multi-line strings for complex CSS selectors, improving readability. Selectors can span multiple lines just like in CSS files.

```python
>>> selector = """
... .a,
... .b,
... .c
... """
>>> sv.select(selector, soup)
[<p class="a">Cat</p>, <p class="b">Dog</p>, <p class="c">Mouse</p>]
```

--------------------------------

### Fullscreen Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :fullscreen pseudo-class.

```css
:fullscreen
```

--------------------------------

### Run tox linting

Source: https://facelessuser.github.io/soupsieve/about/development

Executes linting checks via tox.

```bash
tox -e lint
```

--------------------------------

### Configure Soup Sieve Namespace Dictionary

Source: https://facelessuser.github.io/soupsieve/api

Mapping prefixes to namespace URIs for use in Soup Sieve selector functions. An empty string key represents the default namespace.

```python
namespace = {
    "": "http://www.w3.org/1999/xhtml",   # Default namespace is for XHTML
    "svg": "http://www.w3.org/2000/svg",  # The SVG namespace defined with prefix of "svg"
}
```

--------------------------------

### Popover-open Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :popover-open pseudo-class.

```css
:popover-open
```

--------------------------------

### Using the :optional pseudo-class

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Selects form elements that do not have the required attribute.

```text
:optional
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <form>
... <input type="name" required>
... <input type="checkbox" required>
... <input type="email">
... <textarea name="name" cols="30" rows="10" required></textarea>
... <select name="nm" required>
...     <!-- options -->
... </select>
... </form>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select(':optional'))
[<input type="email"/>]
```

--------------------------------

### Enable Debugging with soupsieve.DEBUG

Source: https://facelessuser.github.io/soupsieve/api

Use the DEBUG flag during compilation to print detailed parsing information for a CSS selector.

```python
>>> import soupsieve as sv
>>> sv.compile('p:has(#id) > span.some-class:contains(text)', flags=sv.DEBUG)
## PARSING: 'p:has(#id) > span.some-class:contains(text)'
TOKEN: 'tag' --> 'p' at position 0
TOKEN: 'pseudo_class' --> ':has(' at position 1
    is_pseudo: True
    is_open: True
    is_relative: True
TOKEN: 'id' --> '#id' at position 6
TOKEN: 'pseudo_close' --> ')' at position 9
TOKEN: 'combine' --> ' > ' at position 10
TOKEN: 'tag' --> 'span' at position 13
TOKEN: 'class' --> '.some-class' at position 17
TOKEN: 'pseudo_contains' --> ':contains(text)' at position 28
## END PARSING
SoupSieve(pattern='p:has(#id) > span.some-class:contains(text)', namespaces=None, custom=None, flags=1)
```

--------------------------------

### Playing Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :playing pseudo-class.

```css
:playing
```

--------------------------------

### soupsieve.compile()

Source: https://facelessuser.github.io/soupsieve/api

Compiles a CSS selector pattern for repeated use.

```APIDOC
## soupsieve.compile(selector, namespaces=None, flags=0)

### Description
Compiles a CSS selector pattern into a reusable object.

### Parameters
- **selector** (string) - Required - The CSS selector pattern to compile.
- **namespaces** (dict) - Optional - A dictionary mapping namespace prefixes to URIs.
- **flags** (int) - Optional - Flags to modify selector behavior.
```

--------------------------------

### Initialize SelectorNth class

Source: https://facelessuser.github.io/soupsieve/about/development

Defines the structure for nth-child selector logic, including formula parameters and optional selector lists.

```python
class SelectorNth:
    """Selector nth type."""

    def __init__(self, a, n, b, of_type, last, selectors):
        """Initialize."""
```

--------------------------------

### Selectors with Comments using Soup Sieve

Source: https://facelessuser.github.io/soupsieve

Shows how to include comments within multi-line selectors for better documentation of complex queries. Comments are ignored by the selector engine.

```python
>>> selector = """
... /* This isn't complicated, but we're going to annotate it anyways.
...    This is the a class */
... .a,
... /* This is the b class */
... .b,
... /* This is the c class */
... .c
... """
>>> sv.select(selector, soup)
[<p class="a">Cat</p>, <p class="b">Dog</p>, <p class="c">Mouse</p>]
```

--------------------------------

### Buffering Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :buffering pseudo-class.

```css
:buffering
```

--------------------------------

### Syntax for :read-only

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

The basic CSS syntax for the :read-only pseudo-class.

```css
:read-only
```

--------------------------------

### Create BeautifulSoup Object

Source: https://facelessuser.github.io/soupsieve

Initialize a BeautifulSoup object with HTML content and a parser. This is a prerequisite for using Soup Sieve with BeautifulSoup.

```python
>>> import bs4

>>> text = """
... <div>
... <!-- These are animals -->
... <p class="a">Cat</p>
... <p class="b">Dog</p>
... <p class="c">Mouse</p>
... </div>
... """
>>> soup = bs4.BeautifulSoup(text, 'html5lib')
```

--------------------------------

### Selecting Elements with Namespaces

Source: https://facelessuser.github.io/soupsieve/selectors/basic

Demonstrates how to select elements belonging to a specific namespace using `svg|a`. This requires defining the namespace mapping in the `namespaces` argument.

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <h1>SVG Example</h1>
... <p><a href="http://facelessuser.github.io/soupsieve/">Soup Sieve Docs</a></p>
... 
... <svg viewBox="0 0 160 40" xmlns="http://www.w3.org/2000/svg">
...   <a xlink:href="https://developer.mozilla.org/"><text x="10" y="25">MDN Web Docs</text></a>
... </svg>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('svg|a', namespaces={'svg': 'http://www.w3.org/2000/svg'}))
[<a xlink:href="https://developer.mozilla.org/"><text x="10" y="25">MDN Web Docs</text></a>]
```

--------------------------------

### Select read-write elements with Soup Sieve

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Demonstrates selecting elements that are editable by the user using BeautifulSoup and Soup Sieve.

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... 
... <input id="0">
... <input id="1" disabled>
... <input id="2" type="number" readonly>
... 
... <textarea id="3"></textarea>
... 
... <p id="4">Not editable</p>
... <p id="5" contenteditable="true">Editable text</p>
... 
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('body :read-write'))
[<input id="0"/>, <textarea id="3"></textarea>, <p contenteditable="true" id="5">Editable text</p>]
```

--------------------------------

### Compile Selector with Soup Sieve

Source: https://facelessuser.github.io/soupsieve

Pre-compile a Soup Sieve selector for performance when it will be used multiple times. Compiled selectors offer the same functionality but can be faster.

```python
>>> selector = sv.compile('p:is(.a, .b, .c)')
>>> selector.filter(soup.div)
[<p class="a">Cat</p>, <p class="b">Dog</p>, <p class="c">Mouse</p>]
```

--------------------------------

### Syntax for :nth-of-type()

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Common syntax patterns for the :nth-of-type() pseudo-class.

```css
element:nth-of-type(even)
element:nth-of-type(odd)
element:nth-of-type(2)
element:nth-of-type(2n+2)
```

--------------------------------

### Use :is() pseudo-class selector

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Selects elements matching any selector in the provided list.

```text
:is(selector1, selector2)
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <p id="0">Some text <span id="1"> in a paragraph</span>.
... <a id="2" href="http://google.com">Link.</a></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('[id]:is(a, span)'))
[<span id="1"> in a paragraph</span>, <a href="http://google.com" id="2">Link.</a>]
```

--------------------------------

### Autofill Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :autofill pseudo-class.

```css
:autofill
```

--------------------------------

### Use :lang() Level 4 pseudo-class selector

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Selects elements using comma-separated language lists and BCP 47 language ranges.

```text
:lang('*-language', language2)
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <div lang="de-DE">
...     <p id="1"></p>
... </div>
... <div lang="en">
...     <p id="2"></p>
... </div>
... <div lang="de-Latn-DE">
...     <p id="3"></p>
... </div>
... <div lang="de-Latf-DE">
...     <p id="4"></p>
... </div>
... <div lang="en-US">
...     <p id="5"></p>
... </div>
... <p id="6" lang="de-DE"></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('p:lang(de-DE, "*-US")'))
[<p id="1"></p>, <p id="3"></p>, <p id="4"></p>, <p id="5"></p>, <p id="6" lang="de-DE"></p>]
```

--------------------------------

### Selecting Attributes with Namespaced Prefix

Source: https://facelessuser.github.io/soupsieve/selectors/basic

Demonstrates selecting an attribute with a specific namespace prefix using `[xlink|href ]`. This requires mapping the `xlink` prefix to its URI in the `namespaces` dictionary.

```python
>>> print(soup.select('[ xlink|href]', namespaces={' xlink': 'http://www.w3.org/1999/xlink'}))
[<a xlink:href="https://developer.mozilla.org/"><text x="10" y="25">MDN Web Docs</text></a>]
```

--------------------------------

### Local-link Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :local-link pseudo-class.

```css
:local-link
```

--------------------------------

### Select Multiple Tags with select

Source: https://facelessuser.github.io/soupsieve/api

Returns a list of all matching tags. Supports an optional limit parameter to restrict the number of results.

```python
def select(select, tag, namespaces=None, limit=0, flags=0, **kwargs):
    """Select the specified tags."""
```

```python
>>> import soupsieve as sv
>>> sv.select('p:is(.a, .b, .c)', soup)
[<p class="a">Cat</p>, <p class="b">Dog</p>, <p class="c">Mouse</p>]
```

--------------------------------

### Namespace Selector Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/basic

This section outlines the general syntax for namespace selectors in Soup Sieve, covering various combinations of namespace prefixes, universal selectors, and element/attribute names.

```text
ns|element
ns|*
*|*
*|element
|element
[ns|attr]
[*|attr]
[|attr]
```

--------------------------------

### soupsieve.select_one()

Source: https://facelessuser.github.io/soupsieve/api

Selects the first element matching the provided CSS selector pattern.

```APIDOC
## soupsieve.select_one(selector, tags, namespaces=None, flags=0)

### Description
Selects the first element that matches the given CSS selector pattern within the provided tags.

### Parameters
- **selector** (string) - Required - The CSS selector pattern to match.
- **tags** (BeautifulSoup object) - Required - The tag or document to search within.
- **namespaces** (dict) - Optional - A dictionary mapping namespace prefixes to URIs.
- **flags** (int) - Optional - Flags to modify selector behavior.
```

--------------------------------

### soupsieve.select()

Source: https://facelessuser.github.io/soupsieve/api

Selects all elements matching the provided CSS selector pattern.

```APIDOC
## soupsieve.select(selector, tags, namespaces=None, flags=0)

### Description
Returns a list of all elements that match the given CSS selector pattern within the provided tags.

### Parameters
- **selector** (string) - Required - The CSS selector pattern to match.
- **tags** (BeautifulSoup object) - Required - The tag or document to search within.
- **namespaces** (dict) - Optional - A dictionary mapping namespace prefixes to URIs.
- **flags** (int) - Optional - Flags to modify selector behavior.
```

--------------------------------

### Select default form elements with :default

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Identifies form elements that are marked as default, such as checked radio buttons or selected options.

```text
:default
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <form>
... 
... <input type="radio" name="season" id="spring">
... <label for="spring">Spring</label>
... 
... <input type="radio" name="season" id="summer" checked>
... <label for="summer">Summer</label>
... 
... <input type="radio" name="season" id="fall">
... <label for="fall">Fall</label>
... 
... <input type="radio" name="season" id="winter">
... <label for="winter">Winter</label>
... 
... <select id="pet-select">
...     <option value="">--Please choose an option--</option>
...     <option id="dog" value="dog">Dog</option>
...     <option id="cat" value="cat">Cat</option>
...     <option id="hamster" value="hamster" selected>Hamster</option>
...     <option id="parrot" value="parrot">Parrot</option>
...     <option id="spider" value="spider">Spider</option>
...     <option id="goldfish" value="goldfish">Goldfish</option>
... </select>
... </form>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select(':default'))
[<input checked="" id="summer" name="season" type="radio"/>, <option id="hamster" selected="" value="hamster">Hamster</option>]
```

--------------------------------

### soupsieve.match()

Source: https://facelessuser.github.io/soupsieve/api

Matches a given tag with a given CSS selector.

```APIDOC
## soupsieve.match(select, tag, namespaces=None, flags=0, **kwargs)

### Description
Matches a given tag with a given CSS selector and returns a boolean.

### Parameters
- **select** (string) - The CSS selector string.
- **tag** (Tag/BeautifulSoup) - The tag to match against.
- **namespaces** (dict, optional) - Namespace dictionary.
- **flags** (int, optional) - Flags for the selector engine.
```

--------------------------------

### Select enabled elements with :enabled

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Selects any element that is currently enabled.

```text
:enabled
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <form action="#">
...   <fieldset id="shipping">
...     <legend>Shipping address</legend>
...     <input type="text" placeholder="Name">
...     <input type="text" placeholder="Address">
...     <input type="text" placeholder="Zip Code">
...   </fieldset>
...   <br>
...   <fieldset id="billing">
...     <legend>Billing address</legend>
...     <label for="billing-checkbox">Same as shipping address:</label>
...     <input type="checkbox" id="billing-checkbox" checked>
...     <br>
...     <input type="text" placeholder="Name" disabled>
...     <input type="text" placeholder="Address" disabled>
...     <input type="text" placeholder="Zip Code" disabled>
...   </fieldset>
... </form>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('input:enabled'))
[<input placeholder="Name" type="text"/>, <input placeholder="Address" type="text"/>, <input placeholder="Zip Code" type="text"/>, <input checked="" id="billing-checkbox" type="checkbox"/>]
```

--------------------------------

### Selecting Elements with Default Namespace

Source: https://facelessuser.github.io/soupsieve/selectors/basic

Illustrates how defining a default namespace (e.g., `''` for `http://www.w3.org/1999/xhtml`) restricts the `a` selector to only match elements within that default namespace.

```python
>>> print(soup.select('a', namespaces={'': 'http://www.w3.org/1999/xhtml', 'svg': 'http://www.w3.org/2000/svg'}))
[<a href="http://facelessuser.github.io/soupsieve/">Soup Sieve Docs</a>]
```

--------------------------------

### Select root element with :root

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Selects the root element of the document tree.

```text
:root
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
...    <div>Here is some text.</div>
...    <div>Here is some more text.</div>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select(':root'))
[<html><head></head>
<body>
    <div>Here is some text.</div>
    <div>Here is some more text.</div>


</body></html>]
```

--------------------------------

### Define SelectorContains class

Source: https://facelessuser.github.io/soupsieve/about/development

Defines rules for matching element text content.

```python
class SelectorContains:
    """Selector contains rule."""

    def __init__(self, text):
        """Initialize."""
```

--------------------------------

### Define SelectorTag class

Source: https://facelessuser.github.io/soupsieve/about/development

Represents a tag name and optional namespace prefix for selector matching.

```python
class SelectorTag:
    """Selector tag."""

    def __init__(self, name, prefix):
        """Initialize."""
```

--------------------------------

### Select defined elements with :defined

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Selects standard HTML elements while excluding custom elements, as custom element registration is not supported in Beautiful Soup.

```text
:defined
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <custom-element text="Custom element example text"></custom-element>
... <p>Standard paragraph example text</p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('body > *:defined'))
[<p>Standard paragraph example text</p>]
```

--------------------------------

### Select Element by ID

Source: https://facelessuser.github.io/soupsieve/selectors/basic

Use ID selectors to match an element with a specific 'id' attribute. The ID must match exactly.

```python
from bs4 import BeautifulSoup as bs
html = """
<html>
<head></head>
<body>
   <div id="some-id">Here is some text.</div>
   <div>Here is some more text.</div>
</body>
</html>
"""
soup = bs(html, 'html5lib')
print(soup.select('#some-id'))
```

--------------------------------

### Select link elements

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Matches <a> and <area> elements with an href attribute. Since visited states are not tracked, this matches all links.

```text
:link
```

```python
>>> from bs4 import BeautifulSoup as bsx
>>> html = """
... <html>
... <head></head>
... <body>
... <p>A link to <a href="http://example.com">click</a></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select(':link'))
[<a href="http://example.com">click</a>]
```

--------------------------------

### soupsieve.select()

Source: https://facelessuser.github.io/soupsieve/api

Selects all tags under the given tag that match the provided CSS selectors, with an optional limit on the number of results.

```APIDOC
## soupsieve.select(select, tag, namespaces=None, limit=0, flags=0, **kwargs)

### Description
Returns a list of all tags under the given tag that match the provided CSS selectors. The number of results can be restricted using the limit parameter.

### Parameters
- **select** (str) - Required - The CSS selector string.
- **tag** (Tag/BeautifulSoup) - Required - The tag object to search within.
- **namespaces** (dict) - Optional - An optional namespace dictionary.
- **limit** (int) - Optional - Maximum number of tags to return (0 for all).
- **flags** (int) - Optional - Parsing flags.

### Example
```python
import soupsieve as sv
sv.select('p:is(.a, .b, .c)', soup)
```
```

--------------------------------

### Select the first child element

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Use :first-child to target the first sibling element in a group.

```text
:first-child
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <p id="0"></p>
... <p id="1"></p>
... <p id="2"></p>
... <p id="3"></p>
... <p id="4"></p>
... <p id="5"></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('p:first-child'))
[<p id="0"></p>]
```

--------------------------------

### Target Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :target pseudo-class.

```css
:target
```

--------------------------------

### Use :where() pseudo-class

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Demonstrates selecting elements using the :where() pseudo-class, which acts as an alias for :is() in Soup Sieve.

```text
:where(selector1, selector2)
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <p id="0">Some text <span id="1"> in a paragraph</span>.
... <a id="2" href="http://google.com">Link.</a></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('[id]:where(a, span)'))
[<span id="1"> in a paragraph</span>, <a href="http://google.com" id="2">Link.</a>]
```

--------------------------------

### Current Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :current pseudo-class and its functional form.

```css
:current
:current(selector1, selector2)
```

--------------------------------

### Visited Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :visited pseudo-class.

```css
:visited
```

--------------------------------

### Focus Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :focus pseudo-class.

```css
:focus
```

--------------------------------

### Select elements with :any-link

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Selects <a> or <area> elements containing an href attribute.

```css
:any-link
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <p>A link to <a href="http://example.com">click</a></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select(':any-link'))
[<a href="http://example.com">click</a>]
```

--------------------------------

### soupsieve.match()

Source: https://facelessuser.github.io/soupsieve/api

Checks if a specific tag matches the provided CSS selector pattern.

```APIDOC
## soupsieve.match(selector, tag, namespaces=None, flags=0)

### Description
Determines if the provided tag matches the given CSS selector pattern.

### Parameters
- **selector** (string) - Required - The CSS selector pattern to match.
- **tag** (BeautifulSoup object) - Required - The tag to test.
- **namespaces** (dict) - Optional - A dictionary mapping namespace prefixes to URIs.
- **flags** (int) - Optional - Flags to modify selector behavior.
```

--------------------------------

### Compile CSS Patterns

Source: https://facelessuser.github.io/soupsieve/api

Pre-compiles CSS selector patterns into a SoupSieve object for repeated use.

```python
def compile(pattern, namespaces=None, flags=0, **kwargs):
    """Compile CSS pattern."""
```

```python
class SoupSieve:
    """Match tags in Beautiful Soup with CSS selectors."""

    def match(self, tag):
        """Match."""

    def closest(self, tag):
        """Match closest ancestor."""

    def filter(self, iterable):
        """Filter."""

    def select_one(self, tag):
        """Select a single tag."""

    def select(self, tag, limit=0):
        """Select the specified tags."""

    def iselect(self, tag, limit=0):
        """Iterate the specified tags."""
```

--------------------------------

### Select All Elements (Universal Selector)

Source: https://facelessuser.github.io/soupsieve/selectors/basic

The universal selector '*' matches elements of any type. It's often used to apply styles or select all nodes in the document.

```python
from bs4 import BeautifulSoup as bs
html = """
<html>
<head></head>
<body>
   <p>Here is some text.</p>
   <div>Here is some more text.</div>
</body>
</html>
"""
soup = bs(html, 'html5lib')
print(soup.select('*'))
```

--------------------------------

### Match tags with match

Source: https://facelessuser.github.io/soupsieve/api

Determines if a given tag matches the provided CSS selector string.

```python
def match(select, tag, namespaces=None, flags=0, **kwargs):
    """Match node."""
```

```python
>>> nodes = sv.select('p:is(.a, .b, .c)', soup)
>>> sv.match('p:not(.b)', nodes[0])
True
>>> sv.match('p:not(.b)', nodes[1])
False
```

--------------------------------

### Future Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :future pseudo-class.

```css
:future
```

--------------------------------

### soupsieve.iselect()

Source: https://facelessuser.github.io/soupsieve/api

Selects tags based on a CSS selector and returns a generator.

```APIDOC
## soupsieve.iselect(select, node, namespaces=None, limit=0, flags=0, **kwargs)

### Description
Selects the specified tags and returns a generator instead of a list.

### Parameters
- **select** (string) - The CSS selector string.
- **node** (Tag/BeautifulSoup) - The node to search within.
- **namespaces** (dict, optional) - Namespace dictionary.
- **limit** (int, optional) - Limit the number of results.
- **flags** (int, optional) - Flags for the selector engine.
```

--------------------------------

### Seeking Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :seeking pseudo-class.

```css
:seeking
```

--------------------------------

### Active Pseudo-class Syntax

Source: https://facelessuser.github.io/soupsieve/selectors/unsupported

Syntax for the :active pseudo-class.

```css
:active
```

--------------------------------

### :required

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Selects any input, select, or textarea element that has the required attribute set.

```APIDOC
## :required

### Description
Selects any `<input>`, `<select>`, or `<textarea>` element that has the `required` attribute set on it.

### Usage
`soup.select(':required')`
```

--------------------------------

### Run pytest validation

Source: https://facelessuser.github.io/soupsieve/about/development

Executes the project test suite using pytest.

```bash
pytest
```

--------------------------------

### Use :lang() Level 3 pseudo-class selector

Source: https://facelessuser.github.io/soupsieve/selectors/pseudo-classes

Selects elements based on language matching rules defined in CSS Level 3.

```text
:lang(language)
```

```python
>>> from bs4 import BeautifulSoup as bs
>>> html = """
... <html>
... <head></head>
... <body>
... <div lang="de-DE">
...     <p id="1"></p>
... </div>
... <div lang="de-DE-1996">
...     <p id="2"></p>
... </div>
... <div lang="de-Latn-DE">
...     <p id="3"></p>
... </div>
... <div lang="de-Latf-DE">
...     <p id="4"></p>
... </div>
... <div lang="de-Latn-DE-1996">
...     <p id="5"></p>
... </div>
... <p id="6" lang="de-DE"></p>
... </body>
... </html>
... """
>>> soup = bs(html, 'html5lib')
>>> print(soup.select('p:lang(de)'))
[<p id="1"></p>, <p id="2"></p>, <p id="3"></p>, <p id="4"></p>, <p id="5"></p>, <p id="6" lang="de-DE"></p>]
```

--------------------------------

### Run specific tox environment

Source: https://facelessuser.github.io/soupsieve/about/development

Executes tests for a specific Python version environment.

```bash
tox -e py310
```
Tokens:
Raw