General Details
Implementation Specifics
The CSS selectors are based off of the CSS specification and includes not only stable selectors, but may also include selectors currently under development from the draft specifications. Primarily support has been added for selectors that were feasible to implement and most likely to get practical use. In addition to the selectors in the specification, Soup Sieve also supports a couple non-standard selectors.
Soup Sieve aims to allow users to target XML/HTML elements with CSS selectors. It implements many pseudo classes, but it does not currently implement any pseudo elements and has no plans to do so. Soup Sieve also will not match anything for pseudo classes that are only relevant in a live, browser environment, but it will gracefully handle them if they've been implemented; such pseudo classes are non-applicable in the Beautiful Soup environment and are noted in Non-Applicable Pseudo Classes.
When speaking about namespaces, they only apply to XML, XHTML, or when dealing with recognized foreign tags in HTML5. Currently, Beautiful Soup's html5lib parser is the only parser that will return the appropriate namespaces for a HTML5 document. If you are using XHTML, you have to use the Beautiful Soup's lxml-xml parser (or xml for short) to get the appropriate namespaces in an XHTML document. In addition to using the correct parser, you must provide a dictionary of namespaces to Soup Sieve in order to use namespace selectors. See the documentation on namespaces to learn more.
While an effort is made to mimic CSS selector behavior, there may be some differences or quirks, please report issues if any are found.
Selector Context Key
| Symbol | Name | Description |
|---|---|---|
| HTML | Some selectors are very specific to HTML and either have no meaningful representation in XML, or such functionality has not been implemented. Selectors that are HTML only will be noted with , and will match nothing if used in XML. | |
| Custom | Soup Sieve has implemented a couple non-standard selectors. These can contain useful selectors that were rejected from the official CSS specifications, selectors implemented by other systems such as JQuery, or even selectors specifically created for Soup Sieve. If a selector is considered non standard, it will be marked with . | |
| Experimental | All selectors that are from the current working draft of CSS4 are considered experimental and are marked with . Additionally, if there are other immature selectors, they may be marked as experimental as well. Experimental may mean we are not entirely sure if our implementation is correct, that things may still be in flux as they are part of a working draft, or even both. If at anytime a working draft drops a selector from the current draft, it will most likely also be removed here, most likely with a deprecation path, except where there may be a conflict that requires a less graceful transition. One exception is in the rare case that the selector is found to be far too useful despite being rejected. In these cases, we may adopt them as "custom" selectors. |
Additional Reading
If usage of a selector is not clear in this documentation, you can find more information by reading these specification documents:
CSS Level 3 Specification : Contains the latest official document outlying official behaviors of CSS selectors.
CSS Level 4 Working Draft : Contains the latest published working draft of the CSS level 4 selectors which outlines the experimental new selectors and experimental behavioral changes.
HTML5 : The HTML 5.0 specification document. Defines the semantics regarding HTML.
HTML Living Standard : The HTML Living Standard document. Defines semantics regarding HTML.
Selector Terminology
Certain terminology is used throughout this document when describing selectors. In order to fully understand the syntax a selector may implement, it is important to understand a couple of key terms.
Selector
Selector is used to describe any selector whether it is a simple, compound, or complex selector.
Simple Selector
A simple selector represents a single condition on an element. It can be a type selector, universal selector, ID selector, class selector, attribute selector, or pseudo class selector.
Compound Selector
A compound selector is a sequence of simple selectors. They do not contain any combinators. If a universal or type selector is used, they must come first, and only one instance of either a universal or type selector can be used, both cannot be used at the same time.
Complex Selector
A complex selector consists of multiple simple or compound selectors joined with combinators.
Selector List
A selector list is a list of selectors joined with a comma (,). A selector list is used to specify that a match is valid if any of the selectors in a list matches.