tableio 0.7__tar.gz → 0.8__tar.gz

{tableio-0.7/tableio.egg-info → tableio-0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tableio
-Version: 0.7
+Version: 0.8
 Summary: Uniform way to write table data to and read from different file formats
 Author: Tom Björkholm
 Author-email: Tom Björkholm <klausuler_linnet0q@icloud.com>
@@ -137,8 +137,9 @@ a better start by reading the examples.
 
 ## Test summary
 
-- Test result: 1186 passed in 18s
+- Test result: 1311 passed in 19s
 - No flake8 warnings.
 - No mypy errors found.
-- Built version(s): 0.7
+- No python layout warnings.
+- Built version(s): 0.8
 - Build and test using Python 3.14.4

{tableio-0.7 → tableio-0.8}/README.md

@@ -93,8 +93,9 @@ information about the build system. This README can also be viewed at
 
 ## Test summary
 
-- Test result: 1186 passed in 18s
+- Test result: 1311 passed in 19s
 - No flake8 warnings.
 - No mypy errors found.
-- Built version(s): 0.7
+- No python layout warnings.
+- Built version(s): 0.8
 - Build and test using Python 3.14.4

{tableio-0.7 → tableio-0.8}/README_pypi.md

@@ -109,8 +109,9 @@ a better start by reading the examples.
 
 ## Test summary
 
-- Test result: 1186 passed in 18s
+- Test result: 1311 passed in 19s
 - No flake8 warnings.
 - No mypy errors found.
-- Built version(s): 0.7
+- No python layout warnings.
+- Built version(s): 0.8
 - Build and test using Python 3.14.4

{tableio-0.7 → tableio-0.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tableio"
-version = "0.7"
+version = "0.8"
 authors = [
   { name="Tom Björkholm", email="klausuler_linnet0q@icloud.com" },
 ]

{tableio-0.7 → tableio-0.8}/setup.py

@@ -5,7 +5,7 @@ from setuptools import setup
 
 setup(
   name='tableio',
-  version='0.7',
+  version='0.8',
   description='Uniform way to write table data to and read from different ' \
     'file formats',
   author='Tom Björkholm',

{tableio-0.7 → tableio-0.8}/src/tableio/__init__.py

@@ -7,7 +7,18 @@
 
 from tableio.capability import CAP_IGNORABLE, CAP_NEEDED, CAP_NOT_USED, \
     Capabilities
+from tableio.access_capability import NO_ERROR_OUTPUT, \
+    InsufficientCapabilities, access_capabilities, add_access_capabilities, \
+    check_access_capabilities
 from tableio.color import Color
+from tableio.config_data import ConfigData, CsvConfigData, HtmlConfigData, \
+    LatexConfigData
+from tableio.config_data_apply import tio_config_create, tio_config_default, \
+    tio_config_ignored_names, tio_config_optional_args, tio_config_trim
+from tableio.config_data_describe import ConfigSpec, tio_config_describe, \
+    tio_config_descriptions, tio_config_specs
+from tableio.config_data_error import ConfigError, ConfigIssue
+from tableio.config_data_validate import tio_config_validate
 from tableio.factory import create_tableio, filter_args_tableio, \
     list_implementations_tableio, list_registered_tableio
 from tableio.optional_args import CsvDialect, OptionalArgs, OptionalArgsDict
@@ -40,10 +51,21 @@ __all__ = ['create_tableio',
            'CellT',
            'Color',
            'Capabilities',
+           'NO_ERROR_OUTPUT',
+           'InsufficientCapabilities',
            'CAP_NEEDED',
            'CAP_NOT_USED',
            'CAP_IGNORABLE',
+           'access_capabilities',
+           'add_access_capabilities',
+           'check_access_capabilities',
            'filter_args_tableio',
            'list_registered_tableio',
            'list_implementations_tableio',
-           'CsvDialect']
+           'CsvDialect',
+           'ConfigData', 'ConfigError', 'ConfigIssue', 'ConfigSpec',
+           'CsvConfigData', 'HtmlConfigData', 'LatexConfigData',
+           'tio_config_create', 'tio_config_default',
+           'tio_config_describe', 'tio_config_descriptions',
+           'tio_config_ignored_names', 'tio_config_optional_args',
+           'tio_config_specs', 'tio_config_trim', 'tio_config_validate']

tableio-0.8/src/tableio/access_capability.py

@@ -0,0 +1,156 @@
+#! /usr/bin/env python3
+"""Helpers that connect file access modes to capability requests."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+
+import os
+from typing import NoReturn, TextIO
+
+from tableio.capability import CAP_NEEDED, Capabilities
+from tableio.tableio_types import FileAccess
+
+
+# pylint: disable-next=consider-using-with
+NO_ERROR_OUTPUT: TextIO = open(os.devnull, 'w', encoding='utf-8')
+"""Text stream used when helper errors should not be printed."""
+
+
+class InsufficientCapabilities(ValueError):
+    """Raised when requested capabilities contradict requested file access.
+
+    Error raised when the caller supplies file access and explicit
+    Capabilities, but the requested capabilities do not include the capability
+    implied by that access mode. For example, READ requires can_read, CREATE
+    requires can_write, and UPDATE requires both.
+    """
+
+    def __init__(self, message: str, capability_names: tuple[str, ...] =
+                 ()) -> None:
+        """Initialize the exception."""
+        self.capability_names = capability_names
+        super().__init__(message)
+
+
+def _raise_error(error_file: TextIO, error: Exception) -> NoReturn:
+    """Write an error message and raise the error."""
+    error_file.write(str(error) + '\n')
+    raise error
+
+
+def _check_access_value(file_access: FileAccess, error_file: TextIO) -> None:
+    """Raise if file access is not a supported FileAccess value."""
+    if not isinstance(file_access, FileAccess):
+        error = TypeError('file_access must be a FileAccess value.')
+        _raise_error(error_file, error)
+    valid_access = (FileAccess.READ, FileAccess.CREATE, FileAccess.UPDATE)
+    if file_access not in valid_access:
+        error = ValueError(f'unsupported file access: {file_access!r}.')
+        _raise_error(error_file, error)
+
+
+def _check_capabilities_value(capabilities: Capabilities,
+                              error_file: TextIO) -> None:
+    """Raise if capabilities is not a Capabilities object."""
+    if not isinstance(capabilities, Capabilities):
+        error = TypeError('capabilities must be a Capabilities object.')
+        _raise_error(error_file, error)
+
+
+def access_capabilities(file_access: FileAccess,
+                        error_file: TextIO = NO_ERROR_OUTPUT) -> Capabilities:
+    """Return the capabilities implied by a file access mode.
+
+    Args:
+        file_access: File access mode to convert to capability requirements.
+        error_file: Text stream receiving error messages before exceptions.
+    Raises:
+        TypeError: If file_access is not a FileAccess value.
+        ValueError: If file_access is an unsupported FileAccess value.
+    Returns:
+        Capabilities needed for the requested file access.
+    """
+    _check_access_value(file_access, error_file)
+    if file_access == FileAccess.READ:
+        return Capabilities(can_read=CAP_NEEDED)
+    if file_access == FileAccess.CREATE:
+        return Capabilities(can_write=CAP_NEEDED)
+    return Capabilities(can_read=CAP_NEEDED, can_write=CAP_NEEDED)
+
+
+def add_access_capabilities(file_access: FileAccess,
+                            capabilities: Capabilities,
+                            error_file: TextIO = NO_ERROR_OUTPUT) \
+        -> Capabilities:
+    """Return capabilities with file access requirements added.
+
+    The original capabilities object is not mutated.
+
+    Args:
+        file_access: File access mode to add capability requirements for.
+        capabilities: Existing capability requirements to extend.
+        error_file: Text stream receiving error messages before exceptions.
+    Raises:
+        TypeError: If file_access or capabilities has an invalid type.
+        ValueError: If file_access is an unsupported FileAccess value.
+    Returns:
+        New Capabilities object including the file access requirements.
+    """
+    _check_access_value(file_access, error_file)
+    _check_capabilities_value(capabilities, error_file)
+    if file_access == FileAccess.READ:
+        return capabilities._replace(can_read=CAP_NEEDED)
+    if file_access == FileAccess.CREATE:
+        return capabilities._replace(can_write=CAP_NEEDED)
+    return capabilities._replace(can_read=CAP_NEEDED, can_write=CAP_NEEDED)
+
+
+def _missing_access_caps(file_access: FileAccess,
+                         capabilities: Capabilities) -> tuple[str, ...]:
+    """Return capability names missing for the requested access mode."""
+    if file_access == FileAccess.READ and not capabilities.can_read.supported:
+        return ('can_read',)
+    if file_access == FileAccess.CREATE and \
+            not capabilities.can_write.supported:
+        return ('can_write',)
+    if file_access == FileAccess.UPDATE:
+        missing: list[str] = []
+        if not capabilities.can_read.supported:
+            missing.append('can_read')
+        if not capabilities.can_write.supported:
+            missing.append('can_write')
+        return tuple(missing)
+    return ()
+
+
+def _access_error_message(file_access: FileAccess) -> str:
+    """Return the error message for missing access capabilities."""
+    if file_access == FileAccess.READ:
+        return 'FileAccess.READ requires can_read capability.'
+    if file_access == FileAccess.CREATE:
+        return 'FileAccess.CREATE requires can_write capability.'
+    return 'FileAccess.UPDATE requires both can_read and can_write ' + \
+        'capabilities.'
+
+
+def check_access_capabilities(file_access: FileAccess,
+                              capabilities: Capabilities,
+                              error_file: TextIO = NO_ERROR_OUTPUT) -> None:
+    """Raise if capabilities are not enough for requested access mode.
+
+    Args:
+        file_access: File access mode to check capability requirements for.
+        capabilities: Capability requirements to check.
+        error_file: Text stream receiving error messages before exceptions.
+    Raises:
+        TypeError: If file_access or capabilities has an invalid type.
+        ValueError: If file_access is an unsupported FileAccess value.
+        InsufficientCapabilities: If capabilities do not support file_access.
+    """
+    _check_access_value(file_access, error_file)
+    _check_capabilities_value(capabilities, error_file)
+    missing_caps = _missing_access_caps(file_access, capabilities)
+    if missing_caps:
+        message = _access_error_message(file_access)
+        error = InsufficientCapabilities(message, missing_caps)
+        _raise_error(error_file, error)

{tableio-0.7 → tableio-0.8}/src/tableio/border_helper.py

@@ -30,11 +30,8 @@ class CellBorder(NamedTuple):
     left: BorderWeight
 
 
-NO_BORDERS = CellBorder(
-    BorderWeight.NONE,
-    BorderWeight.NONE,
-    BorderWeight.NONE,
-    BorderWeight.NONE)
+NO_BORDERS = CellBorder(BorderWeight.NONE, BorderWeight.NONE,
+                        BorderWeight.NONE, BorderWeight.NONE)
 """The absence of borders on all four cell edges."""
 
 
@@ -68,61 +65,40 @@ def _thicker(first: BorderWeight, second: BorderWeight) -> BorderWeight:
 
 _STYLE_COMPONENTS: dict[TableBorderStyle, _BorderComponents] = {
     TableBorderStyle.NONE: _BorderComponents(
-        outer=BorderWeight.NONE,
-        first_row_separator=BorderWeight.NONE,
-        inner_horizontal=BorderWeight.NONE,
-        inner_vertical=BorderWeight.NONE),
+        outer=BorderWeight.NONE, first_row_separator=BorderWeight.NONE,
+        inner_horizontal=BorderWeight.NONE, inner_vertical=BorderWeight.NONE),
     TableBorderStyle.OUTER_THIN: _BorderComponents(
-        outer=BorderWeight.THIN,
-        first_row_separator=BorderWeight.NONE,
-        inner_horizontal=BorderWeight.NONE,
-        inner_vertical=BorderWeight.NONE),
+        outer=BorderWeight.THIN, first_row_separator=BorderWeight.NONE,
+        inner_horizontal=BorderWeight.NONE, inner_vertical=BorderWeight.NONE),
     TableBorderStyle.OUTER_THICK: _BorderComponents(
-        outer=BorderWeight.THICK,
-        first_row_separator=BorderWeight.NONE,
-        inner_horizontal=BorderWeight.NONE,
-        inner_vertical=BorderWeight.NONE),
+        outer=BorderWeight.THICK, first_row_separator=BorderWeight.NONE,
+        inner_horizontal=BorderWeight.NONE, inner_vertical=BorderWeight.NONE),
     TableBorderStyle.OUTER_FIRST_ROW_THIN: _BorderComponents(
-        outer=BorderWeight.THIN,
-        first_row_separator=BorderWeight.THIN,
-        inner_horizontal=BorderWeight.NONE,
-        inner_vertical=BorderWeight.NONE),
+        outer=BorderWeight.THIN, first_row_separator=BorderWeight.THIN,
+        inner_horizontal=BorderWeight.NONE, inner_vertical=BorderWeight.NONE),
     TableBorderStyle.OUTER_FIRST_ROW_THICK: _BorderComponents(
-        outer=BorderWeight.THICK,
-        first_row_separator=BorderWeight.THICK,
-        inner_horizontal=BorderWeight.NONE,
-        inner_vertical=BorderWeight.NONE),
+        outer=BorderWeight.THICK, first_row_separator=BorderWeight.THICK,
+        inner_horizontal=BorderWeight.NONE, inner_vertical=BorderWeight.NONE),
     TableBorderStyle.OUTER_THICK_FIRST_ROW_THIN: _BorderComponents(
-        outer=BorderWeight.THICK,
-        first_row_separator=BorderWeight.THIN,
-        inner_horizontal=BorderWeight.NONE,
-        inner_vertical=BorderWeight.NONE),
+        outer=BorderWeight.THICK, first_row_separator=BorderWeight.THIN,
+        inner_horizontal=BorderWeight.NONE, inner_vertical=BorderWeight.NONE),
     TableBorderStyle.OUTER_FIRST_ROW_THICK_VERTICAL_THIN:
-        _BorderComponents(
-            outer=BorderWeight.THICK,
-            first_row_separator=BorderWeight.THICK,
-            inner_horizontal=BorderWeight.NONE,
-            inner_vertical=BorderWeight.THIN),
+        _BorderComponents(outer=BorderWeight.THICK,
+                          first_row_separator=BorderWeight.THICK,
+                          inner_horizontal=BorderWeight.NONE,
+                          inner_vertical=BorderWeight.THIN),
     TableBorderStyle.OUTER_FIRST_ROW_THICK_INNER_THIN: _BorderComponents(
-        outer=BorderWeight.THICK,
-        first_row_separator=BorderWeight.THICK,
-        inner_horizontal=BorderWeight.THIN,
-        inner_vertical=BorderWeight.THIN),
+        outer=BorderWeight.THICK, first_row_separator=BorderWeight.THICK,
+        inner_horizontal=BorderWeight.THIN, inner_vertical=BorderWeight.THIN),
     TableBorderStyle.OUTER_THICK_INNER_THIN: _BorderComponents(
-        outer=BorderWeight.THICK,
-        first_row_separator=BorderWeight.NONE,
-        inner_horizontal=BorderWeight.THIN,
-        inner_vertical=BorderWeight.THIN),
+        outer=BorderWeight.THICK, first_row_separator=BorderWeight.NONE,
+        inner_horizontal=BorderWeight.THIN, inner_vertical=BorderWeight.THIN),
     TableBorderStyle.ALL_THIN: _BorderComponents(
-        outer=BorderWeight.THIN,
-        first_row_separator=BorderWeight.NONE,
-        inner_horizontal=BorderWeight.THIN,
-        inner_vertical=BorderWeight.THIN),
+        outer=BorderWeight.THIN, first_row_separator=BorderWeight.NONE,
+        inner_horizontal=BorderWeight.THIN, inner_vertical=BorderWeight.THIN),
     TableBorderStyle.ALL_THICK: _BorderComponents(
-        outer=BorderWeight.THICK,
-        first_row_separator=BorderWeight.NONE,
-        inner_horizontal=BorderWeight.THICK,
-        inner_vertical=BorderWeight.THICK)
+        outer=BorderWeight.THICK, first_row_separator=BorderWeight.NONE,
+        inner_horizontal=BorderWeight.THICK, inner_vertical=BorderWeight.THICK)
 }
 
 

{tableio-0.7 → tableio-0.8}/src/tableio/capability.py

@@ -125,8 +125,7 @@ def single_capability_match(offered: SingleCapability,
     return False
 
 
-def capability_match(offered: Capabilities,
-                     will_use: Capabilities,
+def capability_match(offered: Capabilities, will_use: Capabilities,
                      ignore_allowed: bool = False) -> bool:
     """Check if the offered capabilities match the required capabilities.
 

tableio-0.8/src/tableio/config_data.py

@@ -0,0 +1,117 @@
+#! /usr/local/bin/python3
+"""Configuration data for the tableio package."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+
+from dataclasses import dataclass
+from typing import Optional
+from tableio.optional_args import CsvDialect
+
+
+@dataclass
+class CsvConfigData:
+    """CSV-specific configuration values.
+
+    This class holds durable user choices that only have meaning for CSV
+    output. The values are allowed to be present even when another format is
+    selected; helper functions decide whether they are relevant for the
+    current TableIO backend. The class has no configuration-framework base
+    class, so adapter libraries may combine it with their own base classes.
+    """
+
+    dialect: Optional[CsvDialect] = None
+    """The CSV dialect template to use, or ``None`` for backend default."""
+
+    delimiter: Optional[str] = None
+    """The CSV delimiter to use, or ``None`` for backend default."""
+
+    quoting: Optional[str] = None
+    """The CSV quoting style to use, or ``None`` for backend default."""
+
+    quotechar: Optional[str] = None
+    """The CSV quote character to use, or ``None`` for backend default."""
+
+    lineterminator: Optional[str] = None
+    """The CSV line terminator to use, or ``None`` for backend default."""
+
+    escapechar: Optional[str] = None
+    """The CSV escape character to use, or ``None`` for backend default."""
+
+
+@dataclass
+class HtmlConfigData:
+    """HTML-specific configuration values.
+
+    The class has no configuration-framework base class, so adapter
+    libraries may combine it with their own base classes.
+    """
+
+    css_file: Optional[str] = None
+    """The CSS file path or URL to reference, or ``None`` for no CSS file."""
+
+
+@dataclass
+class LatexConfigData:
+    """LaTeX-specific configuration values.
+
+    The class has no configuration-framework base class, so adapter
+    libraries may combine it with their own base classes.
+    """
+
+    document_class: Optional[str] = None
+    """The LaTeX document class to use, or ``None`` for backend default."""
+
+    preamble: Optional[str] = None
+    """Extra LaTeX preamble text, or ``None`` for backend default."""
+
+
+@dataclass
+class ConfigData:  # pylint: disable=too-many-instance-attributes
+    """Durable, framework-neutral TableIO configuration choices.
+
+    This class intentionally excludes runtime intent. File names, file access,
+    capabilities and callbacks are supplied to helper functions instead of
+    being stored as configuration values. The default format is Excel, and
+    format-specific nested sections default to ``None`` until a user or
+    application deliberately configures them.
+
+    The class has no configuration-framework base class, so adapter libraries
+    may combine it with their own base classes.
+    """
+
+    format_name: str = 'excel'
+    """The TableIO format name. Matching is case-insensitive."""
+
+    implementation: Optional[str] = None
+    """The optional implementation pin, or ``None`` to choose best match."""
+
+    character_encoding: Optional[str] = None
+    """The text encoding to use, or ``None`` for backend default."""
+
+    language: Optional[str] = None
+    """The document language value mapped to backend ``lang`` arguments."""
+
+    title: Optional[str] = None
+    """The document title, or ``None`` for backend default."""
+
+    paper_size: Optional[str] = None
+    """The document paper size, or ``None`` for backend default."""
+
+    line_length: Optional[int] = None
+    """The preferred text line length, or ``None`` for backend default."""
+
+    table_max_line_length: Optional[int] = None
+    """The preferred text table line length, or ``None`` for default."""
+
+    table_alignment: Optional[str] = None
+    """The preferred text table alignment, or ``None`` for default."""
+
+    csv: Optional[CsvConfigData] = None
+    """CSV-specific configuration values, or ``None`` when unset."""
+
+    html: Optional[HtmlConfigData] = None
+    """HTML-specific configuration values, or ``None`` when unset."""
+
+    latex: Optional[LatexConfigData] = None
+    """LaTeX-specific configuration values, or ``None`` when unset."""