{"id":9138,"library":"nicknames","title":"Nicknames","description":"The 'nicknames' library provides a hand-curated dataset of English given names and their associated nicknames or diminutive names. It offers a Python API to query these relationships. The current version is 1.0.1, released on March 5, 2026, and follows a release cadence tied to data updates and feature enhancements. It is actively maintained by the Old Dominion University - Web Science and Digital Libraries Research Group. [4, 5]","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/carltonnorthern/nicknames","tags":["names","nicknames","dataset","linguistics","data processing","genealogy"],"install":[{"cmd":"pip install nicknames","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"NickNamer","correct":"from nicknames import NickNamer"},{"note":"Provides direct access to the raw data as a list of NamedTuples.","symbol":"name_triplets","correct":"from nicknames import name_triplets"}],"quickstart":{"code":"from nicknames import NickNamer, name_triplets\n\n# Initialize the NickNamer class\nnn = NickNamer()\n\n# Get nicknames for a given name\nnicks_for_alexander = nn.nicknames_of(\"Alexander\")\nprint(f\"Nicknames for Alexander: {nicks_for_alexander}\")\n# Expected: {'al', 'alex'}\n\n# Get canonical names for a given nickname\ncanonicals_for_al = nn.canonicals_of(\"al\")\nprint(f\"Canonical names for al: {canonicals_for_al}\")\n# Expected: {'alexander', 'alex'}\n\n# Check if two names are interchangeable (via nicknames or canonical forms)\nalexander_is_al_interchangeable = \"alexander\" in (nn.nicknames_of(\"al\") | nn.canonicals_of(\"al\"))\nprint(f\"Is Alexander interchangeable with al? {alexander_is_al_interchangeable}\")\n\n# Access the raw data triplets\nfirst_three_triplets = name_triplets()[:3]\nprint(f\"First three raw name triplets: {first_three_triplets}\")","lang":"python","description":"This quickstart demonstrates how to instantiate the `NickNamer` class to find nicknames for a given name and canonical names for a given nickname. It also shows how to combine these methods to check for interchangeability and how to access the raw `name_triplets` data directly. [4]"},"warnings":[{"fix":"Migrate any direct CSV parsing logic to use the `NickNamer` class methods (`nicknames_of`, `canonicals_of`) or the new lower-level `name_triplets`, `with_names_csv_path`, `name_relationships` functions, which correctly interpret the new semantic triplet format. [4, 10]","message":"Version 1.0.0 (released July 14, 2025) introduced a significant breaking change by switching the underlying data format from a 'wide' format to a 'long' format using semantic triplets (name1, relationship, name2). This impacts direct CSV parsing if you were bypassing the Python API. [10]","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your project uses Python 3.8 or higher. If you were using `load_resource()`, switch to `with_names_csv_path()` or `name_relationships()` for lower-level CSV access. [4, 10]","message":"Python 3.7 support was removed in version 1.0.0. Additionally, legacy Perl, Java, and R bindings and the `load_resource()` Python function were deprecated and removed. [10]","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"When checking for equivalence or relatedness, consider querying both directions (e.g., `nn.nicknames_of(\"name\")` and `nn.canonicals_of(\"name\")`) or combining results from both `nicknames_of` and `canonicals_of` as shown in the quickstart. [4]","message":"The relationship between a name and its nickname is not always symmetric. For example, 'al' is a nickname for 'alexander', but 'alexander' is not considered a nickname for 'al'. Direct lookups should account for this. [4]","severity":"gotcha","affected_versions":"All"},{"fix":"Be aware of this data bias when using the library for applications requiring broader demographic coverage. Contribution to expand the dataset is welcomed by the maintainers. [5]","message":"The dataset, due to its original source (genealogy page from the Center for African American Research, Inc.), has a bias towards traditionally African American names. Other name groups may be underrepresented or absent. [5]","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"The `NickNamer` class is directly available from the `nicknames` package. Use `from nicknames import NickNamer`.","cause":"Attempting to import `NickNamer` directly from a submodule instead of the top-level package. [4]","error":"ModuleNotFoundError: No module named 'nicknames.NickNamer'"},{"fix":"For lower-level access to the CSV data, use `name_triplets()` directly or explore `with_names_csv_path()` and `name_relationships()` if you need custom data loading paths. [4, 10]","cause":"The `load_resource()` function was removed in version 1.0.0. [10]","error":"AttributeError: 'NickNamer' object has no attribute 'load_resource'"},{"fix":"Use `nn.canonicals_of('al')` to find canonical forms like 'alexander', or combine results from both `nicknames_of` and `canonicals_of` for a comprehensive check. [4]","cause":"Misunderstanding the non-symmetric nature of nickname relationships. 'Alexander' is a canonical name, 'al' is a nickname for 'Alexander', but 'Alexander' is not a nickname for 'al'. [4]","error":"AssertionError: 'alexander' not in nn.nicknames_of('al')"}]}