models.wrappers

Module with wrappers for selectors used mostly in model schemas. Wrappers are used to control behavior and define how fields of the models are defined.

Classes

• All - Wrapper to find all information matching criteria.

• Default - Wrapper to set default value if information is not found.

• Required - Wrapper to enforce that information must be found.

class FieldWrapper(selector: TagSearcher | TagSearcherMeta)

Bases: TagSearcher, Comparable

A wrapper for TagSearcher valid objects, that acts as a higher order searcher, which controls behavior of the wrapped searcher. Used as field in defined model. Subclasses must implement find method with their specific behavior.

__init__(selector: TagSearcher | TagSearcherMeta) → None

Initializes wrapper with a TagSearcher valid object.

Parameters

selectorTagSearcher

The TagSearcher valid object to be wrapped.

Raises

NotTagSearcherException

If provided object is not a valid TagSearcher.

property selector: TagSearcher

Returns searcher, that is wrapped by this wrapper.

Returns

TagSearcher

TagSearcher instance wrapped by this wrapper.

find_all(tag: IElement, recursive: bool = True, limit: int | None = None) → list[Any]

Find all matching element using the wrapped selector. Used for compatibility with TagSearcher interface, delegates to wrapped selector.

Parameters

tagIElement

Any IElement to search within.

recursivebool, optional

Whether to search recursively, by default True.

limitint, optional

Limit the number of results, by default None.

Returns

list[Any]

A list of found results.

class FieldList(iterable=(), /)

Bases: list, JSONSerializable

Convenience wrapper around list to provide JSON serialization for lists containing JSON serializable items. Useful as field value to represent multiple matched elements.

json() → list[Any]

Serializes the FieldList to a JSON-compatible list.

Returns

list[Any]

A list containing JSON-serializable representations of the items.

class All(selector: TagSearcher | TagSearcherMeta)

Bases: FieldWrapper

Field wrapper for selecting multiple elements matching the selector. Forces find method to fall back to find_all method and return all matches.

Example

>>> from soupsavvy.models import All
... from soupsavvy import TypeSelector
... selector = All(TypeSelector("div"))
... selector.find(tag)
[element1, element2, element3]

find(tag: IElement, strict: bool = False, recursive: bool = True) → list[Any]

Find all matching tags using the wrapped selector, enforcing the use of find_all method.

Parameters

tagIElement

Any IElement to search within.

strictbool, optional

Ignored, as this method always falls back to find_all.

recursivebool, optional

Whether to search recursively, by default True.

Returns

list[Any]

A list of matching results.

class Required(selector: TagSearcher | TagSearcherMeta)

Bases: FieldWrapper

Field wrapper for enforcing matched element not to be None. Raises an exception if searcher does not find any matches.

Example

>>> from soupsavvy.models import Required
... from soupsavvy import TypeSelector
... selector = Required(TypeSelector("div"))
... selector.find(tag)
RequiredConstraintException

find(tag: IElement, strict: bool = False, recursive: bool = True) → Any

Finds a required element using the wrapped selector, enforcing matched element not to be None. If any exception is raised during the search, it’s propagated to the caller.

Parameters

tagIElement

Any IElement to search within.

strictbool, optional

If True, raises an exception if no matches are found, by default False.

recursivebool, optional

Whether to search recursively, by default True.

Returns

Any

The found element.

Raises

RequiredConstraintException

If selector returns None, indicating that required element was not found.

class Default(selector: TagSearcher | TagSearcherMeta, default: Any)

Bases: FieldWrapper

Field wrapper for returning a default value if no match is found.

Example

>>> from soupsavvy.models import Default
... from soupsavvy import TypeSelector
... selector = Default(TypeSelector("div"), default="1234")
... selector.find(tag)
"1234"

__init__(selector: TagSearcher | TagSearcherMeta, default: Any) → None

Initializes Default field wrapper.

Parameters

selectorTagSearcher

Object compatible with TagSearcher interface to be wrapped.

defaultAny

The default value to return if no match is found.

find(tag: IElement, strict: bool = False, recursive: bool = True)

Finds an element, returning a default value if None was returned by wrapped selector. Any exception raised during the search is propagated.

Parameters

tagIElement

Any IElement to search within.

strictbool, optional

If True, raises an exception if no matches are found, by default False.

recursivebool, optional

Whether to search recursively, by default True.

Returns

Any

The found element or the default value if not found.