import sys
import requests
__API_ENDPOINT__ = 'https://gender-api.com/get'
__FEMALE__ = 'female'
__MALE__ = 'male'
def _collect_payload_single(name, country_id, language_id, ip, key):
"""Return the query params from the given arguments
Keyword arguments:
- `name` -- The name to lookup
- `country_id` -- Restrict name lookup for a specific country
- `language_id` -- Restrict name lookup for a specific language
- `ip` -- Deduce the locale for the name lookup from the given ip address
- `key` -- The API key for registered accounts
"""
params = {'name': name}
if (country_id != None):
params['country'] = country_id
if (language_id != None):
params['language'] = language_id
if (ip != None):
params['ip'] = ip
if (key != None):
params['key'] = key
return params
def _collect_payload_multi(names, country_id, language_id, ip, key):
"""Return the query params from the given arguments
Keyword arguments:
- `names` -- The list of names to lookup
- `country_id` -- Restrict name lookup for a specific country
- `language_id` -- Restrict name lookup for a specific language
- `ip` -- Deduce the locale for the name lookup from the given ip address
- `key` -- The API key for registered accounts
"""
params = {}
names = reduce(lambda name, consumed_names: consumed_names + ';' + name, names, '')
names = names[:-1] if names[-1] == ';' else names
params['name'] = names
if (country_id != None):
params['country'] = country_id
if (language_id != None):
params['language'] = language_id
if (ip != None):
params['ip'] = ip
if (key != None):
params['key'] = key
return params
[docs]def genderize(name, country_id=None, language_id=None, ip=None, key=None):
"""Query the gender of the given name with the given options
Keyword arguments:
- `name` -- The name to lookup (**mandatory**, *no default*)
- `country_id` -- Restrict name lookup for a specific country (*default:* `None`)
- `language_id` -- Restrict name lookup for a specific language (*default:* `None`)
- `ip` -- Deduce the locale for the name lookup from the given ip address (*default:* `None`)
- `key` -- The API key for registered accounts (*default:* `None`)
"""
r = requests.get(__API_ENDPOINT__, params=_collect_payload_single(name=name, country_id=country_id, language_id=language_id, ip=ip, key=key))
# Raise if the request failed
r.raise_for_status()
return r.json()
[docs]def genderize_all(names, country_id=None, language_id=None, ip=None, key=None):
"""Query the gender of the given names with the given options
Keyword arguments:
- `names` -- The list of names to lookup (**mandatory**, *no default*)
- `country_id` -- Restrict name lookup for a specific country (*default:* `None`)
- `language_id` -- Restrict name lookup for a specific language (*default:* `None`)
- `ip` -- Deduce the locale for the name lookup from the given ip address (*default:* `None`)
- `key` -- The API key for registered accounts (*default:* `None`)
"""
r = requests.get(__API_ENDPOINT__, params=_collect_payload_multi(names=names, country_id=country_id, language_id=language_id, ip=ip, key=key))
# Raise if the request failed
r.raise_for_status()
return r.json()
[docs]def is_female(name, country_id=None, language_id=None, ip=None, key=None):
"""Check if the given name is female
Keyword arguments:
- `name` -- The name to lookup (**mandatory**, *no default*)
- `country_id` -- Restrict name lookup for a specific country (*default:* `None`)
- `language_id` -- Restrict name lookup for a specific language (*default:* `None`)
- `ip` -- Deduce the locale for the name lookup from the given ip address (*default:* `None`)
- `key` -- The API key for registered accounts (*default:* `None`)
"""
r = requests.get(__API_ENDPOINT__, params=_collect_payload_single(name=name, country_id=country_id, language_id=language_id, ip=ip, key=key))
# Raise if the request failed
r.raise_for_status()
return r.json().get('gender', 'white rabbit') == __FEMALE__
[docs]def is_male(name, country_id=None, language_id=None, ip=None, key=None):
"""Check if the given name is male
Keyword arguments:
- `name` -- The name to lookup (**mandatory**, *no default*)
- `country_id` -- Restrict name lookup for a specific country (*default:* `None`)
- `language_id` -- Restrict name lookup for a specific language (*default:* `None`)
- `ip` -- Deduce the locale for the name lookup from the given ip address (*default:* `None`)
- `key` -- The API key for registered accounts (*default:* `None`)
"""
r = requests.get(__API_ENDPOINT__, params=_collect_payload_single(name=name, country_id=country_id, language_id=language_id, ip=ip, key=key))
# Raise if the request failed
r.raise_for_status()
return r.json().get('gender', 'go ask alice') == __MALE__
[docs]def third_person_personal_pronoun(name, country_id=None, language_id=None, ip=None, key=None):
"""Return the third person singular personal pronoun ('he', 'she' or 'it'; see http://en.wikipedia.org/wiki/Personal_pronoun for more) for the given name
Keyword arguments:
- `name` -- The name to lookup (**mandatory**, *no default*)
- `country_id` -- Restrict name lookup for a specific country (*default:* `None`)
- `language_id` -- Restrict name lookup for a specific language (*default:* `None`)
- `ip` -- Deduce the locale for the name lookup from the given ip address (*default:* `None`)
- `key` -- The API key for registered accounts (*default:* `None`)
"""
return 'he' if is_male(name=name, country_id=country_id, language_id=language_id, ip=ip, key=key) else 'she'
[docs]def possessive_determiner(name, country_id=None, language_id=None, ip=None, key=None):
"""Return the possessive determiner ('his' or 'her'; see http://en.wikipedia.org/wiki/Possessive_determiner for more) for the given name
Keyword arguments:
- `name` -- The name to lookup (**mandatory**, *no default*)
- `country_id` -- Restrict name lookup for a specific country (*default:* `None`)
- `language_id` -- Restrict name lookup for a specific language (*default:* `None`)
- `ip` -- Deduce the locale for the name lookup from the given ip address (*default:* `None`)
- `key` -- The API key for registered accounts (*default:* `None`)
"""
return 'his' if is_male(name=name, country_id=country_id, language_id=language_id, ip=ip, key=key) else 'her'
[docs]def female_probability(name, country_id=None, language_id=None, ip=None, return_sample_size=False, key=None):
"""Return the probability of the given name being female
Keyword arguments:
- `name` -- The name to lookup (**mandatory**, *no default*)
- `country_id` -- Restrict name lookup for a specific country (*default:* `None`)
- `language_id` -- Restrict name lookup for a specific language (*default:* `None`)
- `ip` -- Deduce the locale for the name lookup from the given ip address (*default:* `None`)
- `return_sample_size` -- If true, the return value is a tuple consisting of `(female_probability, sample_size)` (*default:* `False`)
- `key` -- The API key for registered accounts (*default:* `None`)
"""
r = requests.get(__API_ENDPOINT__, params=_collect_payload_single(name=name, country_id=country_id, language_id=language_id, ip=ip, key=key))
# Raise if the request failed
r.raise_for_status()
p = float(r.json().get('accuracy', -1.0)) / 100.
p = p if (r.json().get('gender') == __FEMALE__) else 1 - p
return (p, r.json().get('samples', -1)) if return_sample_size else p
[docs]def male_probability(name, country_id=None, language_id=None, ip=None, return_sample_size=False, key=None):
"""Return the probability of the given name being male
Keyword arguments:
- `name` -- The name to lookup (**mandatory**, *no default*)
- `country_id` -- Restrict name lookup for a specific country (*default:* `None`)
- `language_id` -- Restrict name lookup for a specific language (*default:* `None`)
- `ip` -- Deduce the locale for the name lookup from the given ip address (*default:* `None`)
- `return_sample_size` -- If true, the return value is a tuple consisting of `(male_probability, sample_size)` (*default:* `False`)
- `key` -- The API key for registered accounts (*default:* `None`)
"""
r = requests.get(__API_ENDPOINT__, params=_collect_payload_single(name=name, country_id=country_id, language_id=language_id, ip=ip, key=key))
# Raise if the request failed
r.raise_for_status()
p = float(r.json().get('accuracy', -1.0)) / 100.
p = p if (r.json().get('gender') == __MALE__) else 1 - p
return (p, r.json().get('samples', -1)) if return_sample_size else p
if (__name__ == '__main__'):
if (len(sys.argv) > 2):
names = sys.argv[1:]
print genderize_all(names=names)
else:
n = sys.argv[1] if len(sys.argv) > 1 else 'julia'
print genderize(name=n)