tableio 0.8__tar.gz → 0.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tableio
-Version: 0.8
+Version: 0.9
 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,9 +137,9 @@ a better start by reading the examples.
 
 ## Test summary
 
-- Test result: 1311 passed in 19s
+- Test result: 1344 passed in 20s
 - No flake8 warnings.
 - No mypy errors found.
 - No python layout warnings.
-- Built version(s): 0.8
+- Built version(s): 0.9
 - Build and test using Python 3.14.4

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

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

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

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

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

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

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

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

{tableio-0.8 → tableio-0.9}/src/tableio/access_capability.py

@@ -4,16 +4,22 @@
 # Copyright (c) 2026 Tom Björkholm
 # MIT License
 
-import os
+from enum import Enum, auto
 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 NoErrorOutput(Enum):
+    """Text stream marker when helper errors should not be printed."""
+
+    NO_OUTPUT = auto()
+    """Text stream marker when helper errors should not be printed."""
+
+
+NO_ERROR_OUTPUT = NoErrorOutput.NO_OUTPUT
+"""Text stream marker used when helper errors should not be printed."""
 
 
 class InsufficientCapabilities(ValueError):
@@ -32,13 +38,17 @@ class InsufficientCapabilities(ValueError):
         super().__init__(message)
 
 
-def _raise_error(error_file: TextIO, error: Exception) -> NoReturn:
+def _raise_error(error_file: TextIO | NoErrorOutput,
+                 error: Exception) -> NoReturn:
     """Write an error message and raise the error."""
+    if isinstance(error_file, NoErrorOutput):
+        raise error
     error_file.write(str(error) + '\n')
     raise error
 
 
-def _check_access_value(file_access: FileAccess, error_file: TextIO) -> None:
+def _check_access_value(file_access: FileAccess,
+                        error_file: TextIO | NoErrorOutput) -> 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.')
@@ -50,7 +60,7 @@ def _check_access_value(file_access: FileAccess, error_file: TextIO) -> None:
 
 
 def _check_capabilities_value(capabilities: Capabilities,
-                              error_file: TextIO) -> None:
+                              error_file: TextIO | NoErrorOutput) -> None:
     """Raise if capabilities is not a Capabilities object."""
     if not isinstance(capabilities, Capabilities):
         error = TypeError('capabilities must be a Capabilities object.')
@@ -58,7 +68,8 @@ def _check_capabilities_value(capabilities: Capabilities,
 
 
 def access_capabilities(file_access: FileAccess,
-                        error_file: TextIO = NO_ERROR_OUTPUT) -> Capabilities:
+                        error_file: TextIO | NoErrorOutput =
+                        NO_ERROR_OUTPUT) -> Capabilities:
     """Return the capabilities implied by a file access mode.
 
     Args:
@@ -80,7 +91,8 @@ def access_capabilities(file_access: FileAccess,
 
 def add_access_capabilities(file_access: FileAccess,
                             capabilities: Capabilities,
-                            error_file: TextIO = NO_ERROR_OUTPUT) \
+                            error_file: TextIO | NoErrorOutput =
+                            NO_ERROR_OUTPUT) \
         -> Capabilities:
     """Return capabilities with file access requirements added.
 
@@ -135,7 +147,8 @@ def _access_error_message(file_access: FileAccess) -> str:
 
 def check_access_capabilities(file_access: FileAccess,
                               capabilities: Capabilities,
-                              error_file: TextIO = NO_ERROR_OUTPUT) -> None:
+                              error_file: TextIO | NoErrorOutput =
+                              NO_ERROR_OUTPUT) -> None:
     """Raise if capabilities are not enough for requested access mode.
 
     Args:

{tableio-0.8 → tableio-0.9}/src/tableio/config_data_apply.py

@@ -4,7 +4,7 @@
 # Copyright (c) 2026 Tom Björkholm
 # MIT License
 
-from typing import Callable, Optional, TypeVar, cast
+from typing import Callable, NoReturn, Optional, TypeVar, cast
 
 from mformat.mformat import PathLike
 from tableio.access_capability import add_access_capabilities
@@ -24,15 +24,14 @@ _FORMAT_PRIORITY = ('excel', 'ods', 'csv')
 _ValueT = TypeVar('_ValueT')
 
 
-def _config_error(name: str, message: str) -> None:
+def _config_error(name: str, message: str) -> NoReturn:
     """Raise one structured configuration error."""
     raise ConfigError((ConfigIssue(name, message),))
 
 
 def _check_default_input(capabilities: Capabilities, file_access: FileAccess,
                          format_name: Optional[str],
-                         implementation: Optional[str],
-                         include_all_options: bool) -> None:
+                         implementation: Optional[str]) -> None:
     """Validate runtime values used for default selection."""
     if not isinstance(capabilities, Capabilities):
         _config_error('capabilities', 'must be a Capabilities object.')
@@ -42,8 +41,15 @@ def _check_default_input(capabilities: Capabilities, file_access: FileAccess,
         _config_error('format_name', 'must be a string or None.')
     if implementation is not None and not isinstance(implementation, str):
         _config_error('implementation', 'must be a string or None.')
+
+
+def _check_default_flags(include_all_options: bool,
+                         impl_in_cfg: Optional[bool]) -> None:
+    """Validate flags used for default selection."""
     if not isinstance(include_all_options, bool):
         _config_error('include_all_options', 'must be a bool.')
+    if impl_in_cfg is not None and not isinstance(impl_in_cfg, bool):
+        _config_error('impl_in_cfg', 'must be a bool or None.')
 
 
 def _registered_formats_by_lower() -> dict[str, str]:
@@ -103,7 +109,6 @@ def _best_default_names(capabilities: Capabilities, format_name: Optional[str],
         return selected_format, selected_impl
     name = 'implementation' if implementation is not None else 'format_name'
     _config_error(name, 'does not match registered TableIO backends.')
-    raise AssertionError('Unreachable default selection failure.')
 
 
 def _base_arg_items(config: ConfigData) -> list[tuple[str, str, object]]:
@@ -184,7 +189,8 @@ def _filtered_args(config: ConfigData, capabilities: Optional[Capabilities],
     return filtered
 
 
-def _all_option_config(format_name: str, implementation: str) -> ConfigData:
+def _all_option_config(format_name: str,
+                       implementation: Optional[str]) -> ConfigData:
     """Return a configuration object with all options visible."""
     csv = CsvConfigData(dialect=CsvDialect.UNIX, delimiter=',', quoting='all',
                         quotechar='"', lineterminator='\n', escapechar='\\')
@@ -198,10 +204,21 @@ def _all_option_config(format_name: str, implementation: str) -> ConfigData:
                       html=html, latex=latex)
 
 
-def tio_config_default(capabilities: Capabilities, file_access: FileAccess,
+def _include_default_impl(implementation: Optional[str],
+                          include_all_options: bool,
+                          impl_in_cfg: Optional[bool]) -> bool:
+    """Return true if the default config should pin implementation."""
+    if impl_in_cfg is not None:
+        return impl_in_cfg
+    return implementation is not None or include_all_options
+
+
+# pylint: disable-next=too-many-arguments
+def tio_config_default(capabilities: Capabilities, file_access: FileAccess, *,
                        format_name: Optional[str] = None,
                        implementation: Optional[str] = None,
-                       include_all_options: bool = False) -> ConfigData:
+                       include_all_options: bool = False,
+                       impl_in_cfg: Optional[bool] = None) -> ConfigData:
     """Return recommended default configuration data.
 
     Default format and implementation selection first prefers implementations
