choice - Constrained Types¶
Lightweight constrained types without full Enum classes. Perfect for simple value restrictions.
Constrain a string field to a fixed set of allowed values.
This creates a validated subtype of str that only accepts a defined set
of literal values. It behaves like a normal string at runtime and integrates
directly with Pydantic v2.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
str
|
Allowed string values. |
()
|
Returns:
| Type | Description |
|---|---|
type[str]
|
A callable type validator for the specified string literals. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If a provided value is not one of the allowed literals. |
Examples:
Basic usage: >>> Color = strChoice("red", "green", "blue") >>> Color("red") 'red' >>> Color("yellow") Traceback (most recent call last): ... ValueError: 'yellow' is not one of ('red', 'green', 'blue')
Integration with Pydantic: >>> from xpyt_pydantic import BaseModel >>> class Item(BaseModel): ... color: Color >>> Item(color="green") Item(color='green') >>> Item(color="purple") Traceback (most recent call last): ... pydantic_core._pydantic_core.ValidationError: ...
Source code in xpytools/xtype/choice/strChoice.py
def strChoice(*choices: str) -> type[str]:
"""
Constrain a string field to a fixed set of allowed values.
This creates a **validated subtype of `str`** that only accepts a defined set
of literal values. It behaves like a normal string at runtime and integrates
directly with **Pydantic v2**.
Parameters
----------
*choices : str
Allowed string values.
Returns
-------
type[str]
A callable type validator for the specified string literals.
Raises
------
ValueError
If a provided value is not one of the allowed literals.
Examples
--------
Basic usage:
>>> Color = strChoice("red", "green", "blue")
>>> Color("red")
'red'
>>> Color("yellow")
Traceback (most recent call last):
...
ValueError: 'yellow' is not one of ('red', 'green', 'blue')
Integration with Pydantic:
>>> from xpyt_pydantic import BaseModel
>>> class Item(BaseModel):
... color: Color
>>> Item(color="green")
Item(color='green')
>>> Item(color="purple")
Traceback (most recent call last):
...
pydantic_core._pydantic_core.ValidationError: ...
"""
return cast(type[str], _LiteralEnumType(*choices))
Constrain an integer field to a fixed set of allowed values.
This creates a validated subtype of int that behaves like a regular integer
but restricts its possible values. It’s ideal for representing enums like
status codes or fixed numeric constants.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
int
|
Allowed integer values. |
()
|
Returns:
| Type | Description |
|---|---|
type[int]
|
A callable validated integer type. |
Examples:
>>> Code = intChoice(200, 404, 500)
>>> Code(200)
200
>>> Code(403)
Traceback (most recent call last):
...
ValueError: 403 is not one of (200, 404, 500)
Source code in xpytools/xtype/choice/intChoice.py
def intChoice(*choices: int) -> type[int]:
"""
Constrain an integer field to a fixed set of allowed values.
This creates a **validated subtype of `int`** that behaves like a regular integer
but restricts its possible values. It’s ideal for representing enums like
status codes or fixed numeric constants.
Parameters
----------
*choices : int
Allowed integer values.
Returns
-------
type[int]
A callable validated integer type.
Examples
--------
>>> Code = intChoice(200, 404, 500)
>>> Code(200)
200
>>> Code(403)
Traceback (most recent call last):
...
ValueError: 403 is not one of (200, 404, 500)
"""
return cast(type[int], _LiteralEnumType(*choices))
Constrain a float field to a fixed set of allowed values.
Behaves exactly like float (supports math operations, .real, .is_integer(), etc.)
but enforces allowed literal values at runtime.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
float
|
Allowed float values. |
()
|
Returns:
| Type | Description |
|---|---|
type[float]
|
A callable validated float type. |
Examples:
>>> Precision = floatChoice(0.1, 0.01, 0.001)
>>> Precision(0.1)
0.1
>>> Precision(1.0)
Traceback (most recent call last):
...
ValueError: 1.0 is not one of (0.1, 0.01, 0.001)
Source code in xpytools/xtype/choice/floatChoice.py
def floatChoice(*choices: float) -> type[float]:
"""
Constrain a float field to a fixed set of allowed values.
Behaves exactly like `float` (supports math operations, `.real`, `.is_integer()`, etc.)
but enforces allowed literal values at runtime.
Parameters
----------
*choices : float
Allowed float values.
Returns
-------
type[float]
A callable validated float type.
Examples
--------
>>> Precision = floatChoice(0.1, 0.01, 0.001)
>>> Precision(0.1)
0.1
>>> Precision(1.0)
Traceback (most recent call last):
...
ValueError: 1.0 is not one of (0.1, 0.01, 0.001)
"""
return cast(type[float], _LiteralEnumType(*choices))
Constrain a field to a fixed set of arbitrary values.
This is the most flexible variant of LiteralEnum. It accepts mixed types
(e.g., strings, ints, objects) and enforces that runtime values match one
of the provided choices exactly.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
|
Any
|
Arbitrary allowed values. Typing.Types may differ. |
()
|
Returns:
| Type | Description |
|---|---|
type
|
A callable validated type (base type = Any). |
Examples:
>>> Mixed = anyChoice("foo", 1, 2.5, {})
>>> Mixed("foo")
'foo'
>>> Mixed({})
{}
>>> Mixed("bar")
Traceback (most recent call last):
...
ValueError: 'bar' is not one of ('foo', 1, 2.5, {})
Source code in xpytools/xtype/choice/anyChoice.py
def anyChoice(*choices: Any):
"""
Constrain a field to a fixed set of **arbitrary values**.
This is the most flexible variant of `LiteralEnum`. It accepts mixed types
(e.g., strings, ints, objects) and enforces that runtime values match one
of the provided choices exactly.
Parameters
----------
*choices : Any
Arbitrary allowed values. Typing.Types may differ.
Returns
-------
type
A callable validated type (base type = Any).
Examples
--------
>>> Mixed = anyChoice("foo", 1, 2.5, {})
>>> Mixed("foo")
'foo'
>>> Mixed({})
{}
>>> Mixed("bar")
Traceback (most recent call last):
...
ValueError: 'bar' is not one of ('foo', 1, 2.5, {})
"""
return _LiteralEnumType(*choices)