Add class for highlighting, replacing and extracting placeholders

[quis]

Notes for reviewing

Reviewing will be easier on a commit-by-commit basis

I would particularly like to know:

• if there are any test cases I might have missed

Usage

Given a template object, the Template class can:

• highlight the placeholders (by adding HTML)
• replace the placeholders with data
• extract the names of the placeholders

It will also pass through, if passed the name and id of the template, and the user’s data, eg:

  template = Template(
    {"id": "1234", "name": "Hello world", "content": "Hello ((name))"},
    {"name": "chris"}
  )
  template.id
  >>> "1234"
  template.name
  >>> "Hello world"
  template.content
  >>> "Hello ((name))"
  template.values
  >>> {"name": "chris"}

If you only have the template

  template = Template({"content": "Hello ((name))"})

Highlight the placeholders:

  template.formatted
  >>> "Hello <span class='placeholder'>name</span>"
  template.formatted_as_markup
  >>> Markup(u"Hello <span class='placeholder'>name</span>")

List the placeholders in the template

  template.placeholders
  >>> ['name']
  template.placeholders_as_markup
  >>> [Markup(u"<span class='placeholder'>name</span>")]

If you have the template and the user’s data

You can do all of the above, plus

Replace the placeholders with the user’s data

  template = Template({"content": "Hello ((name))"}, {"name": "Chris"})
  template.replaced
  >>> 'Hello Chris'

Find out what data is missing for a given template

  template = Template({"content": "Hello ((name))}", {"foo": "bar"})
  template.missing_data
  >>> {'name'}

Find out what additional data is being passed that the template isn’t expecting

  template = Template({"content": "Hello ((name))"}, {"foo": "bar"})
  template.additional_data
  >>> {'foo'}

If you try to replace placeholders with bad data

…then you’ll get a NeededByTemplateError or a NoPlaceholderForDataError, eg

  template = Template({"content": "Hello ((name))"}, {"foo": "bar"})
  >>> NeededByTemplateError: name

[mannickutd]

These don't need to be enclosed in sets?
Look at pythons set operators :)
https://docs.python.org/3.5/library/stdtypes.html?highlight=set#set

[quis]

@mannickutd You’re right, don’t need the wrapping sets, I’ve squashed the changes into c890df1.

Other changes I’ve made since:

Rename from Placeholders to Template

In trying to use this class I found it clumsy, because it accepted one attribute of a template object (content) but not the others (name, id).

This commit changes the class to accept an entire template object (with name and id still optional). All attributes of the template are passed through, and the additional properties available (eg template.replaced`) stay the same, although in some cases are renamed for clarity.

This commit also updates the documentation to match.

Add option to drop values from the user’s data before parsing template

A user’s uploaded data may well have fields which aren’t in the template, for example phone number wouldn’t be in the template, but would need to be in the CSV. You wouldn’t want to raise an error when giving the template this data.

This commit adds an option, when instantiating the Template object, to drop values from the user’s data before attempting to do any replacing of the template.