API: searching

Model vs Pulp fields

New in version 1.3.0.

The Criteria and Matcher classes are able to operate on two types of fields:

• Model fields: fields documented on the PulpObject class hierarchy. eng_product_id from the Repository class is an example of a model field.

• Pulp fields: any arbitrary fields within the Pulp 2.x database. notes.eng_product is an example of a Pulp field.

Generally, searching on model fields should be preferred when possible, as this allows your code to avoid a dependency on Pulp implementation details and allows you to use the same field names everywhere.

However, not all model fields support this, as not every model field has a direct mapping with a Pulp field. Attempting to search on an unsupported model field will raise an exception.

Class reference

class pubtools.pulplib.Criteria

Represents a Pulp search criteria.

This is an opaque class which is not intended to be created or used directly. Instances of this class should be obtained and composed by calls to the documented class methods.

Example - searching a repository:

# With Pulp 2.x / mongo, this is roughly equivalent
# to search fragment:
#
#  {"notes.my-field": {"$exists": True},
#   "notes.other-field": {"$eq": ["a", "b", "c"]}}
#
crit = Criteria.and_(
    Criteria.with_field('notes.my-field', Matcher.exists()),
    Criteria.with_field('notes.other-field', ["a", "b", "c"])
)

# criteria may now be used with client to execute a search
repos = client.search_repository(crit)

Example - searching across all repos for a specific content type:

crit = Criteria.and_(
    Criteria.with_unit_type(RpmUnit),
    Criteria.with_field("sha256sum", Matcher.in_([
        "49ae93732fcf8d63fe1cce759664982dbd5b23161f007dba8561862adc96d063",
        "6b30e91df993d96df0bef0f9d232d1068fa2f7055f13650208d77b43cd7c99f6"])))

# Will find RpmUnit instances with above sums
units = client.search_content(crit)

classmethod with_unit_type(unit_type, unit_fields=None)

Parameters:

• unit_type (class) – A subclass of Unit.

• unit_fields (Iterable[str]) –

  Names of the desired field(s) to include in response to a search using this criteria. If omitted, all fields are included.

  Some fields will always be included even when not requested.

Returns:

Criteria

criteria for finding units of type unit_type populated with (at least) the fields from unit_fields.

New in version 2.14.0.

New in version 2.33.0: Introduced unit_fields.

classmethod with_id(ids)

Parameters:

ids (str, list[str]) – An id or list of ids

Returns:

Criteria

criteria for finding objects matching the given ID(s)

classmethod with_field(field_name, field_value)

Parameters:

• field_name (str) –

  The name of a field.

  Supported field names include both model fields and Pulp fields. See Model vs Pulp fields for information about these two types of fields.

  When Pulp fields are used, field names may contain a “.” to indicate nesting, such as notes.created.

• field_value –

  Matcher

  A matcher to be applied against the field.

  object

  Any value, to be matched against the field via Matcher.equals().

Returns:

Criteria

criteria for finding objects where field_name is present and matches field_value.

classmethod and_(*criteria)

Parameters:

criteria (list[Criteria]) – Any number of criteria.

Returns:

Criteria

criteria for finding objects which satisfy all of the input criteria.

classmethod or_(*criteria)

Parameters:

criteria (list[Criteria]) – Any number of criteria.

Returns:

Criteria

criteria for finding objects which satisfy any of the input criteria.

classmethod true()

Returns:

Criteria

a criteria which always matches any object.

class pubtools.pulplib.Matcher

Methods for matching fields within a Pulp search query.

Instances of this class are created by the documented class methods, and should be used in conjunction with Criteria methods, such as Criteria.with_field().

New in version 1.1.0.

classmethod equals(value)

Matcher for a field which must equal exactly the given value.

Parameters:

value (object) – An object to match against a field.

classmethod regex(pattern)

Matcher for a field which must be a string and must match the given regular expression.

Parameters:

pattern (str) –

A regular expression to match against the field. The expression is not implicitly anchored.

Warning

It is not defined which specific regular expression syntax is supported. For portable code, callers are recommended to use only the common subset of PCRE-compatible and Python-compatible regular expressions.

Raises:

re.error – If the given pattern is not a valid regular expression.

Example

# Would match any Repository where notes.my-field starts
# with "abc"
crit = Criteria.with_field('notes.my-field', Matcher.regex("^abc"))

classmethod exists()

Matcher for a field which must exist, with no specific value.

Example

# Would match any Repository where notes.my-field exists
crit = Criteria.with_field('notes.my-field', Matcher.exists())

classmethod in_(values)

Returns a matcher for a field whose value equals one of the specified input values.

Parameters:

values (iterable) – An iterable of values used to match a field.

Example

# Would match any Repository where notes.my-field is "a", "b" or "c"
crit = Criteria.with_field(
    'notes.my-field',
    Matcher.in_(["a", "b", "c"])
)

classmethod less_than(value)

Returns a matcher for a field whose value is less than the specified input value.

Parameters:

value (object) – An object to match against the field

Example

# would match where last_publish is before "2019-08-27T00:00:00Z"
# date comparison requires a datetime.datetime object
crit = Criteria.with_field(
    'last_publish',
    Matcher.less_than(datetime.datetime(2019, 8, 27, 0, 0, 0))
)

New in version 2.1.0.

class pubtools.pulplib.Page(*, data=_Nothing.NOTHING, next: Future | None = None)

A page of Pulp search results.

All Pulp searches issued by this library are paginated. Instances of this class may be used to iterate through the returned pages, in both blocking and non-blocking coding styles.

Page objects are iterables. Iterating over a page will iterate over all data within that page, and all subsequent pages, blocking on more data from Pulp as needed.

Examples

Non-blocking iteration

This example sets up non-blocking processing of all results from a search query. Futures are chained and composed using f_flat_map() and friends.

def handle_results(page):
    # Returns a future for handling of a single page
    for repo in page.data:
        do_something(repo)
    if page.next:
        # There's more data, handle that too when it's ready
        return f_flat_map(page.next, handle_results)
    # No more data, we're done
    print("Handled results!")
    return f_return()

page_f = client.search_repository(...)
handled_f = f_flat_map(page_f, handle_results)
# handled_f will be resolved when all results are handled

Blocking iteration

This example uses the page as an iterable to loop over all search results. At certain points during the iteration, blocking may occur to await more pages from Pulp.

page = client.search_repository(...).result()
# processes all data, but may block at page boundaries
for repo in page:
    do_something(repo)

Method generated by attrs for class Page.

data

List of Pulp objects in this page.

This list will contain instances of the appropriate Pulp object type (e.g. Repository for a repository search).

property next

None, if this is the last page of results.

Otherwise, a Future[Page] for the next page of results.