FunctionResolver

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

Bases: Generic[P, T], BaseResolver[Callable[[P], T], Callable[[P], T]]

A resolver for functions.

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 a function.
make(query[, pos_kwargs])	Make a function with partial bindings to the given kwargs.
make_safe(query[, pos_kwargs])	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

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()

extract_name(element: Callable[[P], T]) → str

Get the name for an element.

extract_synonyms(element: X) → Collection[str]

Get synonyms from an element.

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

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]

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

lookup(query: str | Callable[[P], T] | None, default: Callable[[P], T] | None = None) → Callable[[P], T]

Lookup a function.

make(query: str | Callable[[P], T] | None, pos_kwargs: Mapping[str, Any] | None = None, **kwargs: Any) → Callable[[P], T]

Make a function with partial bindings to the given kwargs.

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

Run make, but pass through a none query.

normalize(s: str) → str

Normalize the string with this resolve’s suffix.

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

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

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:

• RegistrationNameConflict – If raise_on_conflict is true and there’s a conflict with the lookup dict

• RegistrationSynonymConflict – If raise_on_conflict is true and there’s a conflict with the synonym dict

• ValueError – If any given synonyms are empty strings

register_entrypoint(group: str) → None

Register additional entries from an entrypoint.