Tools

This provides the API for creating custom names databases.

Command Scripts

The following are the core command scripts that automate the main actions mkname.tools is intended to perform.

mkname.tools.add(dst_path: Path | str, name: str, source: str = 'unknown', culture: str = 'unknown', date: int = 1970, gender: str = 'unknown', kind: str = 'unknown') → None[source]

Add a name to a names database.

Parameters:

  • dst_path – The database destination for the new name.

  • name – The name.

  • source – The URL where the name was found.

  • culture – The culture or nation the name is tied to.

  • date – The approximate year the name is tied to.

  • gender – The gender typically associated with the name during the time and in the culture the name is from.

  • kind – A tag for how the name is used, such as a given name or a surname.

Returns:

None.

Return type:

NoneType

mkname.tools.copy(dst_path: Path | str | None) → Path[source]

Copy a names database to a new location.

Parameters:

dst_path – The destination of the copy.

Returns:

A pathlib.Path object.

Return type:

pathlib.Path

mkname.tools.export(dst_path: Path | str, src_path: Path | str | None = None, cfg_path: Path | str | None = None, overwrite: bool = False) → None[source]

Export names databases to CSV files for manual updating.

Parameters:

  • dst_path – The CSV destination for the export.

  • src_path – (Optional.) The database source of the data to export. Defaults to the default database.

  • overwrite – (Optional.) Whether to overwrite an existing destination path. Defaults to False.

mkname.tools.import_(dst_path: Path | str, src_path: Path | str, format: str = 'csv', source: str = 'unknown', date: int = 1970, kind: str = 'unknown', update: bool = False) → None[source]

Import names from a file to a database.

Parameters:

  • dst_path – The database destination for the import.

  • src_path – The source of the name data to import.

  • format – The format of the source data. Valid options are csv, census.name, and census.gov.

  • source – (Optional.) Where the source data comes from. Defaults to unknown. This is used only for formats that need it.

  • date – (Optional.) The approximate year for the imported data. Defaults to 1970. This is used only for formats that need it.

  • kind – (Optional.) The kind of name in the imported data. Defaults to unknown. This is used only for formats that need it.

  • update – (Optional.) Whether to update records with colliding IDs or throw an error. Defaults to False, which throws the error.

Returns:

None.

Return type:

NoneType

mkname.tools.new(dst_path: Path | str | None = None) → Path[source]

Create an empty names database.

Parameters:

dst_path – The database destination for the import.

Returns:

A pathlib.Path object.

Return type:

pathlib.Path

Read Source Data

These functions can read common sources of name data for use in a name databases.

mkname.tools.read_csv(path: str | Path) → tuple[Name, ...][source]

Deserialize mkname.model.Name objects serialized to a CSV file.

Parameters:

path – The location of the file to read.

Returns:

A tuple object.

Return type:

tuple

mkname.tools.read_name_census(path: str | Path, source: str, year: int, kind: str, headers: bool = True) → tuple[Name, ...][source]

Read a CSV file containing census.name formatted name data.

Parameters:

  • path – The path to the CSV file.

  • source – The URL for the data source.

  • date – The year the data comes from.

  • kind – A tag for how the name is used, such as a given name or a surname.

  • headers – Whether the file has headers that need to be ignored. Defaults to True.

Returns:

A tuple object.

Return type:

tuple

mkname.tools.read_us_census(path: str | Path, source: str, culture: str = 'United States', year: int = 1970, gender: str = 'none', kind: str = 'surname', headers: bool = True) → tuple[Name, ...][source]

Deserialize name data in U.S. Census name frequency data.

Parameters:

  • path – The path to the TSV file.

  • source – The URL for the data source.

  • culture – The culture or nation the data is tied to.

  • date – The approximate year the data is tied to.

  • gender – The gender typically associated with the data during the time and in the culture the name is from.

  • kind – A tag for how the data is used, such as a given name or a surname.

  • headers – Whether the file has headers that need to be ignored. Defaults to True.

Returns:

A tuple object.

Return type:

tuple

Write Data

This function writes a name databases out to a file for editing.

mkname.tools.write_as_csv(path: str | Path, names: Sequence[Name], overwrite: bool = False) → None[source]

Serialize the given mkname.model.Name objects as a CSV file.

Parameters:

  • path – Where to save the names.

  • names – The names to save.

  • overwrite – Whether to overwrite an existing file.

Returns:

None.

Return type:

NoneType

Utility Functions

This function manipulates names data in useful ways.

mkname.tools.reindex(names: Sequence[Name], offset: int = 0) → tuple[Name, ...][source]

Reindex the given sequence of names.

Parameters:

  • names – A sequence of names to reindex.

  • offset – The first index when reindexing.

Returns:

A tuple object.

Return type:

tuple