randname package¶

randname.randname module¶

Main module for randname

Todo

TODO P0: Write unit tests for existing code

Todo

TODO P1: Refactor code and review variable names

Todo

TODO P2: Add database validation function

Todo

TODO P3: Move from os.path to Path

Example usage of module:

>>> import randname
>>> randname.full_name()
'John Doe'

class randname.randname.Randname¶

Bases: object

database = <randname.database.Database object>¶

classmethod full_name(*args, **kwargs)¶

classmethod first_name(*args, **kwargs)¶

classmethod last_name(*args, **kwargs)¶

randname.randname.full_name(year: Optional[int] = None, sex: Optional[str] = None, country: Optional[str] = None, weights: bool = True, show_warnings: bool = WARNINGS, database: str = DATABASE) → str¶

Return full name

Parameters

year (int, optional) – year of birth, defaults to None
sex (str, optional) – sex’s name, defaults to None
country (str, optional) – country of origin, defaults to None
weights (bool, optional) – use population distribution if True, else treat all names with same probability, defaults to True
show_warnings (bool, optional) – show warnings, defaults to WARNINGS
database (str, optional) – path to database, defaults to DATABASE

Raises

InvalidSexArgument – if sex is not in proper sex options
InvalidCountryName – if country is not in valid countries

Returns

full name

Return type

str

>>> full_name()
'John Doe'

randname.randname.last_name(year: Optional[int] = None, sex: Optional[str] = None, country: Optional[str] = None, weights: bool = True, show_warnings: bool = WARNINGS, database: str = DATABASE) → str¶

Return random last name

Parameters

year (int, optional) – year of birth, defaults to None
sex (str, optional) – sex’s name, defaults to None
country (str, optional) – country of origin, defaults to None
weights (bool, optional) – use population distribution if True, else treat all names with same probability, defaults to True
show_warnings (bool, optional) – show warnings, defaults to WARNINGS
database (str, optional) – path to database, defaults to DATABASE

Raises

InvalidSexArgument – if sex is not in proper sex options
InvalidCountryName – if country is not in valid countries

Returns

last name

Return type

str

>>> last_name()
'Doe'

randname.randname.first_name(year: Optional[int] = None, sex: Optional[str] = None, country: Optional[str] = None, weights: bool = True, show_warnings: bool = WARNINGS, database: str = DATABASE) → str¶

Return random first name

Parameters

year (int, optional) – year of birth, defaults to None
sex (str, optional) – sex’s name, defaults to None
country (str, optional) – country of origin, defaults to None
weights (bool, optional) – use population distribution if True, else treat all names with same probability, defaults to True
show_warnings (bool, optional) – show warnings, defaults to WARNINGS
database (str, optional) – path to database, defaults to DATABASE

Raises

InvalidSexArgument – if sex is not in proper sex options
InvalidCountryName – if country is not in valid countries

Returns

first name

Return type

str

>>> first_name()
'John'

randname.randname.available_countries(path_to_database: str = DATABASE) → set¶

Return set of available countries

Returns: set of available countries
Return type: set

>>> available_countries()
{'ES', 'PL', 'US'}

randname.randname.show_data(path_to_database: str = DATABASE) → dict¶

Return dictionary with information about database.

Returns: information about database
Return type: dict

>>> show_data()
{
    'ES': {'first_names': ['M'], 'last_names': ['N']},
    'PL': {'first_names': ['M', 'F'], 'last_names': ['M', 'F']},
    'US': {'first_names': ['M', 'F'], 'last_names': ['N']}
}

randname.randname.validate_database(path_to_database: pathlib.Path) → bool¶

Validate database

Parameters: path_to_database (Path) – path to database
Returns: True if database is valid, else False
Return type: bool

randname.database module¶

Database module

class randname.database.Database(path_to_database: Union[pathlib.Path, str])¶

Bases: object

schema_info_json = {'additionalProperties': False, 'description': 'Schema for info.json file', 'properties': {'country': {'type': 'string'}, 'first_names': {'items': {'type': 'string'}, 'minItems': 1, 'type': 'array'}, 'last_names': {'items': {'type': 'string'}, 'minItems': 1, 'type': 'array'}}, 'required': ['country', 'first_names', 'last_names'], 'title': 'info.json schema', 'type': 'object'}¶

schema_name_json = {'additionalProperties': False, 'description': 'Schema for last and first names files', 'properties': {'Names': {'items': {'type': 'string'}, 'minItems': 1, 'type': 'array'}, 'Totals': {'items': {'type': 'number'}, 'minItems': 1, 'type': 'array'}}, 'required': ['Names', 'Totals'], 'title': 'first_names and last_names schema', 'type': 'object'}¶

draft_validator_info = Draft7Validator(schema={'additionalProperties': False, 'description': 'Schema for info.json file', 'properties': {'country': {'type': 'string'}, 'first_names': {'items': {'type': 'string'}, 'minItems': 1, 'type': 'array'}, 'last_names': {'items': {'type': 'string'}, 'minItems': 1, 'type': 'array'}}, 'required': ['country', 'first_names', 'last_names'], ...}, format_checker=None)¶

draft_validator_name = Draft7Validator(schema={'additionalProperties': False, 'description': 'Schema for l...t names files', 'properties': {'Names': {'items': {'type': 'string'}, 'minItems': 1, 'type': 'array'}, 'Totals': {'items': {'type': 'number'}, 'minItems': 1, 'type': 'array'}}, 'required': ['Names', 'Totals'], ...}, format_checker=None)¶

property path: pathlib.Path¶

Path to database

Returns: path to database
Return type: Path

validate(path_to_database: Optional[Union[pathlib.Path, str]] = None) → None¶

Check if database has valid structure and it’s files are correctly formatted.

..warning::: Validating database might take some time, depends how large is the database.

Parameters

path_to_database (Union[Path, str]) – path to database

Raises

randname.error.DirectoryDoesNotExist – raise when directory with database does not exist.
randname.error.MissingInfoFile – raise when info.json is missing.
randname.error.GenderMismatch – raise when gender information in info.json does not match to what is in directories.
randname.error.FileNameDoesNotMatchPattern – raise when file with names doesn’t mach naming convention.
jsonschema.ValidationError – raise when json file doesn’t match pattern.

randname.error module¶

Error module

exception randname.error.InvalidSexArgument(sex: str, available_sex: list)¶

Bases: Exception

InvalidSexArgument.

Raise when selected sex is not it available for chosen country.

exception randname.error.InvalidCountryName(country: str, available_countries: list)¶

Bases: Exception

Raise when country is not in available countries list

exception randname.error.DirectoryDoesNotExist¶

Bases: Exception

Raise when specified directory with database does not exist.

Todo

TODO: To implement

exception randname.error.MissingInfoFile¶

Bases: Exception

Raise when info.json file is missing in the country directory.

Todo

TODO: To implement

exception randname.error.FileNameDoesNotMatchPattern¶

Bases: Exception

Raise when file doesn’t match the pattern.

Todo

TODO: To implement

exception randname.error.GenderMismatch¶

Bases: Exception

Raise when supported genders defined in info.json does not match to what is in corresponding folders

Todo

TODO: To implement

randname package¶

randname.randname module¶

randname.database module¶

randname.error module¶

Table of Contents

Previous topic

This Page