Python Client for Handwriting.io API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
handwritingio
test
.dockerignore
.gitignore
CONTRIBUTING.rst
Dockerfile
LICENSE
MANIFEST.in
Makefile
README.rst
circle.yml
setup.cfg
setup.py
tox.ini

README.rst

Handwriting.io Python Client

Installation

$ pip install handwritingio

Basic Example

Before getting started, you'll need to register for a free account at Handwriting.io. You'll then be able to create access tokens, including free test tokens.

While you're there, browse through the handwriting catalog, play with the live demo, and read the documentation.

Back in Python, create a handwritten message:

import handwritingio

# Set up the client with your access token:
hwio = handwritingio.Client('KEY', 'SECRET')

# Render an image:
png = hwio.render_png({
  'text': 'Handwriting with Python!',
  # Found in the catalog (https://handwriting.io/handwriting-catalog/2D5S46A80003/)
  # or by listing handwritings:
  'handwriting_id': '2D5S46A80003',
  # See https://handwriting.io/docs/#dimensions:
  'height': 'auto',
})

# Write the image to a file:
with open('handwriting.png', 'wb') as f:
  f.write(png)

If all goes well, this should create an image similar to the following:

https://d2igm8ue20pook.cloudfront.net/python-client/handwriting.png

Advanced Examples

List all handwritings, paging through the results as necessary:

import handwritingio

hwio = handwritingio.Client('KEY', 'SECRET')
all_handwritings = [] # we'll add all of the results to this list
limit = 100 # number of handwritings to get per page
offset = 0 # starting index
while True:
  page_of_handwritings = hwio.list_handwritings({
    'limit': limit,
    'offset': offset,
  })
  if not page_of_handwritings:
    # We've exhausted the listing, so we're done
    break
  all_handwritings.extend(page_of_handwritings)
  offset += limit
# all_handwritings now contains every handwriting available

If you don't need all of the (currently 200+) handwritings for your application, you could simply fetch the five "most cursive" handwritings, for example:

import handwritingio

hwio = handwritingio.Client('KEY', 'SECRET')
handwritings = hwio.list_handwritings({
  'order_by': 'rating_cursivity',
  'order_dir': 'desc',
  'limit': 5,
})

Render a PNG and manipulate it with PIL:

from cStringIO import StringIO

import handwritingio
from PIL import Image

hwio = handwritingio.Client('KEY', 'SECRET')
png = hwio.render_png({
  'text': 'Handwriting with Python!',
  # Found in the catalog (https://handwriting.io/handwriting-catalog/2D5S46A80003/)
  # or by listing handwritings:
  'handwriting_id': '2D5S46A80003',
  # See https://handwriting.io/docs/#dimensions:
  'height': 'auto',
})
# Image expects a file-like object, so wrap the image in StringIO:
im = Image.open(StringIO(png))
# Rotate the image by 180 degrees:
im = im.rotate(180, expand=True)
# Save it to a file:
im.save('handwriting_upside_down.png')

Which should create the file:

https://d2igm8ue20pook.cloudfront.net/python-client/handwriting_upside_down.png

Render a PDF, with a CMYK color for the text:

import handwritingio

hwio = handwritingio.Client('KEY', 'SECRET')
pdf = hwio.render_pdf({
  'text': 'Handwriting with Python!',
  # Found in the catalog (https://handwriting.io/handwriting-catalog/2D5S46A80003/)
  # or by listing handwritings:
  'handwriting_id': '2D5S46A80003',
  # See https://handwriting.io/docs/#dimensions:
  'height': 'auto',
  # See https://handwriting.io/docs/#handwriting-color:
  'handwriting_color': '(1, 0.5, 0, 0.2)',
})
with open('handwriting.pdf', 'wb') as f:
  f.write(pdf)

If something goes wrong with a request, an exception will be raised:

import handwritingio

hwio = handwritingio.Client('KEY', 'SECRET')
pdf = hwio.render_pdf({
  'text': 'Handwriting with Python!',
  # Found in the catalog (https://handwriting.io/handwriting-catalog/2D5S46A80003/)
  # or by listing handwritings:
  'handwriting_id': '2D5S46A80003',
  # See https://handwriting.io/docs/#dimensions:
  'height': 'auto',
  'handwriting_color': 'cheesecake',
  'width': 'double wide',
})
Traceback (most recent call last):
  File "tester.py", line 9, in <module>
    'width': 'double wide',
  File "build/bdist.linux-x86_64/egg/handwritingio/__init__.py", line 145, in render_pdf
  File "build/bdist.linux-x86_64/egg/handwritingio/__init__.py", line 109, in _hit
handwritingio.ValidationError: field: width, width unable to parse: "double wide"

But, there's more than one thing wrong with that request. We can see all of the errors by catching the exception and inspecting the errors attribute:

import handwritingio

hwio = handwritingio.Client('KEY', 'SECRET')
try:
  pdf = hwio.render_pdf({
    'text': 'Handwriting with Python!',
    # Found in the catalog (https://handwriting.io/handwriting-catalog/2D5S46A80003/)
    # or by listing handwritings:
    'handwriting_id': '2D5S46A80003',
    # See https://handwriting.io/docs/#dimensions:
    'height': 'auto',
    'handwriting_color': 'cheesecake',
    'width': 'double wide',
  })
except handwritingio.ValidationError as e:
  print e.errors
[{u'field': u'width', u'error': u'width unable to parse: "double wide"'},
 {u'field': u'handwriting_color', u'error': u'handwriting_color must be valid CMYK'}]

Reference

See the API Documentation for details on all endpoints and parameters. For the most part, the Client passes the parameters through to the API directly.

The endpoints map to client methods as follows:

Version Numbers

Version numbers for this package work slightly differently than standard semantic versioning. For this package, the major version number will match the Handwriting.io API version number, and the minor version will be incremented for any breaking changes to this package. The patch version will be incremented for bug fixes and changes that add functionality only.

For this reason, we recommend that you pin this dependency to the minor version, for example, in your requirements.txt or setup.py, use:

handwritingio>=1.0,<1.1

uWSGI Compatibility

If your application uses uWSGI in "preforking" mode, beware of issues with sharing a global handwritingio.Client across forked processes. To avoid problems, make sure that each worker process instantiates its own handwritingio.Client instance. One way to do this is to run a postfork hook, which can be done by including code similar to this:

import handwritingio
import uwsgidecorators

client = handwritingio.Client(API_KEY, API_SECRET)

@uwsgidecorators.postfork
def refresh_client():
  global client
  client = handwritingio.Client(API_KEY, API_SECRET)

Issues

Please open an issue on Github or contact us directly for help with any problems you find.