Skip to content

Persons

Generate random persons.

PersonParams

Bases: BaseModel

Parameters for people generation.

Parameters:

Name Type Description Default
locale str

Locale for names

'et_EE'
number int

Number of people

5
Source code in src/snailz/persons.py
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class PersonParams(BaseModel):
    """Parameters for people generation."""

    locale: str = Field(default="et_EE", description="Locale for names")
    number: int = Field(default=5, gt=0, description="Number of people")

    model_config = {"extra": "forbid"}

    @field_validator("locale")
    def validate_fields(cls, v):
        """Validate that the locale is available in faker."""
        if v not in faker.config.AVAILABLE_LOCALES:
            raise ValueError(f"Unknown locale {v}")
        return v

validate_fields(v)

Validate that the locale is available in faker.

Source code in src/snailz/persons.py
20
21
22
23
24
25
@field_validator("locale")
def validate_fields(cls, v):
    """Validate that the locale is available in faker."""
    if v not in faker.config.AVAILABLE_LOCALES:
        raise ValueError(f"Unknown locale {v}")
    return v

Person

Bases: BaseModel

A single person.

Parameters:

Name Type Description Default
ident str

unique identifier

required
family str

family name

required
personal str

personal name

required
Source code in src/snailz/persons.py
28
29
30
31
32
33
34
35
class Person(BaseModel):
    """A single person."""

    ident: str = Field(description="unique identifier")
    family: str = Field(description="family name")
    personal: str = Field(description="personal name")

    model_config = {"extra": "forbid"}

AllPersons

Bases: BaseModel

A set of generated people.

Parameters:

Name Type Description Default
items list[Person]

all persons

required
Source code in src/snailz/persons.py
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class AllPersons(BaseModel):
    """A set of generated people."""

    items: list[Person] = Field(description="all persons")

    model_config = {"extra": "forbid"}

    def to_csv(self) -> str:
        """Create a CSV representation of the people data.

        Returns:
            A CSV-formatted string with people data.
        """
        return utils.to_csv(
            self.items,
            ["ident", "personal", "family"],
            lambda p: [p.ident, p.personal, p.family],
        )

to_csv()

Create a CSV representation of the people data.

Returns:

Type Description
str

A CSV-formatted string with people data.

Source code in src/snailz/persons.py
45
46
47
48
49
50
51
52
53
54
55
def to_csv(self) -> str:
    """Create a CSV representation of the people data.

    Returns:
        A CSV-formatted string with people data.
    """
    return utils.to_csv(
        self.items,
        ["ident", "personal", "family"],
        lambda p: [p.ident, p.personal, p.family],
    )

persons_generate(params)

Generate random persons.

Parameters:

Name Type Description Default
params PersonParams

Data generation parameters.

required

Returns:

Type Description
AllPersons

Data model including all persons.

Source code in src/snailz/persons.py
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def persons_generate(params: PersonParams) -> AllPersons:
    """Generate random persons.

    Parameters:
        params: Data generation parameters.

    Returns:
        Data model including all persons.
    """
    fake = faker.Faker(params.locale)
    fake.seed_instance(random.randint(0, 1_000_000))
    id_gen = utils.unique_id("person", _person_id_generator)
    items = []
    for _ in range(params.number):
        family = fake.last_name()
        personal = fake.first_name()
        ident = id_gen.send((family, personal))
        items.append(
            Person(
                ident=ident,
                family=family,
                personal=personal,
            )
        )

    return AllPersons(items=items)

_person_id_generator(family, personal)

Generate unique ID for a person.

Parameters:

Name Type Description Default
family str

Person's family name.

required
personal str

Person's personal name.

required

Returns:

Type Description
str

Candidate identifier 'CCNNNN'.

Source code in src/snailz/persons.py
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def _person_id_generator(family: str, personal: str) -> str:
    """Generate unique ID for a person.

    Parameters:
        family: Person's family name.
        personal: Person's personal name.

    Returns:
        Candidate identifier 'CCNNNN'.
    """
    f = family[0].lower()
    p = personal[0].lower()
    num = random.randint(0, 9999)
    return f"{f}{p}{num:04d}"