← Back
Editing: tables.py
# $Id: tables.py 9363 2023-04-24 16:37:37Z aa-turner $ # Authors: David Goodger <goodger@python.org>; David Priest # Copyright: This module has been placed in the public domain. """ Directives for table elements. """ __docformat__ = 'reStructuredText' import csv from pathlib import Path import warnings from docutils import io, nodes, statemachine, utils from docutils.utils import SystemMessagePropagation from docutils.parsers.rst import Directive from docutils.parsers.rst import directives from urllib.request import urlopen from urllib.error import URLError def align(argument): return directives.choice(argument, ('left', 'center', 'right')) class Table(Directive): """ Generic table base class. """ optional_arguments = 1 final_argument_whitespace = True option_spec = {'class': directives.class_option, 'name': directives.unchanged, 'align': align, 'width': directives.length_or_percentage_or_unitless, 'widths': directives.value_or(('auto', 'grid'), directives.positive_int_list)} has_content = True def make_title(self): if self.arguments: title_text = self.arguments[0] text_nodes, messages = self.state.inline_text(title_text, self.lineno) title = nodes.title(title_text, '', *text_nodes) (title.source, title.line) = self.state_machine.get_source_and_line(self.lineno) else: title = None messages = [] return title, messages def process_header_option(self): # Provisional # * Will move to CSVTable in Docutils 0.21 # as it calls `self.HeaderDialect()` only defined in CSVTable. # * Will change to use the same CSV dialect as the body to get in line # with the specification in ref/rst/directives.txt in Docutils 0.21. source = self.state_machine.get_source(self.lineno - 1) table_head = [] max_header_cols = 0 if 'header' in self.options: # separate table header in option with warnings.catch_warnings(): warnings.simplefilter('ignore') header_dialect = self.HeaderDialect() rows, max_header_cols = self.parse_csv_data_into_rows( self.options['header'].split('\n'), header_dialect, source) table_head.extend(rows) return table_head, max_header_cols def check_table_dimensions(self, rows, header_rows, stub_columns): if len(rows) < header_rows: error = self.reporter.error('%s header row(s) specified but ' 'only %s row(s) of data supplied ("%s" directive).' % (header_rows, len(rows), self.name), nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) if len(rows) == header_rows > 0: error = self.reporter.error( f'Insufficient data supplied ({len(rows)} row(s)); ' 'no data remaining for table body, ' f'required by "{self.name}" directive.', nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) for row in rows: if len(row) < stub_columns: error = self.reporter.error( f'{stub_columns} stub column(s) specified ' f'but only {len(row)} columns(s) of data supplied ' f'("{self.name}" directive).', nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) if len(row) == stub_columns > 0: error = self.reporter.error( 'Insufficient data supplied (%s columns(s)); ' 'no data remaining for table body, required ' 'by "%s" directive.' % (len(row), self.name), nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) def set_table_width(self, table_node): if 'width' in self.options: table_node['width'] = self.options.get('width') @property def widths(self): return self.options.get('widths', '') def get_column_widths(self, n_cols): if isinstance(self.widths, list): if len(self.widths) != n_cols: # TODO: use last value for missing columns? error = self.reporter.error('"%s" widths do not match the ' 'number of columns in table (%s).' % (self.name, n_cols), nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) col_widths = self.widths elif n_cols: col_widths = [100 // n_cols] * n_cols else: error = self.reporter.error('No table data detected in CSV file.', nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) return col_widths def extend_short_rows_with_empty_cells(self, columns, parts): for part in parts: for row in part: if len(row) < columns: row.extend([(0, 0, 0, [])] * (columns - len(row))) class RSTTable(Table): """ Class for the `"table" directive`__ for formal tables using rST syntax. __ https://docutils.sourceforge.io/docs/ref/rst/directives.html """ def run(self): if not self.content: warning = self.reporter.warning('Content block expected ' 'for the "%s" directive; none found.' % self.name, nodes.literal_block(self.block_text, self.block_text), line=self.lineno) return [warning] title, messages = self.make_title() node = nodes.Element() # anonymous container for parsing self.state.nested_parse(self.content, self.content_offset, node) if len(node) != 1 or not isinstance(node[0], nodes.table): error = self.reporter.error('Error parsing content block for the ' '"%s" directive: exactly one table expected.' % self.name, nodes.literal_block(self.block_text, self.block_text), line=self.lineno) return [error] table_node = node[0] table_node['classes'] += self.options.get('class', []) self.set_table_width(table_node) if 'align' in self.options: table_node['align'] = self.options.get('align') if isinstance(self.widths, list): tgroup = table_node[0] try: col_widths = self.get_column_widths(tgroup["cols"]) except SystemMessagePropagation as detail: return [detail.args[0]] colspecs = [child for child in tgroup.children if child.tagname == 'colspec'] for colspec, col_width in zip(colspecs, col_widths): colspec['colwidth'] = col_width if self.widths == 'auto': table_node['classes'] += ['colwidths-auto'] elif self.widths: # "grid" or list of integers table_node['classes'] += ['colwidths-given'] self.add_name(table_node) if title: table_node.insert(0, title) return [table_node] + messages class CSVTable(Table): option_spec = {'header-rows': directives.nonnegative_int, 'stub-columns': directives.nonnegative_int, 'header': directives.unchanged, 'width': directives.length_or_percentage_or_unitless, 'widths': directives.value_or(('auto', ), directives.positive_int_list), 'file': directives.path, 'url': directives.uri, 'encoding': directives.encoding, 'class': directives.class_option, 'name': directives.unchanged, 'align': align, # field delimiter char 'delim': directives.single_char_or_whitespace_or_unicode, # treat whitespace after delimiter as significant 'keepspace': directives.flag, # text field quote/unquote char: 'quote': directives.single_char_or_unicode, # char used to escape delim & quote as-needed: 'escape': directives.single_char_or_unicode} class DocutilsDialect(csv.Dialect): """CSV dialect for `csv_table` directive.""" delimiter = ',' quotechar = '"' doublequote = True skipinitialspace = True strict = True lineterminator = '\n' quoting = csv.QUOTE_MINIMAL def __init__(self, options): if 'delim' in options: self.delimiter = options['delim'] if 'keepspace' in options: self.skipinitialspace = False if 'quote' in options: self.quotechar = options['quote'] if 'escape' in options: self.doublequote = False self.escapechar = options['escape'] super().__init__() class HeaderDialect(csv.Dialect): """ CSV dialect used for the "header" option data. Deprecated. Will be removed in Docutils 0.22. """ # The separate HeaderDialect was introduced in revision 2294 # (2004-06-17) in the sandbox before the "csv-table" directive moved # to the trunk in r2309. Discussion in docutils-devel around this time # did not mention a rationale (part of the discussion was in private # mail). # This is in conflict with the documentation, which always said: # "" # and did not change in this aspect. # # Maybe it was intended to have similar escape rules for rST and CSV, # however with the current implementation this means we need # `\\` for rST markup and ``\\\\`` for a literal backslash # in the "option" header but ``\`` and ``\\`` in the header-lines and # table cells of the main CSV data. delimiter = ',' quotechar = '"' escapechar = '\\' doublequote = False skipinitialspace = True strict = True lineterminator = '\n' quoting = csv.QUOTE_MINIMAL def __init__(self): warnings.warn('CSVTable.HeaderDialect will be removed ' 'in Docutils 0.22.', PendingDeprecationWarning, stacklevel=2) super().__init__() @staticmethod def check_requirements(): warnings.warn('CSVTable.check_requirements()' ' is not required with Python 3' ' and will be removed in Docutils 0.22.', DeprecationWarning, stacklevel=2) def run(self): try: if (not self.state.document.settings.file_insertion_enabled and ('file' in self.options or 'url' in self.options)): warning = self.reporter.warning('File and URL access ' 'deactivated; ignoring "%s" directive.' % self.name, nodes.literal_block(self.block_text, self.block_text), line=self.lineno) return [warning] title, messages = self.make_title() csv_data, source = self.get_csv_data() table_head, max_header_cols = self.process_header_option() rows, max_cols = self.parse_csv_data_into_rows( csv_data, self.DocutilsDialect(self.options), source) max_cols = max(max_cols, max_header_cols) header_rows = self.options.get('header-rows', 0) stub_columns = self.options.get('stub-columns', 0) self.check_table_dimensions(rows, header_rows, stub_columns) table_head.extend(rows[:header_rows]) table_body = rows[header_rows:] col_widths = self.get_column_widths(max_cols) self.extend_short_rows_with_empty_cells(max_cols, (table_head, table_body)) except SystemMessagePropagation as detail: return [detail.args[0]] except csv.Error as detail: message = str(detail) error = self.reporter.error('Error with CSV data' ' in "%s" directive:\n%s' % (self.name, message), nodes.literal_block(self.block_text, self.block_text), line=self.lineno) return [error] table = (col_widths, table_head, table_body) table_node = self.state.build_table(table, self.content_offset, stub_columns, widths=self.widths) table_node['classes'] += self.options.get('class', []) if 'align' in self.options: table_node['align'] = self.options.get('align') self.set_table_width(table_node) self.add_name(table_node) if title: table_node.insert(0, title) return [table_node] + messages def get_csv_data(self): """ Get CSV data from the directive content, from an external file, or from a URL reference. """ encoding = self.options.get( 'encoding', self.state.document.settings.input_encoding) error_handler = self.state.document.settings.input_encoding_error_handler # noqa:E501 if self.content: # CSV data is from directive content. if 'file' in self.options or 'url' in self.options: error = self.reporter.error('"%s" directive may not both ' 'specify an external file and have content.' % self.name, nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) source = self.content.source(0) csv_data = self.content elif 'file' in self.options: # CSV data is from an external file. if 'url' in self.options: error = self.reporter.error('The "file" and "url" options ' 'may not be simultaneously specified ' 'for the "%s" directive.' % self.name, nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) source = self.options['file'] # resolve path to external file _base = Path(self.state.document.current_source).parent source = utils.relative_path(None, _base/source) try: csv_file = io.FileInput(source_path=source, encoding=encoding, error_handler=error_handler) csv_data = csv_file.read().splitlines() except OSError as error: severe = self.reporter.severe( 'Problems with "%s" directive path:\n%s.' % (self.name, error), nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(severe) else: self.state.document.settings.record_dependencies.add(source) elif 'url' in self.options: source = self.options['url'] try: with urlopen(source) as response: csv_text = response.read() except (URLError, OSError, ValueError) as error: severe = self.reporter.severe( 'Problems with "%s" directive URL "%s":\n%s.' % (self.name, self.options['url'], error), nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(severe) csv_file = io.StringInput( source=csv_text, source_path=source, encoding=encoding, error_handler=(self.state.document.settings. input_encoding_error_handler)) csv_data = csv_file.read().splitlines() else: error = self.reporter.warning( 'The "%s" directive requires content; none supplied.' % self.name, nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) return csv_data, source @staticmethod def decode_from_csv(s): warnings.warn('CSVTable.decode_from_csv()' ' is not required with Python 3' ' and will be removed in Docutils 0.21 or later.', DeprecationWarning, stacklevel=2) return s @staticmethod def encode_for_csv(s): warnings.warn('CSVTable.encode_from_csv()' ' is not required with Python 3' ' and will be removed in Docutils 0.21 or later.', DeprecationWarning, stacklevel=2) return s def parse_csv_data_into_rows(self, csv_data, dialect, source): csv_reader = csv.reader((line + '\n' for line in csv_data), dialect=dialect) rows = [] max_cols = 0 for row in csv_reader: row_data = [] for cell in row: cell_data = (0, 0, 0, statemachine.StringList( cell.splitlines(), source=source)) row_data.append(cell_data) rows.append(row_data) max_cols = max(max_cols, len(row)) return rows, max_cols class ListTable(Table): """ Implement tables whose data is encoded as a uniform two-level bullet list. For further ideas, see https://docutils.sourceforge.io/docs/dev/rst/alternatives.html#list-driven-tables """ option_spec = {'header-rows': directives.nonnegative_int, 'stub-columns': directives.nonnegative_int, 'width': directives.length_or_percentage_or_unitless, 'widths': directives.value_or(('auto', ), directives.positive_int_list), 'class': directives.class_option, 'name': directives.unchanged, 'align': align} def run(self): if not self.content: error = self.reporter.error('The "%s" directive is empty; ' 'content required.' % self.name, nodes.literal_block(self.block_text, self.block_text), line=self.lineno) return [error] title, messages = self.make_title() node = nodes.Element() # anonymous container for parsing self.state.nested_parse(self.content, self.content_offset, node) try: num_cols, col_widths = self.check_list_content(node) table_data = [[item.children for item in row_list[0]] for row_list in node[0]] header_rows = self.options.get('header-rows', 0) stub_columns = self.options.get('stub-columns', 0) self.check_table_dimensions(table_data, header_rows, stub_columns) except SystemMessagePropagation as detail: return [detail.args[0]] table_node = self.build_table_from_list(table_data, col_widths, header_rows, stub_columns) if 'align' in self.options: table_node['align'] = self.options.get('align') table_node['classes'] += self.options.get('class', []) self.set_table_width(table_node) self.add_name(table_node) if title: table_node.insert(0, title) return [table_node] + messages def check_list_content(self, node): if len(node) != 1 or not isinstance(node[0], nodes.bullet_list): error = self.reporter.error( 'Error parsing content block for the "%s" directive: ' 'exactly one bullet list expected.' % self.name, nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) list_node = node[0] num_cols = 0 # Check for a uniform two-level bullet list: for item_index in range(len(list_node)): item = list_node[item_index] if len(item) != 1 or not isinstance(item[0], nodes.bullet_list): error = self.reporter.error( 'Error parsing content block for the "%s" directive: ' 'two-level bullet list expected, but row %s does not ' 'contain a second-level bullet list.' % (self.name, item_index + 1), nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) elif item_index: if len(item[0]) != num_cols: error = self.reporter.error( 'Error parsing content block for the "%s" directive: ' 'uniform two-level bullet list expected, but row %s ' 'does not contain the same number of items as row 1 ' '(%s vs %s).' % (self.name, item_index + 1, len(item[0]), num_cols), nodes.literal_block(self.block_text, self.block_text), line=self.lineno) raise SystemMessagePropagation(error) else: num_cols = len(item[0]) col_widths = self.get_column_widths(num_cols) return num_cols, col_widths def build_table_from_list(self, table_data, col_widths, header_rows, stub_columns): table = nodes.table() if self.widths == 'auto': table['classes'] += ['colwidths-auto'] elif self.widths: # explicitly set column widths table['classes'] += ['colwidths-given'] tgroup = nodes.tgroup(cols=len(col_widths)) table += tgroup for col_width in col_widths: colspec = nodes.colspec() if col_width is not None: colspec.attributes['colwidth'] = col_width if stub_columns: colspec.attributes['stub'] = 1 stub_columns -= 1 tgroup += colspec rows = [] for row in table_data: row_node = nodes.row() for cell in row: entry = nodes.entry() entry += cell row_node += entry rows.append(row_node) if header_rows: thead = nodes.thead() thead.extend(rows[:header_rows]) tgroup += thead tbody = nodes.tbody() tbody.extend(rows[header_rows:]) tgroup += tbody return table
Save File
Cancel