ttr.xml.csv2xml 0.1.2dev002
module, providing conversion of csv file into xml
License: BSD
Keywords: xml csv module

====================
ttr.xml.csv2xml
====================
:Author: Jan Vlcinsky
:e-mail: jan.vlcinsky@gmail.com
:license: BSD

ttr.xml.csv2xml module contains:

	class Csv2Xml
		Converter of CSV lines into xml elements or string
	function string2xml
		utility function to convert string into xml string in one shot.

Features:

- read CSV into XML document
- get headers from CSV and use them as element names
- managing CSV format

	- define CSV format as would csv module
		- using Dialect (subclass, registered one)
		- using fmtparams
		- combination (fmtparam override Dialect)

- on resulting xml define:

	- name of root tag
	- name of row element
	- optional use and name of attribute in row element, showing line number

- iterator over csv / xml rows

- simple function string2xml including encoding

Installation
============
Python must be installed, version 2.6 is expected.
You shall have access to Internet to installa additional packages automatically from PyPi_ (lxml at this moment)
This package is not on PyPi_ yet (planned).
Use of distribution package itself is needed at the moment and andy of following tools shall work

Using setup.py: unpack the package and run::
  python setup.py install
  
Using easy_install::
  easy_install <package_file>
  
Using pip::
  pip install <package_file>

On windows, using binary setup.exe::
  simply run the installation program.


CSV string into XML string
==========================

Simple case could be:
	>>> from ttr.xml.csv2xml import string2xml
	>>> csv_str = """a;b;c
	... 1;2;3
	... 11;22;33
	... 111;222;333"""
	>>> print string2xml(csv_str, delimiter = ";")
	<root><row><a>1</a><b>2</b><c>3</c></row><row><a>11</a><b>22</b><c>33</c></row><row><a>111</a><b>222</b><c>333</c></row></root>

If you like to specify output encoding (default is UTF-8), tell it by encoding parameter
	>>> print string2xml(csv_str, delimiter = ";", encoding = "windows-1250")
	<?xml version='1.0' encoding='windows-1250'?>
	<root><row><a>1</a><b>2</b><c>3</c></row><row><a>11</a><b>22</b><c>33</c></row><row><a>111</a><b>222</b><c>333</c></row></root>

The CSV format can be set also by registered dialects, adding also line numbering attribute
	>>> excel_str = """a,b,c
	... 1,2,3
	... 11,22,33
	... 111,222,333"""
	>>> print string2xml(excel_str, dialect = "excel", row_num_att = "rownum")
	<root><row rownum="1"><a>1</a><b>2</b><c>3</c></row><row rownum="2"><a>11</a><b>22</b><c>33</c></row><row rownum="3"><a>111</a><b>222</b><c>333</c></row></root>

Or you can define your own dialect using csv.Dialect subclass
	>>> import csv
	>>> class DialectSemicolon(csv.Dialect):
	...  delimiter = ';'
	...  quotechar = '"'
	...  doublequote = True
	...  skipinitialspace = False
	...  lineterminator = '\r\n'
	...  quoting = csv.QUOTE_NONE
	...	
	>>> print string2xml(csv_str, dialect = DialectSemicolon)
	<root><row><a>1</a><b>2</b><c>3</c></row><row><a>11</a><b>22</b><c>33</c></row><row><a>111</a><b>222</b><c>333</c></row></root>

File object into XML string
===========================
Csv2Xml provides only one type of source - file like object.
It can be created by opening a file in style: f = open("my.csv", "b")
or by using string buffers:

	>>> from StringIO import StringIO
	>>> buff = StringIO(csv_str)
	>>> print buff # doctest:+ELLIPSIS
	<StringIO.StringIO ...>
	>>> from ttr.xml.csv2xml import Csv2Xml
	>>> csv_convertor = Csv2Xml(buff, delimiter = ";") # doctest:+ELLIPSIS
	>>> print csv_convertor.as_string()
	<root><row><a>1</a><b>2</b><c>3</c></row><row><a>11</a><b>22</b><c>33</c></row><row><a>111</a><b>222</b><c>333</c></row></root>

This way you can easily manage conversion of files without any need to read them in advance into a string.
You can specify CSV file format using the same methods as with string2xml function.

	>>> buff2 = StringIO(excel_str) 
	>>> csv_convertor = Csv2Xml(buff2, dialect = "excel")
	>>> print  csv_convertor.as_string()
	<root><row><a>1</a><b>2</b><c>3</c></row><row><a>11</a><b>22</b><c>33</c></row><row><a>111</a><b>222</b><c>333</c></row></root>

Reading CSV into XML elements
=============================
Instead of using string for storing resulting XML, more nataral is to get is as XML element
You then get root element with all the row - related elements being nested inside
The only difference is you call as_element method now:

	>>> buff2 = StringIO(excel_str) # doctest: +ELLIPSIS
	>>> csv_convertor = Csv2Xml(buff2, dialect = "excel")
	>>> xml_elm = csv_convertor.as_element()
	>>> print xml_elm # doctest: +ELLIPSIS
	<Element root ...>
	>>> from lxml import etree
	>>> etree.tostring(xml_elm)
	'<root><row><a>1</a><b>2</b><c>3</c></row><row><a>11</a><b>22</b><c>33</c></row><row><a>111</a><b>222</b><c>333</c></row></root>'

Iterating over CSV file lines
=============================
Csv2Xml converter can function also as an iterator - in such a case it will not return root element, but only the row elements.

	>>> buff = StringIO(excel_str)
	>>> csv_converter = Csv2Xml(buff, dialect = "excel")
	>>> for xml_row in csv_converter:
	...    print etree.tostring(xml_row)
	<row><a>1</a><b>2</b><c>3</c></row>
	<row><a>11</a><b>22</b><c>33</c></row>
	<row><a>111</a><b>222</b><c>333</c></row>
  
.. _PyPi: http://pypi.python.org/pypi


.. This is your project NEWS file which will contain the release notes.
.. Example: http://www.python.org/download/releases/2.6/NEWS.txt
.. The content of this file, along with README.rst, will appear in your
.. project's PyPI page.

News
====

0.1.2dev
---

*Release date: 2011-08-12*

* Initial version
* removed dependency on lxml, using Python ElementTree