.. _db_customization:

##############################
Customizing the Names Database
##############################
The names generated by :mod:`mkname` come from data stored within a
database stored within the package. I don't recommend modifying that
database because it could cause problems with future updates to
:mod:`mkname`. However, :mod:`mkname` does have tools that allow you
to create names databases of your own to use instead of the default
one supplied with the package.

The easiest, and best documented, way to do this is to use the
`mkname_tools` script supplied with the :mod:`mkname` package. I'll
get into details about some of the things it can do below, but if
you ever want a quick overview of everything it does, you can access
its help at the command line::

    mkname_tools -h


.. _copy_default_db:

Copying the Default Names Database
==================================
The easiest way to get started making a custom `names.db` is to
create a copy of the default database supplied with the package.
Let's say you want to create a copy of the `names.db` in the
current working directory::

    mkname_tools copy

You can copy the database to a specific path with the `-o` option::

    mkname_tools copy -o data/spam.db


.. _create_empty_db:

Creating an Empty Database
==========================
If you want to start from scratch without any of the information from
the default database, you can create an empty database. If you want to
create an empty `names.db` in the current working directory::

    mkname_tools new

If you want to create the empty database in a specific location::

    mkname_tools new -o data/spam.db


.. _add_name_to_db:

Adding a Name to a Names Database
=================================
Once you have created your new names database, it's time to add new
names to it. If you just need to add a single name, you can do that
manually::

    mkname_tools add data/spam.db --name Graham
    --source https://montypython.com --culture MontyPython
    --date 1941 --gender python --kind given

The difference options needed when adding a new name to a database
correspond to the fields for a record in the names database. See
the The Name fields: :ref:`name_fields`


.. _importing_names:

Importing Serialized Names Data
===============================
The easiest way of customizing a names database is:

*   Export an existing names database to a CSV file.
*   Use the spreadsheet software of your choice to add names to
    the CSV file.
*   Import the CSV file into a new names database file.

.. warning:
    :mod:`mkname` tries to prevent changes to the default
    database to prevent unexpected problems when you update
    the package. While it's possible to bypass those protections,
    I highly recommend that you don't. Instead, create a copy
    of the names database to modify and use that modified copy
    for name generation.

To export a copy of the default database to a CSV file::

    mkname_tools export -o data/spam.csv

To import it into a new names database once changes have been made::

    mkname_tools import -f csv -i data/spam.csv -o data/spam.db --update


.. _using_tools_api:

Using the Tools API
===================
If you want to use the :mod:`mkname.tools` API to create a custom
names database, you can. The API is documented here: :ref:`tools_api`.