CSV source section
==================

A CSV source pipeline section lets you create pipeline items from CSV files.
The CSV source section blueprint name is
``collective.transmogrifier.sections.csvsource``.

A CSV source section will load the CSV file named in the ``filename`` option,
and will yield an item for each line in the CSV file. It'll use the first line
of the CSV file to determine what keys to use, or you can specify a
``fieldnames`` option to specify the key names.

The ``filename`` option may be an absolute path, or a package reference, e.g.
``my.package:foo/bar.csv``.

By default the CSV file is assumed to use the Excel CSV dialect, but you can
specify any dialect supported by the python csv module if you specify it with
the ``dialect`` option.

    >>> import tempfile
    >>> tmp = tempfile.NamedTemporaryFile('w+', suffix='.csv')
    >>> tmp.write('\r\n'.join("""\
    ... foo,bar,baz
    ... first-foo,first-bar,first-baz
    ... second-foo,second-bar,second-baz
    ... """.splitlines()))
    >>> tmp.flush()
    >>> csvsource = """
    ... [transmogrifier]
    ... pipeline =
    ...     csvsource
    ...     printer
    ...     
    ... [csvsource]
    ... blueprint = collective.transmogrifier.sections.csvsource
    ... filename = %s
    ... 
    ... [printer]
    ... blueprint = collective.transmogrifier.sections.tests.pprinter
    ... """ % tmp.name
    >>> registerConfig(u'collective.transmogrifier.sections.tests.csvsource.file',
    ...                csvsource)
    >>> transmogrifier(u'collective.transmogrifier.sections.tests.csvsource.file')
    [('bar', 'first-bar'), ('baz', 'first-baz'), ('foo', 'first-foo')]
    [('bar', 'second-bar'), ('baz', 'second-baz'), ('foo', 'second-foo')]

    >>> transmogrifier(u'collective.transmogrifier.sections.tests.csvsource.file',
    ...                csvsource=dict(fieldnames='monty spam eggs'))
    [('eggs', 'baz'), ('monty', 'foo'), ('spam', 'bar')]
    [('eggs', 'first-baz'), ('monty', 'first-foo'), ('spam', 'first-bar')]
    [('eggs', 'second-baz'), ('monty', 'second-foo'), ('spam', 'second-bar')]

Here is the same example, loading a file from a package instead:

    >>> csvsource = """
    ... [transmogrifier]
    ... pipeline =
    ...     csvsource
    ...     printer
    ...     
    ... [csvsource]
    ... blueprint = collective.transmogrifier.sections.csvsource
    ... filename = collective.transmogrifier.tests:sample.csv
    ... 
    ... [printer]
    ... blueprint = collective.transmogrifier.sections.tests.pprinter
    ... """
    >>> registerConfig(u'collective.transmogrifier.sections.tests.csvsource.package',
    ...                csvsource)
    >>> transmogrifier(u'collective.transmogrifier.sections.tests.csvsource.package')
    [('bar', 'first-bar'), ('baz', 'first-baz'), ('foo', 'first-foo')]
    [('bar', 'second-bar'), ('baz', 'second-baz'), ('foo', 'second-foo')]

    >>> transmogrifier(u'collective.transmogrifier.sections.tests.csvsource.package',
    ...                csvsource=dict(fieldnames='monty spam eggs'))
    [('eggs', 'baz'), ('monty', 'foo'), ('spam', 'bar')]
    [('eggs', 'first-baz'), ('monty', 'first-foo'), ('spam', 'first-bar')]
    [('eggs', 'second-baz'), ('monty', 'second-foo'), ('spam', 'second-bar')]
