<commit_before>.. doctest_skip

.. _table_io:

Unified file read/write interface
===================================

Astropy provides a unified interface for reading and writing data in different formats.
For many common cases this will simplify the process of file I/O and reduce the need to
master the separate details of all the I/O packages within Astropy.  This functionality is
still in active development and the number of supported formats will be increasing.  For
details on the implementation see :ref:`io_registry`.

Getting started with Table I/O
------------------------------

The :class:`~astropy.table.table.Table` class includes two methods,
:meth:`~astropy.table.table.Table.read` and
:meth:`~astropy.table.table.Table.write`, that make it possible to read from
and write to files. A number of formats are automatically supported (see
`Built-in table readers/writers`_) and new file formats and extensions can be
registered with the :class:`~astropy.table.table.Table` class (see
:ref:`io_registry`).

To use this interface, first import the :class:`~astropy.table.table.Table` class, then
simply call the :class:`~astropy.table.table.Table`
:meth:`~astropy.table.table.Table.read` method with the name of the file and
the file format, for instance ``'ascii.daophot'``::

    >>> from astropy.table import Table
    >>> t = Table.read('photometry.dat', format='ascii.daophot')

For certain file formats, the format can be automatically detected, for
example from the filename extension::

    >>> t = Table.read('table.tex')

Similarly, for writing, the format can be explicitly specified::

    >>> t.write(filename, format='latex')

As for the :meth:`~astropy.table.table.Table.read` method, the format may
be automatically identified in some cases.

Any additional arguments specified will depend on the format.  For examples of this see the
section `Built-in table readers/writers`_.  This section also provides the full list of
choices for the ``format`` argument.

.. _built_in_readers_writers:

Built-in table readers/writers
------------------------------

.. _table_io_ascii:

ASCII formats
^^^^^^^^^^^^^^

The :meth:`~astropy.table.table.Table.read` and
:meth:`~astropy.table.table.Table.write` methods can be used to read and write formats
supported by `astropy.io.ascii`.

Use ``format='ascii'`` in order to interface to the generic
:func:`~astropy.io.ascii.ui.read` and :func:`~astropy.io.ascii.ui.write`
functions from `astropy.io.ascii`.  When reading a table this means
that all supported ASCII table formats will be tried in order to successfully<commit_msg>Add formats table to unified I/O docs<commit_after>.. doctest_skip

.. _table_io:

Unified file read/write interface
===================================

Astropy provides a unified interface for reading and writing data in different formats.
For many common cases this will simplify the process of file I/O and reduce the need to
master the separate details of all the I/O packages within Astropy.  This functionality is
still in active development and the number of supported formats will be increasing.  For
details on the implementation see :ref:`io_registry`.

Getting started with Table I/O
------------------------------

The :class:`~astropy.table.table.Table` class includes two methods,
:meth:`~astropy.table.table.Table.read` and
:meth:`~astropy.table.table.Table.write`, that make it possible to read from
and write to files. A number of formats are automatically supported (see
`Built-in table readers/writers`_) and new file formats and extensions can be
registered with the :class:`~astropy.table.table.Table` class (see
:ref:`io_registry`).

To use this interface, first import the :class:`~astropy.table.table.Table` class, then
simply call the :class:`~astropy.table.table.Table`
:meth:`~astropy.table.table.Table.read` method with the name of the file and
the file format, for instance ``'ascii.daophot'``::

    >>> from astropy.table import Table
    >>> t = Table.read('photometry.dat', format='ascii.daophot')

For certain file formats, the format can be automatically detected, for
example from the filename extension::

    >>> t = Table.read('table.tex')

Similarly, for writing, the format can be explicitly specified::

    >>> t.write(filename, format='latex')

As for the :meth:`~astropy.table.table.Table.read` method, the format may
be automatically identified in some cases.

Any additional arguments specified will depend on the format.  For examples of this see the
section `Built-in table readers/writers`_.  This section also provides the full list of
choices for the ``format`` argument.

.. _built_in_readers_writers:

Built-in table readers/writers
------------------------------

The full list of built-in readers and writers is shown in the table below:

=========================== ==== ===== ============= ==========
           Format           Read Write Auto-identify Deprecated
=========================== ==== ===== ============= ==========
                     aastex  Yes   Yes            No        Yes
                      ascii  Yes   Yes            No
               ascii.aastex  Yes   Yes            No
                ascii.basic  Yes   Yes            No
                  ascii.cds  Yes    No            No
     ascii.commented_header  Yes   Yes            No
              ascii.daophot  Yes    No            No
          ascii.fixed_width  Yes   Yes            No
ascii.fixed_width_no_header  Yes   Yes            No
 ascii.fixed_width_two_line  Yes   Yes            No
                 ascii.ipac  Yes   Yes            No
                ascii.latex  Yes   Yes           Yes
            ascii.no_header  Yes   Yes            No
                  ascii.rdb  Yes   Yes           Yes
           ascii.sextractor  Yes    No            No
                  ascii.tab  Yes   Yes            No
                        cds  Yes    No            No        Yes
                    daophot  Yes    No            No        Yes
                       fits  Yes   Yes           Yes
                       hdf5  Yes   Yes           Yes
                       ipac  Yes   Yes            No        Yes
                      latex  Yes   Yes            No        Yes
                        rdb  Yes   Yes            No        Yes
                    votable  Yes   Yes           Yes
=========================== ==== ===== ============= ==========

Deprecated format names like ``aastex`` will be removed in a future version.
Use the full name (e.g. ``ascii.aastex``) instead.

.. _table_io_ascii:

ASCII formats
^^^^^^^^^^^^^^

The :meth:`~astropy.table.table.Table.read` and
:meth:`~astropy.table.table.Table.write` methods can be used to read and write formats
supported by `astropy.io.ascii`.

Use ``format='ascii'`` in order to interface to the generic
:func:`~astropy.io.ascii.ui.read` and :func:`~astropy.io.ascii.ui.write`
functions from `astropy.io.ascii`.  When reading a table this means
that all supported ASCII table formats will be tried in order to successfully
{'fraction_non_alphanumeric': 0.12863662293211636, 'fraction_numerical': 0.0001426126640045636, 'mean_word_length': 2.5872122762148337, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4183710', 'n_tokens_mistral': 1921, 'n_tokens_neox': 1799, 'n_words': 725}