Genderize

Client for the Genderize.io web service.

Basic usage

Import the Genderize class and call its get method with a list of names.

from genderize import Genderize
print(Genderize().get(['James', 'Eva', 'Thunderhorse']))

[{u'count': 1037, u'gender': u'male', u'name': u'James', u'probability': 0.99},
 {u'count': 234, u'gender': u'female', u'name': u'Eva', u'probability': 1.0},
 {u'gender': None, u'name': u'Thunderhorse'}]

Shell usage

If run as a script, takes a list of names on stdin, and prints them with their genders.

echo "James\nEva\nThunderhorse" | python -m genderize

James: male
Eva: female
Thunderhorse: None

Advanced usage

Create a Genderize instance with a custom user agent, an API key, and a shorter timeout than the default 30 seconds. Note that you’ll need to use your own API key or this example won’t work.

from genderize import Genderize
genderize = Genderize(
    user_agent='GenderizeDocs/0.0',
    api_key='example_api_key',
    timeout=5.0)
print(genderize.get(['James', 'Eva', 'Thunderhorse']))

[{u'count': 1037, u'gender': u'male', u'name': u'James', u'probability': 0.99},
 {u'count': 234, u'gender': u'female', u'name': u'Eva', u'probability': 1.0},
 {u'gender': None, u'name': u'Thunderhorse'}]

Maintenance

Setup for local development:

virtualenv --prompt '(genderize) ' venv -p python3
pip install -r requirements.txt
pip install -r requirements-dev.txt

Release checklist:

1. Generate a new version number: major.minor.micro. It should be compatible with both PEP 440 and SemVer 2.0.0.
2. Update __version__ in genderize/__init__.py. This is read by setup.py and doesn’t need to be changed there.
3. Add a changelog entry and date for the new version in CHANGES.rst.
4. Commit the changes. This may be done as part of another change.
5. Tag the commit with git tag major.minor.micro.
6. Push the tag to GitHub with git push origin major.minor.micro.
7. Travis will create a new PyPI release from the tag.

API docs

genderize package

Module contents

Client for Genderize.io web service.

class genderize.Genderize(user_agent=None, api_key=None, timeout=30.0)

Bases: object

Client for Genderize.io web service. Uses a Requests session for persistent HTTP connections.

BATCH_SIZE = 10

get(names, country_id=None, language_id=None, retheader=False)

Look up gender for a list of names. Can optionally refine search with locale info. May make multiple requests if there are more names than can be retrieved in one call.

Parameters:

• names (Iterable[str]) – List of names.
• country_id (Optional[str]) – Optional ISO 3166-1 alpha-2 country code.
• language_id (Optional[str]) – Optional ISO 639-1 language code.
• retheader (Optional[boolean]) – Optional

Returns:

If retheader is False:

List of dicts containing ‘name’, ‘gender’,

‘probability’, ‘count’ keys. If ‘gender’ is None, ‘probability’ and ‘count’ will be omitted.

else:

A dict containing ‘data’ and ‘headers’ keys. Data is the same as when retheader is False. Headers are the response header (a requests.structures.CaseInsensitiveDict). If multiple requests were made, the header will be from the last one.

Return type:Union[dict, Sequence[dict]] Raises:GenderizeException – if API server returns HTTP error code.

get1(name, **kwargs)

Look up gender for a single name. See get(). Doesn’t support retheader option.

exception genderize.GenderizeException

Bases: exceptions.Exception

Exception from Genderize.io web service.

Change Log

0.3.1

2018-12-24

• Added missing setup.py classifier for Python 3.7.

0.3.0

2018-12-21

• Added support for Requests connection/read timeouts, with a default of 30 seconds.
• Now tested on Python 3.7.
• Added fix to .travis.yml for broken PyPI publishing. See travis-ci/dpl #861 and Releasing build artifacts.

0.2.0

2018-05-15

• Now respects the API limit of 10 names per request, and will break up larger name lists into multiple API requests transparently. This closes issue #6, reported by neginahoomi.
• Now tested on Python 3.6, PyPy 2, and PyPy 3 as well, and generates Codecov coverage reports.
• Dropped support for Python 2.6 and 3.2.
• Updated author’s contact info.

0.1.5

2015-10-09

• Incorporated vionemc’s patch for optionally returning response headers. Anyone that wants to inspect the rate limit headers should set retheader=True.
• Now tested on Python 3.5 as well.

0.1.4

2015-06-21

• Switched to HTTPS endpoint.
• Incorporated granteagon’s patch for _fixtypes.
• Added support for paid API keys.
• Included Sphinx API docs.

0.1.3

2015-01-16

• Supports Python 2.6, 2.7, 3.2, 3.3, and 3.4.
• Added an integration test that calls the Genderize.io API server.
• Now using Travis CI.

0.1.2

2014-11-26

• Python 3 support.

0.1.1

2014-06-20

• Incorporated oychang’s patch for handling non-JSON error responses.

0.1.0

2014-03-15

• Initial release.

Indices and tables

• Index
• Module Index
• Search Page