BaseResolver

class BaseResolver(elements=None, *, default=None, synonyms=None, suffix=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 (Optional[Iterable[TypeVar(X)]]) – The elements to register
default (Optional[TypeVar(X)]) – The optional default element
synonyms (Optional[Mapping[str, TypeVar(X)]]) – The optional synonym dictionary
suffix (Optional[str]) – The optional shared suffix of all instances

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[, default, as_string, ...])	Get a click option for this resolver.
`lookup`(query[, default])	Lookup an element.
`make`(query[, pos_kwargs])	Make an element.
`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, *path, default=None)[source]

Lookup an element and get its docdata.

Parameters:

query (Union[str, TypeVar(X), None]) – The hint for looking something up in the resolver passed to lookup()
path (str) – An optional path for traversing the resulting docdata dictionary
default (Optional[TypeVar(X)]) – The default value to pass to lookup()

Returns:

The optional docdata retrieved with docdata.get_docdata()

abstract extract_name(element)[source]

Get the name for an element.

Return type:: str

extract_synonyms(element)[source]

Get synonyms from an element.

Return type:: Collection[str]

classmethod from_entrypoint(group, **kwargs)[source]

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

Return type:: BaseResolver

get_option(*flags, default=None, as_string=False, required=False, **kwargs)[source]: Get a click option for this resolver.

abstract lookup(query, default=None)[source]

Lookup an element.

Return type:: TypeVar(X)

abstract make(query, pos_kwargs=None, **kwargs)[source]

Make an element.

Return type:: TypeVar(Y)

make_safe(query, pos_kwargs=None, **kwargs)[source]

Run make, but pass through a none query.

Return type:: Optional[TypeVar(Y)]

normalize(s)[source]

Normalize the string with this resolve’s suffix.

Return type:: str

optuna_lookup(trial, name)[source]

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

Parameters:

trial (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 (str) – The name of the param within an optuna study.

Return type:

TypeVar(X)

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, synonyms=None, raise_on_conflict=True)[source]

Register an additional element with this resolver.

Parameters:

element (TypeVar(X)) – The element to register
synonyms (Optional[Iterable[str]]) – An optional iterable of synonyms to add for the element
raise_on_conflict (bool) – 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)[source]

Register additional entries from an entrypoint.

Return type:: None