People - Snailz Docs

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()

        @field_validator("locale")
        def validate_locale(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

        model_config = {"extra": "forbid"}

### `validate_locale(v)`

Validate that the locale is available in faker.

Source code in `src/snailz/people.py`

    24
    25
    26
    27
    28
    29
    @field_validator("locale")
    def validate_locale(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)