Persons - Snailz Docs

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))
        gen = utils.UniqueIdGenerator("person", _person_id_generator)
        items = []
        for _ in range(params.number):
            f = fake.last_name()
            p = fake.first_name()
            i = gen.next(f, p)
            items.append(
                Person(
                    ident=i,
                    family=f,
                    personal=p,
                )
            )

        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}"