Skip to content

Races

races

Race definitions for the application.

This module defines the canonical set of supported character races using a string-based enumeration. It also provides a helper function for parsing and validating user input (e.g., from CLI arguments).

The enum values are lowercase strings to align with CLI input and external representations.

Example 
>>> parse_race("elf")
<Race.ELF: 'elf'>

>>> parse_race("orc")
Traceback (most recent call last):
    ...
ValueError: Invalid race: orc

Race

Bases: StrEnum

Enumeration of supported character races.

This enum uses StrEnum so that each member behaves like a string, making it convenient for CLI parsing, serialization, and comparison.

Values are automatically generated as lowercase strings matching the member names.

Members
  • DWARF: Dwarf race
  • ELF: Elf race
  • HALFLING: Halfling race
  • HUMAN: Human race
Source code in src/rpgleveler/core/races.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
class Race(StrEnum):
    """
    Enumeration of supported character races.

    This enum uses `StrEnum` so that each member behaves like a string, making
    it convenient for CLI parsing, serialization, and comparison.

    Values are automatically generated as lowercase strings matching the member
    names.

    Members:
        - DWARF: Dwarf race
        - ELF: Elf race
        - HALFLING: Halfling race
        - HUMAN: Human race
    """
    DWARF = auto()
    ELF = auto()
    HALFLING = auto()
    HUMAN = auto()

parse_race(race)

Parse a string into a Race enum value.

This function is intended for use at system boundaries (e.g., CLI input), where user-provided strings must be validated and converted into strongly-typed enum values.

Parameters:

Name Type Description Default
race str

The input string representing a character race.

 required

Returns:

Type Description
Race

A corresponding Race enum value.

Raises:

Type Description
ValueError

If the input does not match any valid race.
Example 
>>> parse_race("human")
<Race.HUMAN: 'human'>
Source code in src/rpgleveler/core/races.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def parse_race(race: str) -> Race:
    """
    Parse a string into a `Race` enum value.

    This function is intended for use at system boundaries (e.g., CLI input),
    where user-provided strings must be validated and converted into
    strongly-typed enum values.

    Args:
        race: The input string representing a character race.

    Returns:
        A corresponding `Race` enum value.

    Raises:
        ValueError: If the input does not match any valid race.

    Example:
        ```
        >>> parse_race("human")
        <Race.HUMAN: 'human'>
        ```
    """
    try:
        return Race(race)
    except ValueError:
        raise ValueError(f"Invalid race: {race}")