@@ -211,6 +228,17 @@ def tio_config_default(capabilities: Capabilities, file_access: FileAccess,
     If several implementations of the selected format match equally well,
     their TableIO implementation priority is used.
 
+    Usually it is better to not include the implementation name in the
+    configuration, as that allows the TableIO library to choose the best
+    implementation based on the capabilities and file access at runtime.
+    If you want to include the implementation name in the configuration,
+    you can set the impl_in_cfg parameter to True. If you set it to False,
+    the implementation name will always be omitted from the configuration.
+    If you set it to None, the implementation name will normally be omitted
+    from the configuration, but if include_all_options is True or if
+    implementation was explicitly provided, the implementation name will be
+    included.
+
     Args:
         capabilities: Runtime capabilities the application intends to use.
         file_access: Runtime file access requested by the application.
@@ -218,12 +246,21 @@ def tio_config_default(capabilities: Capabilities, file_access: FileAccess,
         implementation: Optional preferred implementation name.
         include_all_options: Include visible non-None values for all
             configuration options, for teaching and configuration templates.
+        impl_in_cfg: Optional flag to include the implementation name in the
+            configuration. If None, the implementation name will normally be
+            omitted from the configuration, but if include_all_options is True
+            or if implementation was explicitly provided, the implementation
+            name will be included. If True, the implementation name will be
+            included in the configuration. If False, the implementation name
+            will always be omitted from the configuration.
     Returns:
         A configuration object containing durable user choices only.
     """
     _check_default_input(capabilities, file_access, format_name,
-                         implementation, include_all_options)
+                         implementation)
+    _check_default_flags(include_all_options, impl_in_cfg)
     match_caps = add_access_capabilities(file_access, capabilities)
+    selected_impl: Optional[str] = None
     selected_format, selected_impl = _best_default_names(match_caps,
                                                          format_name,
                                                          implementation)
@@ -231,6 +268,9 @@ def tio_config_default(capabilities: Capabilities, file_access: FileAccess,
         selected_format = format_name
     if implementation is not None:
         selected_impl = implementation
+    if not _include_default_impl(implementation, include_all_options,
+                                 impl_in_cfg):
+        selected_impl = None
     if include_all_options:
         config = _all_option_config(selected_format, selected_impl)
     else:
@@ -341,9 +381,9 @@ def tio_config_trim(config: ConfigData,
                                        filtered_names),
                       line_length=_kept(config.line_length, 'line_length',
                                         filtered_names),
-                      table_max_line_length=_kept(
-                          config.table_max_line_length,
-                          'table_max_line_length', filtered_names),
+                      table_max_line_length=_kept(config.table_max_line_length,
+                                                  'table_max_line_length',
+                                                  filtered_names),
                       table_alignment=_kept(config.table_alignment,
                                             'table_alignment', filtered_names),
                       csv=csv, html=html, latex=latex)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tableio
-Version: 0.8
+Version: 0.9
 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,9 +137,9 @@ a better start by reading the examples.
 
 ## Test summary
 
-- Test result: 1311 passed in 19s
+- Test result: 1344 passed in 20s
 - No flake8 warnings.
 - No mypy errors found.
 - No python layout warnings.
-- Built version(s): 0.8
+- Built version(s): 0.9
 - Build and test using Python 3.14.4