mirror of
https://github.com/kennethreitz/tablib.git
synced 2026-06-05 23:10:17 +00:00
Moved format documentation from code to docs (#420)
This commit is contained in:
Claude Paroz
committed by
Hugo van Kemenade
Hugo van Kemenade
parent
f1046cd13e
commit
a9d9671b7f
@@ -0,0 +1,182 @@
|
||||
.. _formats:
|
||||
|
||||
=======
|
||||
Formats
|
||||
=======
|
||||
|
||||
Tablib supports a wide variety of different tabular formats, both for input and
|
||||
output. Moreover, you can :ref:`register your own formats <newformats>`.
|
||||
|
||||
csv
|
||||
===
|
||||
|
||||
When you import CSV data, you can specify if the first line of your data source
|
||||
is headers with the ``headers`` boolean parameter (defaults to ``True``)::
|
||||
|
||||
import tablib
|
||||
|
||||
tablib.import_set(your_data_stream, format='csv', headers=False)
|
||||
|
||||
When exporting with the ``csv`` format, the top row will contain headers, if
|
||||
they have been set. Otherwise, the top row will contain the first row of the
|
||||
dataset.
|
||||
|
||||
.. admonition:: Line endings
|
||||
|
||||
Exporting uses \\r\\n line endings by default so, make sure to include
|
||||
``newline=''`` otherwise you will get a blank line between each row
|
||||
when you open the file in Excel::
|
||||
|
||||
with open('output.csv', 'w', newline='') as f:
|
||||
f.write(dataset.export('csv'))
|
||||
|
||||
If you do not do this, and you export the file on Windows, your
|
||||
CSV file will open in Excel with a blank line between each row.
|
||||
|
||||
dbf
|
||||
===
|
||||
|
||||
Import/export using the dBASE_ format.
|
||||
|
||||
.. admonition:: Binary Warning
|
||||
|
||||
The ``dbf`` format contains binary data, so make sure to write in binary
|
||||
mode::
|
||||
|
||||
with open('output.dbf', 'wb') as f:
|
||||
f.write(dataset.export('dbf')
|
||||
|
||||
.. _dBASE: https://en.wikipedia.org/wiki/DBase
|
||||
|
||||
df (DataFrame)
|
||||
==============
|
||||
|
||||
Import/export using the pandas_ DataFrame format.
|
||||
|
||||
.. _pandas: https://pandas.pydata.org/
|
||||
|
||||
html
|
||||
====
|
||||
|
||||
The ``html`` format is currently export-only. The exports produce an HTML page
|
||||
with the data in a ``<table>``. If headers have been set, they will be used as
|
||||
table headers.
|
||||
|
||||
jira
|
||||
====
|
||||
|
||||
The ``jira`` format is currently export-only. Exports format the dataset
|
||||
according to the Jira table syntax::
|
||||
|
||||
||heading 1||heading 2||heading 3||
|
||||
|col A1|col A2|col A3|
|
||||
|col B1|col B2|col B3|
|
||||
|
||||
json
|
||||
====
|
||||
|
||||
Import/export using the JSON_ format. If headers have been set, a JSON list of
|
||||
objects will be returned. If no headers have been set, a JSON list of lists
|
||||
(rows) will be returned instead.
|
||||
|
||||
Import assumes (for now) that headers exist.
|
||||
|
||||
.. _JSON: http://json.org/
|
||||
|
||||
latex
|
||||
=====
|
||||
|
||||
Import/export using the LaTeX_ format. This format is export-only.
|
||||
If a title has been set, it will be exported as the table caption.
|
||||
|
||||
.. _LaTeX: https://www.latex-project.org/
|
||||
|
||||
ods
|
||||
===
|
||||
|
||||
Export data in OpenDocument Spreadsheet format. The ``ods`` format is currently
|
||||
export-only.
|
||||
|
||||
.. admonition:: Binary Warning
|
||||
|
||||
:class:`Dataset.ods` contains binary data, so make sure to write in binary mode::
|
||||
|
||||
with open('output.ods', 'wb') as f:
|
||||
f.write(data.ods)
|
||||
|
||||
rst
|
||||
===
|
||||
|
||||
Export data as a reStructuredText_ table representation of a dataset. The
|
||||
``rst`` format is export-only.
|
||||
|
||||
Exporting returns a simple table if the text in the first column is never
|
||||
wrapped, otherwise returns a grid table::
|
||||
|
||||
>>> from tablib import Dataset
|
||||
>>> bits = ((0, 0), (1, 0), (0, 1), (1, 1))
|
||||
>>> data = Dataset()
|
||||
>>> data.headers = ['A', 'B', 'A and B']
|
||||
>>> for a, b in bits:
|
||||
... data.append([bool(a), bool(b), bool(a * b)])
|
||||
>>> table = data.export('rst')
|
||||
>>> table.split('\\n') == [
|
||||
... '===== ===== =====',
|
||||
... ' A B A and',
|
||||
... ' B ',
|
||||
... '===== ===== =====',
|
||||
... 'False False False',
|
||||
... 'True False False',
|
||||
... 'False True False',
|
||||
... 'True True True ',
|
||||
... '===== ===== =====',
|
||||
... ]
|
||||
True
|
||||
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
|
||||
tsv
|
||||
===
|
||||
|
||||
A variant of the csv_ format with tabulators as fields separators.
|
||||
|
||||
xls
|
||||
===
|
||||
|
||||
Import/export data in Legacy Excel Spreadsheet representation.
|
||||
|
||||
.. note::
|
||||
|
||||
XLS files are limited to a maximum of 65,000 rows. Use xlsx_ to avoid this
|
||||
limitation.
|
||||
|
||||
.. admonition:: Binary Warning
|
||||
|
||||
The `xls` file format is binary, so make sure to write in binary mode::
|
||||
|
||||
with open('output.xls', 'wb') as f:
|
||||
f.write(data.export('xls'))
|
||||
|
||||
xlsx
|
||||
====
|
||||
|
||||
Import/export data in Excel 07+ Spreadsheet representation.
|
||||
|
||||
.. admonition:: Binary Warning
|
||||
|
||||
The `xlsx` file format is binary, so make sure to write in binary mode::
|
||||
|
||||
with open('output.xlsx', 'wb') as f:
|
||||
f.write(data.export('xlsx'))
|
||||
|
||||
yaml
|
||||
====
|
||||
|
||||
Import/export data in the YAML_ format.
|
||||
When exporting, if headers have been set, a YAML list of objects will be
|
||||
returned. If no headers have been set, a YAML list of lists (rows) will be
|
||||
returned instead.
|
||||
|
||||
Import assumes (for now) that headers exist.
|
||||
|
||||
.. _YAML: https://yaml.org
|
||||
@@ -98,6 +98,11 @@ This part of the documentation, which is mostly prose, begins with some backgrou
|
||||
|
||||
tutorial
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
formats
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
||||
@@ -424,199 +424,6 @@ class Dataset:
|
||||
|
||||
return fmt.export_set(self, **kwargs)
|
||||
|
||||
# -------
|
||||
# Formats
|
||||
# -------
|
||||
|
||||
@property
|
||||
def xls():
|
||||
"""A Legacy Excel Spreadsheet representation of the :class:`Dataset` object, with :ref:`separators`. Cannot be set.
|
||||
|
||||
.. note::
|
||||
|
||||
XLS files are limited to a maximum of 65,000 rows. Use :class:`Dataset.xlsx` to avoid this limitation.
|
||||
|
||||
.. admonition:: Binary Warning
|
||||
|
||||
:class:`Dataset.xls` contains binary data, so make sure to write in binary mode::
|
||||
|
||||
with open('output.xls', 'wb') as f:
|
||||
f.write(data.xls)
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def xlsx():
|
||||
"""An Excel '07+ Spreadsheet representation of the :class:`Dataset` object, with :ref:`separators`. Cannot be set.
|
||||
|
||||
.. admonition:: Binary Warning
|
||||
|
||||
:class:`Dataset.xlsx` contains binary data, so make sure to write in binary mode::
|
||||
|
||||
with open('output.xlsx', 'wb') as f:
|
||||
f.write(data.xlsx)
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def ods():
|
||||
"""An OpenDocument Spreadsheet representation of the :class:`Dataset` object, with :ref:`separators`. Cannot be set.
|
||||
|
||||
.. admonition:: Binary Warning
|
||||
|
||||
:class:`Dataset.ods` contains binary data, so make sure to write in binary mode::
|
||||
|
||||
with open('output.ods', 'wb') as f:
|
||||
f.write(data.ods)
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def csv():
|
||||
"""A CSV representation of the :class:`Dataset` object. The top row will contain
|
||||
headers, if they have been set. Otherwise, the top row will contain
|
||||
the first row of the dataset.
|
||||
|
||||
A dataset object can also be imported by setting the :class:`Dataset.csv` attribute. ::
|
||||
|
||||
data = tablib.Dataset()
|
||||
data.csv = 'age, first_name, last_name\\n90, John, Adams'
|
||||
|
||||
Import assumes (for now) that headers exist.
|
||||
|
||||
.. admonition:: Binary Warning for Python 2
|
||||
|
||||
:class:`Dataset.csv` uses \\r\\n line endings by default so, in Python 2, make
|
||||
sure to write in binary mode::
|
||||
|
||||
with open('output.csv', 'wb') as f:
|
||||
f.write(data.csv)
|
||||
|
||||
If you do not do this, and you export the file on Windows, your
|
||||
CSV file will open in Excel with a blank line between each row.
|
||||
|
||||
.. admonition:: Line endings for Python 3
|
||||
|
||||
:class:`Dataset.csv` uses \\r\\n line endings by default so, in Python 3, make
|
||||
sure to include newline='' otherwise you will get a blank line between each row
|
||||
when you open the file in Excel::
|
||||
|
||||
with open('output.csv', 'w', newline='') as f:
|
||||
f.write(data.csv)
|
||||
|
||||
If you do not do this, and you export the file on Windows, your
|
||||
CSV file will open in Excel with a blank line between each row.
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def tsv():
|
||||
"""A TSV representation of the :class:`Dataset` object. The top row will contain
|
||||
headers, if they have been set. Otherwise, the top row will contain
|
||||
the first row of the dataset.
|
||||
|
||||
A dataset object can also be imported by setting the :class:`Dataset.tsv` attribute. ::
|
||||
|
||||
data = tablib.Dataset()
|
||||
data.tsv = 'age\tfirst_name\tlast_name\\n90\tJohn\tAdams'
|
||||
|
||||
Import assumes (for now) that headers exist.
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def yaml():
|
||||
"""A YAML representation of the :class:`Dataset` object. If headers have been
|
||||
set, a YAML list of objects will be returned. If no headers have
|
||||
been set, a YAML list of lists (rows) will be returned instead.
|
||||
|
||||
A dataset object can also be imported by setting the :class:`Dataset.yaml` attribute: ::
|
||||
|
||||
data = tablib.Dataset()
|
||||
data.yaml = '- {age: 90, first_name: John, last_name: Adams}'
|
||||
|
||||
Import assumes (for now) that headers exist.
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def df():
|
||||
"""A DataFrame representation of the :class:`Dataset` object.
|
||||
|
||||
A dataset object can also be imported by setting the :class:`Dataset.df` attribute: ::
|
||||
|
||||
data = tablib.Dataset()
|
||||
data.df = DataFrame(np.random.randn(6,4))
|
||||
|
||||
Import assumes (for now) that headers exist.
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def json():
|
||||
"""A JSON representation of the :class:`Dataset` object. If headers have been
|
||||
set, a JSON list of objects will be returned. If no headers have
|
||||
been set, a JSON list of lists (rows) will be returned instead.
|
||||
|
||||
A dataset object can also be imported by setting the :class:`Dataset.json` attribute: ::
|
||||
|
||||
data = tablib.Dataset()
|
||||
data.json = '[{"age": 90, "first_name": "John", "last_name": "Adams"}]'
|
||||
|
||||
Import assumes (for now) that headers exist.
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def html():
|
||||
"""A HTML table representation of the :class:`Dataset` object. If
|
||||
headers have been set, they will be used as table headers.
|
||||
|
||||
.. notice:: This method can be used for export only.
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def dbf():
|
||||
"""A dBASE representation of the :class:`Dataset` object.
|
||||
|
||||
A dataset object can also be imported by setting the
|
||||
:class:`Dataset.dbf` attribute. ::
|
||||
|
||||
# To import data from an existing DBF file:
|
||||
data = tablib.Dataset()
|
||||
data.dbf = open('existing_table.dbf', mode='rb').read()
|
||||
|
||||
# to import data from an ASCII-encoded bytestring:
|
||||
data = tablib.Dataset()
|
||||
data.dbf = '<bytestring of tabular data>'
|
||||
|
||||
.. admonition:: Binary Warning
|
||||
|
||||
:class:`Dataset.dbf` contains binary data, so make sure to write in binary mode::
|
||||
|
||||
with open('output.dbf', 'wb') as f:
|
||||
f.write(data.dbf)
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def latex():
|
||||
"""A LaTeX booktabs representation of the :class:`Dataset` object. If a
|
||||
title has been set, it will be exported as the table caption.
|
||||
|
||||
.. note:: This method can be used for export only.
|
||||
"""
|
||||
pass
|
||||
|
||||
@property
|
||||
def jira():
|
||||
"""A Jira table representation of the :class:`Dataset` object.
|
||||
|
||||
.. note:: This method can be used for export only.
|
||||
"""
|
||||
pass
|
||||
|
||||
# ----
|
||||
# Rows
|
||||
# ----
|
||||
|
||||
Reference in New Issue
Block a user