bs4.filter.SoupStrainer Class Reference

Inheritance diagram for bs4.filter.SoupStrainer:

Collaboration diagram for bs4.filter.SoupStrainer:

Public Member Functions
	__init__ (self, Optional[_StrainableElement] name=None, Optional[Dict[str, _StrainableAttribute]] attrs=None, Optional[_StrainableString] string=None, **_StrainableAttribute kwargs)
bool	includes_everything (self)
bool	excludes_everything (self)
Optional[_StrainableString]	string (self)
Optional[_StrainableString]	text (self)
str	__repr__ (self)
bool	matches_tag (self, Tag tag)
bool	allow_tag_creation (self, Optional[str] nsprefix, str name, Optional[_RawAttributeValues] attrs)
bool	allow_string_creation (self, str string)
bool	matches_any_string_rule (self, str string)
bool	match (self, PageElement element, bool _known_rules=False)
bool	search_tag (self, str name, Optional[_RawAttributeValues] attrs)
Optional[PageElement]	search (self, PageElement element)
Public Member Functions inherited from bs4.filter.ElementFilter
Iterator[_OneElement]	filter (self, Iterator[PageElement] generator)
_AtMostOneElement	find (self, Iterator[PageElement] generator)
_QueryResults	find_all (self, Iterator[PageElement] generator, Optional[int] limit=None)

Public Attributes
	name_rules
	attribute_rules
	string_rules
Public Attributes inherited from bs4.filter.ElementFilter
	match_function

Static Public Attributes
List	name_rules [TagNameMatchRule]
Dict	attribute_rules [str, List[AttributeValueMatchRule]]
List	string_rules [StringMatchRule]
Static Public Attributes inherited from bs4.filter.ElementFilter
Optional	match_function [_PageElementMatchFunction]

Protected Member Functions
Iterator[MatchRule]	_make_match_rules (cls, Optional[Union[_StrainableElement, _StrainableAttribute]] obj, Type[MatchRule] rule_class)
bool	_attribute_match (self, Optional[_AttributeValue] attr_value, Iterable[AttributeValueMatchRule] rules)

Detailed Description

The `ElementFilter` subclass used internally by Beautiful Soup.

A `SoupStrainer` encapsulates the logic necessary to perform the
kind of matches supported by methods such as
:py:meth:`Tag.find`. `SoupStrainer` objects are primarily created
internally, but you can create one yourself and pass it in as
``parse_only`` to the `BeautifulSoup` constructor, to parse a
subset of a large document.

Internally, `SoupStrainer` objects work by converting the
constructor arguments into `MatchRule` objects. Incoming
tags/markup are matched against those rules.

:param name: One or more restrictions on the tags found in a document.

:param attrs: A dictionary that maps attribute names to
  restrictions on tags that use those attributes.

:param string: One or more restrictions on the strings found in a
  document.

:param kwargs: A dictionary that maps attribute names to restrictions
  on tags that use those attributes. These restrictions are additive to
  any specified in ``attrs``.

Constructor & Destructor Documentation

__init__()

bs4.filter.SoupStrainer.__init__	(		self,
		Optional[_StrainableElement]	match_function = None,
		Optional[Dict[str, _StrainableAttribute]]	attrs = None,
		Optional[_StrainableString]	string = None,
		**_StrainableAttribute	kwargs
	)

Pass in a match function to easily customize the behavior of
`ElementFilter.match` without needing to subclass.

:param match_function: A function that takes a `PageElement`
  and returns `True` if that `PageElement` matches some criteria.

Reimplemented from bs4.filter.ElementFilter.

Member Function Documentation

_make_match_rules()

Iterator[MatchRule] bs4.filter.SoupStrainer._make_match_rules (   cls, Optional[Union[_StrainableElement, _StrainableAttribute]]  obj, Type[MatchRule]  rule_class  )

protected

Convert a vaguely-specific 'object' into one or more well-defined
`MatchRule` objects.

:param obj: Some kind of object that corresponds to one or more
   matching rules.
:param rule_class: Create instances of this `MatchRule` subclass.

allow_string_creation()

bool bs4.filter.SoupStrainer.allow_string_creation	(		self,
		str	string
	)

Based on the content of a markup string, see whether this
`SoupStrainer` will allow it to be instantiated as a
`NavigableString` object, or whether it should be ignored.

Reimplemented from bs4.filter.ElementFilter.

allow_tag_creation()

bool bs4.filter.SoupStrainer.allow_tag_creation	(		self,
		Optional[str]	nsprefix,
		str	name,
		Optional[_RawAttributeValues]	attrs
	)

Based on the name and attributes of a tag, see whether this
`SoupStrainer` will allow a `Tag` object to even be created.

:param name: The name of the prospective tag.
:param attrs: The attributes of the prospective tag.

Reimplemented from bs4.filter.ElementFilter.

excludes_everything()

bool bs4.filter.SoupStrainer.excludes_everything

(

self

)

Check whether the provided rules will obviously exclude
everything. (They might exclude everything even if this returns `False`,
but not in an obvious way.)

Reimplemented from bs4.filter.ElementFilter.

includes_everything()

bool bs4.filter.SoupStrainer.includes_everything

(

self

)

Check whether the provided rules will obviously include
everything. (They might include everything even if this returns `False`,
but not in an obvious way.)

Reimplemented from bs4.filter.ElementFilter.

match()

bool bs4.filter.SoupStrainer.match	(		self,
		PageElement	element,
		bool	_known_rules = False
	)

Does the given `PageElement` match the rules set down by this
`SoupStrainer`?

The find_* methods rely heavily on this method to find matches.

:param element: A `PageElement`.
:param _known_rules: Set to true in the common case where
   we already checked and found at least one rule in this SoupStrainer
   that might exclude a PageElement. Without this, we need
   to check .includes_everything every time, just to be safe.
:return: `True` if the element matches this `SoupStrainer`'s rules; `False` otherwise.

Reimplemented from bs4.filter.ElementFilter.

matches_any_string_rule()

bool bs4.filter.SoupStrainer.matches_any_string_rule	(		self,
		str	string
	)

See whether the content of a string matches any of
this `SoupStrainer`'s string rules.

matches_tag()

bool bs4.filter.SoupStrainer.matches_tag	(		self,
		Tag	tag
	)

Do the rules of this `SoupStrainer` trigger a match against the
given `Tag`?

If the `SoupStrainer` has any `TagNameMatchRule`, at least one
must match the `Tag` or its `Tag.name`.

If there are any `AttributeValueMatchRule` for a given
attribute, at least one of them must match the attribute
value.

If there are any `StringMatchRule`, at least one must match,
but a `SoupStrainer` that *only* contains `StringMatchRule`
cannot match a `Tag`, only a `NavigableString`.

search()

Optional[PageElement] bs4.filter.SoupStrainer.search	(		self,
		PageElement	element
	)

A less elegant version of match(). Deprecated as of 4.13.0.

:meta private:

search_tag()

bool bs4.filter.SoupStrainer.search_tag	(		self,
		str	name,
		Optional[_RawAttributeValues]	attrs
	)

A less elegant version of `allow_tag_creation`. Deprecated as of 4.13.0

---

The documentation for this class was generated from the following file:

• docs/help/help-venv/lib/python3.12/site-packages/bs4/filter.py