BaseResolver

class BaseResolver(elements: Iterable[X] | None = None, *, default: X | None = None, synonyms: Mapping[str, X] | None = None, suffix: str | None = None, location: str | None = None)[source]

Bases: ABC, Generic[X, Y]

A resolver for arbitrary elements.

This class is parametrized by two variables:

  • X is the type of element in the resolver

  • Y is the type that gets made by the make function. This is typically the same as X, but might be different from X, such as in the class resolver.

Initialize the resolver.

Parameters:

  • elements – The elements to register

  • default – The optional default element

  • synonyms – The optional synonym dictionary

  • suffix – The optional shared suffix of all instances

  • location – The location used to document the resolver in sphinx

Attributes Summary

options

Return the normalized option names.

Methods Summary

docdata(query, *path[, default])

Lookup an element and get its docdata.

extract_name(element)

Get the name for an element.

extract_synonyms(element)

Get synonyms from an element.

from_entrypoint(group, **kwargs)

Make a resolver from the elements registered at the given entrypoint.

get_option(*flags[, as_string, default, ...])

Get a click option for this resolver.

lookup(query[, default])

Lookup an element.

make(query[, pos_kwargs])

Make an element.

make_safe(-> None)

Run make, but pass through a none query.

normalize(s)

Normalize the string with this resolve's suffix.

optuna_lookup(trial, name)

Suggest an element from this resolver for hyper-parameter optimization in Optuna.

register(element[, synonyms, raise_on_conflict])

Register an additional element with this resolver.

register_entrypoint(group)

Register additional entries from an entrypoint.

Attributes Documentation

options

Return the normalized option names.

Methods Documentation

docdata(query: str | X | None, *path: str, default: X | None = None) → Any[source]

Lookup an element and get its docdata.

Parameters:

  • query – The hint for looking something up in the resolver passed to lookup()

  • path – An optional path for traversing the resulting docdata dictionary

  • default – The default value to pass to lookup()

Returns:

The optional docdata retrieved with docdata.get_docdata()

abstractmethod extract_name(element: X) → str[source]

Get the name for an element.

extract_synonyms(element: X) → Collection[str][source]

Get synonyms from an element.

classmethod from_entrypoint(group: str, **kwargs: Any) → Self[source]

Make a resolver from the elements registered at the given entrypoint.

get_option(*flags: str, as_string: bool = False, default: Hint[X] = None, required: bool = False, prefix: str | None = None, delimiter: str | None = None, suffix: str | None = None, **kwargs: Any) → Callable[[click.decorators.FC], click.decorators.FC][source]

Get a click option for this resolver.

Parameters:

  • flags – Positional arguments that are passed to click.option()

  • as_string – Should the value returned by processing be a string, or the instantiated element? Defaults to False, which returns the instantiated element

  • default – The default value for the option.

  • required – Is a value for this option required? If so, it’s good to give a default.

  • prefix – The string shown after the opening square bracket, before the list of possible values

  • suffix – The string shown before the closing square bracket, after the list of possible values

  • delimiter – The delimiter between values

  • kwargs – Keyword arguments forwarded to click.option().

Returns:

An instantiated option that can be used in click CLI

abstractmethod lookup(query: str | X | None, default: X | None = None) → X[source]

Lookup an element.

abstractmethod make(query: str | X | None, pos_kwargs: Mapping[str, Any] | None = None, **kwargs: Any) → Y[source]

Make an element.

make_safe(query: None, pos_kwargs: Mapping[str, Any] | None = None, **kwargs: Any) → None[source]
make_safe(query: X | str, pos_kwargs: Mapping[str, Any] | None = None, **kwargs: Any) → Y

Run make, but pass through a none query.

normalize(s: str) → str[source]

Normalize the string with this resolve’s suffix.

optuna_lookup(trial: optuna.Trial, name: str) → X[source]

Suggest an element from this resolver for hyper-parameter optimization in Optuna.

Parameters:

  • trial – A trial object from optuna. Note that this object shouldn’t be constructed by the developer, and should only get constructed inside the optuna framework when using optuna.Study.optimize().

  • name – The name of the param within an optuna study.

Returns:

An element chosen by optuna, then run through lookup().

In the following example, Optuna is used to determine the best classification algorithm from scikit-learn when applied to the famous iris dataset.

import optuna
from sklearn import datasets
from sklearn.model_selection import train_test_split

from class_resolver.contrib.sklearn import classifier_resolver


def objective(trial: optuna.Trial) -> float:
    x, y = datasets.load_iris(return_X_y=True)
    x_train, x_test, y_train, y_test = train_test_split(
        x, y, test_size=0.33, random_state=42,
    )
    clf_cls = classifier_resolver.optuna_lookup(trial, "model")
    clf = clf_cls()
    clf.fit(x_train, y_train)
    return clf.score(x_test, y_test)


study = optuna.create_study(direction="maximize")
study.optimize(objective, n_trials=100)
register(element: X, synonyms: Iterable[str] | None = None, raise_on_conflict: bool = True) → None[source]

Register an additional element with this resolver.

Parameters:

  • element – The element to register

  • synonyms – An optional iterable of synonyms to add for the element

  • raise_on_conflict – Determines the behavior when a conflict is encountered on either the normalized element name or a synonym. If true, will raise an exception. If false, will simply disregard the entry.

Raises:
register_entrypoint(group: str) → None[source]

Register additional entries from an entrypoint.