ClassResolver

class ClassResolver(classes=None, *, base, default=None, suffix=None, synonyms=None, synonym_attribute='synonyms', base_as_suffix=True)

Bases: BaseResolver[Type[X], X]

Resolve from a list of classes.

Initialize the resolver.

Parameters:

• classes (Optional[Collection[Type[TypeVar(X)]]]) – A list of classes

• base (Type[TypeVar(X)]) – The base class

• default (Optional[Type[TypeVar(X)]]) – The default class

• suffix (Optional[str]) – The optional shared suffix of all instances. If not none, will override base_as_suffix.

• synonyms (Optional[Mapping[str, Type[TypeVar(X)]]]) – The optional synonym dictionary

• synonym_attribute (Optional[str]) – The attribute to look in each class for synonyms. Explicitly set to None to turn off synonym lookup.

• base_as_suffix (bool) – Should the base class’s name be used as the suffix if none is given? Defaults to true.

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.
from_subclasses(base, *[, skip, ...])	Make a resolver from the subclasses of a given class.
get_option(*flags[, default, as_string, ...])	Get a click option for this resolver.
lookup(query[, default])	Lookup a class.
make(query[, pos_kwargs])	Instantiate a class with optional kwargs.
make_from_kwargs(data, key, *[, kwargs_suffix])	Instantiate a class, by looking up query/pos_kwargs from a dictionary.
make_many([queries, kwargs])	Resolve and compose several queries together.
make_safe(query[, pos_kwargs])	Run make, but pass through a none query.
normalize(s)	Normalize the string with this resolve's suffix.
normalize_cls(cls)	Normalize the class name.
normalize_inst(x)	Normalize the class name of the instance.
optuna_lookup(trial, name)	Suggest an element from this resolver for hyper-parameter optimization in Optuna.
ray_tune_search_space([kwargs_search_space])	Return a search space for ray.tune.
register(element[, synonyms, raise_on_conflict])	Register an additional element with this resolver.
register_entrypoint(group)	Register additional entries from an entrypoint.
signature(query)	Get the signature for the given class via inspect.signature().
supports_argument(query, parameter_name)	Determine if the class constructor supports the given argument.

Attributes Documentation

options

Return the normalized option names.

Methods Documentation

docdata(query, *path, default=None)

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

extract_name(element)

Get the name for an element.

Return type:

str

extract_synonyms(element)

Get synonyms from an element.

Return type:

Collection[str]

classmethod from_entrypoint(group, **kwargs)

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

Return type:

BaseResolver

classmethod from_subclasses(base, *, skip=None, exclude_private=True, exclude_external=True, **kwargs)

Make a resolver from the subclasses of a given class.

Parameters:

• base (Type[TypeVar(X)]) – The base class whose subclasses will be indexed

• skip (Optional[Collection[Type[TypeVar(X)]]]) – Any subclasses to skip (usually good to hardcode intermediate base classes)

• exclude_private (bool) – If true, will skip any class that comes from a module starting with an underscore (i.e., a private module). This is typically done when having shadow duplicate classes implemented in C

• exclude_external (bool) – If true, will exclude any class that does not originate from the same package as the base class.

• kwargs – remaining keyword arguments to pass to Resolver.__init__()

Return type:

ClassResolver

Returns:

A resolver instance

get_option(*flags, default=None, as_string=False, required=False, **kwargs)

Get a click option for this resolver.

lookup(query, default=None)

Lookup a class.

Return type:

Type[TypeVar(X)]

make(query, pos_kwargs=None, **kwargs)

Instantiate a class with optional kwargs.

Return type:

TypeVar(X)

make_from_kwargs(data, key, *, kwargs_suffix='kwargs', **o_kwargs)

Instantiate a class, by looking up query/pos_kwargs from a dictionary.

Parameters:

• data (Mapping[str, Any]) – A dictionary that contains entry key and entry {key}_{kwargs_suffix}.

• key (str) – The key in the dictionary whose value will be put in the query argument of make().

• kwargs_suffix (str) – The suffix after key to look up the data. For example, if key='model' and kwargs_suffix='kwargs' (the default value), then the kwargs from make() are looked up via data['model_kwargs'].

• o_kwargs – Additional kwargs to be passed to make()

Return type:

TypeVar(X)

Returns:

An instance of the X datatype parametrized by this resolver

make_many(queries=None, kwargs=None, **common_kwargs)

Resolve and compose several queries together.

Parameters:

• queries (Union[str, TypeVar(X), Type[TypeVar(X)], None, Sequence[Union[str, TypeVar(X), Type[TypeVar(X)], None]]]) – Either none (will result in the default X), a single X (as either a class, instance, or string for class name), or a list of X’s (as either a class, instance, or string for class name

• kwargs (Union[Mapping[str, Any], None, Sequence[Optional[Mapping[str, Any]]]]) – Either none (will use all defaults), a single dictionary (will be used for all instances), or a list of dictionaries with the same length as queries

• common_kwargs – additional keyword-based parameters passed to all instantiated instances.

Raises:

ValueError – If the number of queries and kwargs has a mismatch

Return type:

List[TypeVar(X)]

Returns:

A list of X instances

make_safe(query, pos_kwargs=None, **kwargs)

Run make, but pass through a none query.

Return type:

Optional[TypeVar(Y)]

normalize(s)

Normalize the string with this resolve’s suffix.

Return type:

str

normalize_cls(cls)

Normalize the class name.

Return type:

str

normalize_inst(x)

Normalize the class name of the instance.

Return type:

str

optuna_lookup(trial, name)

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)

ray_tune_search_space(kwargs_search_space=None)

Return a search space for ray.tune.

ray.tune is a package for distributed hyperparameter optimization. The search space for this search is defined as a (nested) dictionary, which can contain special values tune.{choice,uniform,…}. For these values, the search algorithm will sample a specific configuration.

This method can be used to create a tune.choice sampler for the choices available to the resolver. By default, this is equivalent to

ray.tune.choice(self.options)

If additional kwargs_search_space are passed, they are assumed to be a sub-search space for the constructor parameters passed via pos_kwargs. The resulting sub-search thus looks as follows:

ray.tune.choice(
    query=self.options,
    **kwargs_search_space,
)

Parameters:

kwargs_search_space (Optional[Mapping[str, Any]]) – Additional sub search space for the constructor’s parameters.

Returns:

A ray.tune compatible search space.

Raises:

ImportError – If ray.tune is not installed.

See also

https://docs.ray.io/en/master/tune/index.html

register(element, synonyms=None, raise_on_conflict=True)

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)

Register additional entries from an entrypoint.

Return type:

None

signature(query)

Get the signature for the given class via inspect.signature().

Return type:

Signature

supports_argument(query, parameter_name)

Determine if the class constructor supports the given argument.

Return type:

bool