Skip to content

People

Generate synthetic people.

PeopleParams

Bases: BaseModel

Parameters for people generation.

  • locale: Locale code for generating names (must be supported by Faker)
  • number: Number of people to generate (must be positive)
  • seed: Random seed for reproducibility
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
31
class PeopleParams(BaseModel):
    """Parameters for people generation.

    - locale: Locale code for generating names (must be supported by Faker)
    - number: Number of people to generate (must be positive)
    - seed: Random seed for reproducibility
    """

    locale: str = Field()
    number: int = Field(gt=0)
    seed: int = Field()

    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
26
27
28
29
30
31
@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.

  • family: family name
  • ident: unique identifier
  • personal: personal name
Source code in src/snailz/people.py
34
35
36
37
38
39
40
41
42
43
44
class Person(BaseModel):
    """A single person.

    - family: family name
    - ident: unique identifier
    - personal: personal name
    """

    family: str
    ident: str
    personal: str

AllPersons

Bases: BaseModel

A set of generated people.

  • individuals: list of people
  • params: parameters used to generate this data
Source code in src/snailz/people.py
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
class AllPersons(BaseModel):
    """A set of generated people.

    - individuals: list of people
    - params: parameters used to generate this data
    """

    individuals: list[Person]
    params: PeopleParams

    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
57
58
59
60
61
62
63
64
65
66
67
68
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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
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)