ASCII Tables (

Introduction provides methods for reading and writing a wide range of ASCII data table formats via built-in Extension Reader classes. The emphasis is on flexibility and ease of use.

The following formats are supported:

The package is built on a modular and extensible class structure with independent Base class elements so that new formats can be easily accomodated.


It is also possible to use the functionality from through a higher-level interface in the astropy.table package. See Reading and writing Table objects for more details.

Getting Started

Reading Tables

The majority of commonly encountered ASCII tables can be easily read with the read() function. Assume you have a file named sources.dat with the following contents:

obsid redshift  X      Y     object
3102  0.32      4167  4085   Q1250+568-A
877   0.22      4378  3892   "Source 82"

This table can be read with the following:

>>> from import ascii
>>> data ="sources.dat")
>>> print data
obsid redshift  X    Y      object
----- -------- ---- ---- -----------
 3102     0.32 4167 4085 Q1250+568-A
  877     0.22 4378 3892   Source 82

The first argument to the read() function can be the name of a file, a string representation of a table, or a list of table lines. By default read() will try to guess the table format by trying all the supported formats. If this does not work (for unusually formatted tables) then one needs give additional hints about the format, for example:

>>> lines = ['objID                   & osrcid            & xsrcid       ',
             '----------------------- & ----------------- & -------------',
             '              277955213 & S000.7044P00.7513 & XS04861B6_005',
             '              889974380 & S002.9051P14.7003 & XS03957B7_004']
>>> data =, data_start=2, delimiter='&')
>>> print data
  objID         osrcid          xsrcid
--------- ----------------- -------------
277955213 S000.7044P00.7513 XS04861B6_005
889974380 S002.9051P14.7003 XS03957B7_004

Writing Tables

The write() function provides a way to write a data table as a formatted ASCII table. For example the following writes a table as a simple space-delimited file:

>>> x = np.array([1, 2, 3])
>>> y = x ** 2
>>> data = Table()
>>> ascii.write([x, y], names=['x', 'y'], 'values.dat')

The values.dat file will then contain:

x y
1 1
2 4
3 9

All of the input Reader formats supported by for reading are also supported for writing. This provides a great deal of flexibility in the format for writing. The example below writes the data as a LaTeX table, using the option to send the output to sys.stdout instead of a file:

>>> ascii.write(data, sys.stdout, Writer=ascii.Latex)
x & y \\
1 & 1 \\
2 & 4 \\
3 & 9 \\

Reference/API Module

An extensible ASCII table reader and writer.


convert_numpy(numpy_type) Return a tuple (converter_func, converter_type).
get_reader([Reader, Inputter, Outputter]) Initialize a table reader allowing for common customizations.
get_writer([Writer]) Initialize a table writer allowing for common customizations.
read(table[, guess]) Read the input table and return the table.
set_guess(guess) Set the default value of the guess parameter for read()
write(table[, output, Writer]) Write the input table to filename.


AASTex(**kwargs) Write and read AASTeX tables.
BaseData() Base table data reader.
BaseHeader() Base table header reader
BaseInputter Get the lines from the table input and return a list of lines.
BaseOutputter Output table as a dict of column objects keyed on column name.
BaseReader() Class providing methods to read and write an ASCII table using the specified header, data, inputter, and outputter instances.
BaseSplitter Base splitter that uses python’s split method to do the work.
Basic() Read a character-delimited table with a single header line at the top followed by data lines to the end of the table.
Cds([readme]) Read a CDS format table.
Column(name, index) Table column.
CommentedHeader() Read a file where the column names are given in a line that begins with the header comment character.
ContinuationLinesInputter Inputter where lines ending in continuation_char are joined with the subsequent line.
Daophot() Read a DAOphot file.
DefaultSplitter() Default class to split strings into columns using python csv.
FixedWidth([col_starts, col_ends, ...]) Read or write a fixed width table with a single header line that defines column names and positions.
FixedWidthData() Base table data reader.
FixedWidthHeader() Fixed width table header reader.
FixedWidthNoHeader([col_starts, col_ends, ...]) Read or write a fixed width table which has no header line.
FixedWidthSplitter Split line based on fixed start and end positions for each col in self.cols.
FixedWidthTwoLine([position_line, ...]) Read or write a fixed width table which has two header lines.
Ipac([definition]) Read an IPAC format table.
Latex([ignore_latex_commands, latexdict, ...]) Write and read LaTeX tables.
NoHeader() Read a table with no header line.
Rdb() Read a tab-separated file with an extra line after the column definition line.
SExtractor() Read a SExtractor file.
Tab() Read a tab-separated file.
TableOutputter Output the table as an astropy.table.Table object.

Class Inheritance Diagram

Inheritance diagram of,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,