pg.oneof

Accessible via pg.oneof, pg.one_of, pg.hyper.oneof, pg.hyper.one_of.

oneof(candidates, *, name=None, hints=None)[source]

N choose 1.

Example:

@pg.members([
  ('x', pg.typing.Int())
])
class A(pg.Object):
  pass

# A single categorical choice:
v = pg.oneof([1, 2, 3])

# A complex type as candidate.
v1 = pg.oneof(['a', {'x': 1}, A(1)])

# A hierarchical categorical choice:
v2 = pg.oneof([
    'foo',
    'bar',
    A(pg.oneof([1, 2, 3]))
])

See also: :rtype: Any

Note

Under symbolic mode (by default), pg.oneof returns a pg.hyper.OneOf object. Under dynamic evaluation mode, which is called under the context of pg.hyper.DynamicEvaluationContext or pg.hyper.DynamicEvaluationContext, it evaluates to a concrete candidate value.

To use conditional search space in dynamic evaluation mode, the candidate should be wrapped with a lambda function, which is not necessary under symbolic mode. For example:

pg.oneof([lambda: pg.oneof([0, 1], name='sub'), 2], name='root')
Parameters:

  • candidates – Candidates to select from. Items of candidate can be any type, therefore it can have nested hyper primitives, which forms a hierarchical search space.

  • name – A name that can be used to identify a decision point in the search space. This is needed when the code to instantiate the same hyper primitive may be called multiple times under a pg.DynamicEvaluationContext.collect context or under a pg.DynamicEvaluationContext.apply context.

  • hints – An optional value which acts as a hint for the controller.

Returns:

In symbolic mode, this function returns a ChoiceValue. In dynamic evaluation mode, this function returns one of the items in candidates. If evaluated under a pg.DynamicEvaluationContext.apply scope, this function will return the selected candidate. If evaluated under a pg.DynamicEvaluationContext.collect scope, it will return the first candidate.