People - Snailz Docs

Skip to content

# People

Generate synthetic people data.

## `Person` `dataclass`

A single person with personal and family names.

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

    22
    23
    24
    25
    26
    27
    28
    @dataclass
    class Person:
        """A single person with personal and family names."""

        family: str
        ident: str
        personal: str

## `People` `dataclass`

Keep track of generated people.

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

    31
    32
    33
    34
    35
    36
    @dataclass
    class People:
        """Keep track of generated people."""

        individuals: list[Person]
        params: dict[str, object]

## `people_check(params)`

Check people generation parameters.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`params` | `dict[str, object]` | Dictionary containing people generation parameters | required

Raises:

Type | Description
--- | ---
`ValueError` | If parameters are missing, have wrong types, or have invalid values

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

    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    def people_check(params: dict[str, object]) -> None:
        """Check people generation parameters.

        Parameters:
            params: Dictionary containing people generation parameters

        Raises:
            ValueError: If parameters are missing, have wrong types, or have invalid values
        """
        utils.check_keys_and_types(PEOPLE_PARAMS, params)
        utils.require(0 < params["number"], "number must be positive")
        utils.require(
            params["locale"] in faker.config.AVAILABLE_LOCALES,
            f"unknown locale {params['locale']}",
        )

## `people_generate(params)`

Generate synthetic people data.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`params` | `dict[str, object]` | Dictionary containing people generation parameters | required

Returns:

Type | Description
--- | ---
`People` | People object containing generated individuals and parameters

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

    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    def people_generate(params: dict[str, object]) -> People:
        """Generate synthetic people data.

        Parameters:
            params: Dictionary containing people generation parameters

        Returns:
            People object containing generated individuals and parameters
        """
        people_check(params)
        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 People(individuals=individuals, params=params)

## `people_to_csv(people, filename)`

Write people data as CSV with columns for ident, personal, and family.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`people` | `People` | A People object containing the data to write | required
`filename` | `str | None` | Path to output file, or None to write to standard output | required

Side effects

Either writes to the specified output file or prints to stdout

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

     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    def people_to_csv(people: People, filename: str | None) -> None:
        """Write people data as CSV with columns for ident, personal, and family.

        Parameters:
            people: A People object containing the data to write
            filename: Path to output file, or None to write to standard output

        Side effects:
            Either writes to the specified output file or prints to stdout
        """
        stream = sys.stdout if filename is None else open(filename, "w", newline="")
        writer = csv.writer(stream)
        writer.writerow(["ident", "personal", "family"])
        for person in people.individuals:
            writer.writerow([person.ident, person.personal, person.family])
        if stream is not sys.stdout:
            stream.close()