Including your own generators

There are two types of generators; row generators (possibly a misnomer) and story generators. While there are many row generators included with datafaker (such as dist_gen.normal or generic.text.first_name), there are no story generators.

However, you can make your own!

Row generators

The configure-generators command allows you to set the included row generators for single columns. It is possible to have row generators that set more than one column at a time, but none of the built-in generators do this; to add your own Python functions that write any number of values at once, put them into a file and copy it to the directory you are running datafaker from. Now set the name of this file (minus the .py) as the row_generators_module in your config.yaml, for example:

row_generators_module: my_row_gens
tables:
person:
   row_generators:
      - name: my_row_gens.generate_ifespan
        kwargs:
          current_year: 2025
        columns_assigned: birthdate, deathdate

This will call the function lifespan in your my_row_gens.py file with argument current_year=2025; it must produce a tuple of two values, which will be put into the birthdate and deathdate columns of the person table.

You might prefer to instantiate one or more classes at the start and call methods on them for each value or tuple of values generated. This is achieved with object_instantiation in the following way:

row_generators_module: my_row_gens
object_instantiation:
uct:
   class: my_row_gens.Lifespan
   kwargs:
      current_year: 2025
tables:
person:
   row_generators:
      - name: uct.generate_ifespan
        columns_assigned: birthdate, deathdate

Here we are instantiating a Lifespan class defined in your my_row_gens.py file. We are instantiating this class as an object called uct which is then referenced in the method call uct.generate_lifespan. We have defined this class to accept the current_year parameter in the constructor of the Lifespan class so it doesn’t have to be passed for each generate_lifespan call; we can see how the config.yaml file has changed to pass this value into the constructor instead of the method. You don’t need to do it this way, it is fine to pass extra parameters to methods of classes if you want.

Story generators

Story generators allow you to generate lines for any table in any order and create links between them. Again, you must define your own; datafaker provides no built-in story generators.

You can put your story generators in their own Python file, or you can re-use your row generators file if you like.

A story generator is a Python Generator function (a function that calls yield to return multiple values rather than return a single one).