Tabular files for humans or an opinionated approach to tabular files or...
This repository has been archived on 2023-02-21. You can view files and clone it, but cannot push or open issues or pull requests.
Go to file
Agate 4c75ff6b6a Prepare Jenkinsfile for Gitea migration (#74572) 2023-02-20 15:17:33 +01:00
debian first commit 2020-07-17 12:20:37 +02:00
tabularfile first commit 2020-07-17 12:20:37 +02:00
tests first commit 2020-07-17 12:20:37 +02:00
Jenkinsfile Prepare Jenkinsfile for Gitea migration (#74572) 2023-02-20 15:17:33 +01:00
MANIFEST.in first commit 2020-07-17 12:20:37 +02:00
README first commit 2020-07-17 12:20:37 +02:00
sample.py first commit 2020-07-17 12:20:37 +02:00
setup.py first commit 2020-07-17 12:20:37 +02:00
tox.ini first commit 2020-07-17 12:20:37 +02:00

README

tabularfile
============

Tabular files for humans or an opinionated approach to tabular files or
whatever. Parse and write ODS files, mimicing the `csv` module interface,
keeping memory usage as low as possible.

Reading
-------

The main API is `tabularfile.load(path_or_file, **kwarsg)` it's a context manager returning an
iterable. It accepts as first argument a bytes string, a path or an opened
file. Other arguments depends on the backend, ods or csv.

.. code:: pycon

    >>> from tabularfile import load
    >>> with load('sheet.ods') as tabfile:
        list(tabfile)
    [
        ['date', 'count'],
        ['01/12/2019', '123'],
        ['01/01/2020', '156'],
    ]
    >>> with load('sheet.csv') as tabfile:
        list(tabfile)
    [
        ['date', 'count'],
        ['01/12/2019', '123'],
        ['01/01/2020', '156'],
    ]


With `typed=True` you can ask the reader to cast cells content based on the declared OpenDocument value type.


.. code:: pycon

    >>> with load('sheet.ods'), typed=True) as tabfile:
            list(tabfile)
    [
        ['date', 'count']
        [datetime.date(2019, 12, 1), 123],
        [datetime.date(2029, 1, 1), 156],
    ]


With the `sheet` constructor attribute you can load another sheet than the
first one, only integer indexes are supported, it also supports sheet's name.
To get the list of tsheets you can use the `tabfile.sheets` accessor.


.. code:: pycon

    >>> with load('sheet.ods', sheet=1) as tabfile:
    ...
    >>> with load('sheet.ods', sheet='Sheet1') as tabfile:
            tabfile.sheets
    ['Sheet1', 'Sheet2']

Writing
-------

To write a sheet file, use the `tabularfile.write(path_or_file, format='ods',
**kwargs)` context manager. `format` can also be `csv` and in this case it
accepts other arguments like `encoding`, `dialect`, `delimiter` or `quotechar`.

The ODS writer accept special value `tabularfile.ods.LinkedValue` if you need
to put XLink on your data. ODS and CSV writer accets date and datetime values
which will be formatted using the `date_format` and `datetime_format`
templates.


.. code:: pycon

    >>> from tabularfile import ods
    >>> with ods.writer('sheet.ods') as writer:
        writer.writerow(['date', 'count', 'link'])
        writer.writerows([
            [datetime.date(2019, 12, 1), 123, ods.LinkedValue('Click me', href='https://example.com/')],
            [datetime.date(2020, 1, 1), 156, ods.LinkedValue('Click me', href='https://example.com/')],
        ])

Parsing ISO8601 dates
---------------------

Base python before version 3.7 is not able to parse date with timezone, so we
try as much as possible to use other library to do it. `isodate` or
`python-dateutil` are used if present.

Detecting CSV character encoding
--------------------------------

If the charamel_ package is installed, it is used for detecting the encoding of CSV files.


.. _charamel: https://pypi.org/project/charamel/