bs4.filter.ElementFilter Class Reference

Inheritance diagram for bs4.filter.ElementFilter:

Collaboration diagram for bs4.filter.ElementFilter:

Public Member Functions
	__init__ (self, Optional[_PageElementMatchFunction] match_function=None)
bool	includes_everything (self)
bool	excludes_everything (self)
bool	match (self, PageElement element, bool _known_rules=False)
Iterator[_OneElement]	filter (self, Iterator[PageElement] generator)
_AtMostOneElement	find (self, Iterator[PageElement] generator)
_QueryResults	find_all (self, Iterator[PageElement] generator, Optional[int] limit=None)
bool	allow_tag_creation (self, Optional[str] nsprefix, str name, Optional[_RawAttributeValues] attrs)
bool	allow_string_creation (self, str string)

Public Attributes
	match_function

Static Public Attributes
Optional	match_function [_PageElementMatchFunction]

Detailed Description

`ElementFilter` encapsulates the logic necessary to decide:

1. whether a `PageElement` (a `Tag` or a `NavigableString`) matches a
user-specified query.

2. whether a given sequence of markup found during initial parsing
should be turned into a `PageElement` at all, or simply discarded.

The base class is the simplest `ElementFilter`. By default, it
matches everything and allows all markup to become `PageElement`
objects. You can make it more selective by passing in a
user-defined match function, or defining a subclass.

Most users of Beautiful Soup will never need to use
`ElementFilter`, or its more capable subclass
`SoupStrainer`. Instead, they will use methods like
:py:meth:`Tag.find`, which will convert their arguments into
`SoupStrainer` objects and run them against the tree.

However, if you find yourself wanting to treat the arguments to
Beautiful Soup's find_*() methods as first-class objects, those
objects will be `SoupStrainer` objects. You can create them
yourself and then make use of functions like
`ElementFilter.filter()`.

Constructor & Destructor Documentation

__init__()

bs4.filter.ElementFilter.__init__	(		self,
		Optional[_PageElementMatchFunction]	match_function = None
	)

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 in bs4.filter.SoupStrainer.

Member Function Documentation

allow_string_creation()

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

Based on the content of a string, see whether this
`ElementFilter` will allow a `NavigableString` object based on
this string to be added to the parse tree.

By default, all strings are processed into `NavigableString`
objects. To change this, subclass `ElementFilter`.

:param str: The string under consideration.

Reimplemented in bs4.filter.SoupStrainer.

allow_tag_creation()

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

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

By default, all tags are parsed. To change this, subclass
`ElementFilter`.

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

Reimplemented in bs4.filter.SoupStrainer.

excludes_everything()

bool bs4.filter.ElementFilter.excludes_everything

(

self

)

Does this `ElementFilter` obviously exclude everything? If
so, Beautiful Soup will issue a warning if you try to use it
when parsing a document.

The `ElementFilter` might turn out to exclude everything even
if this returns `False`, but it won't exclude everything in an
obvious way.

The base `ElementFilter` implementation excludes things based
on a match function we can't inspect, so excludes_everything
is always false.

Reimplemented in bs4.filter.SoupStrainer.

filter()

Iterator[_OneElement] bs4.filter.ElementFilter.filter	(		self,
		Iterator[PageElement]	generator
	)

The most generic search method offered by Beautiful Soup.

Acts like Python's built-in `filter`, using
`ElementFilter.match` as the filtering function.

find()

_AtMostOneElement bs4.filter.ElementFilter.find	(		self,
		Iterator[PageElement]	generator
	)

A lower-level equivalent of :py:meth:`Tag.find`.

You can pass in your own generator for iterating over
`PageElement` objects. The first one that matches this
`ElementFilter` will be returned.

:param generator: A way of iterating over `PageElement`
    objects.

find_all()

_QueryResults bs4.filter.ElementFilter.find_all	(		self,
		Iterator[PageElement]	generator,
		Optional[int]	limit = None
	)

A lower-level equivalent of :py:meth:`Tag.find_all`.

You can pass in your own generator for iterating over
`PageElement` objects. Only elements that match this
`ElementFilter` will be returned in the :py:class:`ResultSet`.

:param generator: A way of iterating over `PageElement`
    objects.

:param limit: Stop looking after finding this many results.

includes_everything()

bool bs4.filter.ElementFilter.includes_everything

(

self

)

Does this `ElementFilter` obviously include everything? If so,
the filter process can be made much faster.

The `ElementFilter` might turn out to include everything even
if this returns `False`, but it won't include everything in an
obvious way.

The base `ElementFilter` implementation includes things based on
the match function, so includes_everything is only true if
there is no match function.

Reimplemented in bs4.filter.SoupStrainer.

match()

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

Does the given PageElement match the rules set down by this
ElementFilter?

The base implementation delegates to the function passed in to
the constructor.

:param _known_rules: Defined for compatibility with
    SoupStrainer._match(). Used more for consistency than because
    we need the performance optimization.

Reimplemented in bs4.filter.SoupStrainer.

---

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

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