Skip to content

People

Generate synthetic people.

PeopleParams

Bases: BaseModel

Parameters for people generation.

Parameters:

Name Type Description Default
locale str

Locale code for generating names (must be supported by Faker)

required
number int

Number of people to generate (must be positive)

required
seed int

Random seed for reproducibility

required
Source code in src/snailz/people.py
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
class PeopleParams(BaseModel):
    """Parameters for people generation."""

    locale: str = Field(
        description="Locale code for generating names (must be supported by Faker)"
    )
    number: int = Field(
        gt=0, description="Number of people to generate (must be positive)"
    )
    seed: int = Field(ge=0, description="Random seed for reproducibility")

    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/people.py
25
26
27
28
29
30
@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
family str

family name

required
ident str

unique identifier

required
personal str

personal name

required
Source code in src/snailz/people.py
33
34
35
36
37
38
class Person(BaseModel):
    """A single person."""

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

AllPersons

Bases: BaseModel

A set of generated people.

Parameters:

Name Type Description Default
individuals list[Person]

list of people

required
params PeopleParams

parameters used to generate data

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

    individuals: list[Person] = Field(description="list of people")
    params: PeopleParams = Field(description="parameters used to generate data")

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

        Returns:
            A CSV-formatted string with people data (without parameters) using Unix line endings
        """
        output = io.StringIO()
        writer = utils.csv_writer(output)
        writer.writerow(["ident", "personal", "family"])
        for person in self.individuals:
            writer.writerow([person.ident, person.personal, person.family])
        return output.getvalue()

to_csv()

Return a CSV string representation of the people data.

Returns:

Type Description
str

A CSV-formatted string with people data (without parameters) using Unix line endings

Source code in src/snailz/people.py
47
48
49
50
51
52
53
54
55
56
57
58
def to_csv(self) -> str:
    """Return a CSV string representation of the people data.

    Returns:
        A CSV-formatted string with people data (without parameters) using Unix line endings
    """
    output = io.StringIO()
    writer = utils.csv_writer(output)
    writer.writerow(["ident", "personal", "family"])
    for person in self.individuals:
        writer.writerow([person.ident, person.personal, person.family])
    return output.getvalue()

people_generate(params)

Generate synthetic people data.

Parameters:

Name Type Description Default
params PeopleParams

PeopleParams object

required

Returns:

Type Description
AllPersons

AllPersons object containing generated individuals and parameters

Source code in src/snailz/people.py
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def people_generate(params: PeopleParams) -> AllPersons:
    """Generate synthetic people data.

    Parameters:
        params: PeopleParams object

    Returns:
        AllPersons object containing generated individuals and parameters
    """
    fake = Faker(params.locale)
    fake.seed_instance(params.seed)
    gen = utils.UniqueIdGenerator(
        "people",
        lambda p, f: f"{f[0].lower()}{p[0].lower()}{random.randint(0, 9999):04d}",
    )

    individuals = []
    for _ in range(params.number):
        personal = fake.first_name()
        family = fake.last_name()
        ident = gen.next(personal, family)
        individuals.append(Person(personal=personal, family=family, ident=ident))

    return AllPersons(individuals=individuals, params=params)