tableio 1.1__tar.gz → 1.2__tar.gz

{tableio-1.1 → tableio-1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tableio
-Version: 1.1
+Version: 1.2
 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>
@@ -19,8 +19,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: mformat-ext>=0.7
 Requires-Dist: openpyxl>=3.1.5
-Requires-Dist: types-openpyxl>=3.1.5.20260518
-Requires-Dist: odfdo>=3.22.10
+Requires-Dist: types-openpyxl>=3.1.5.20260827
+Requires-Dist: odfdo>=3.26.3
 Requires-Dist: xlsxwriter>=3.2.9
 Requires-Dist: pylightxl>=1.61
 Dynamic: author
@@ -111,6 +111,7 @@ The main features are:
   - int
   - float
   - datetime
+  - timedelta (see below)
 - writing a table as a filtered data range
 - writing a table to a specific location in a spreadsheet (specified by a box)
 - reading table data from a specific location in a spreadsheet (specified by a box)
@@ -119,6 +120,43 @@ The main features are:
   at that position or at positions relative to that position.
 - several border styles for tables
 
+## Timedelta (duration) values
+
+Excel (OpenPyXL, XlsxWriter, pylightxl) and ODS (odfdo) store `timedelta`
+values natively, as duration cells, and read them back as `timedelta`.
+(OpenPyXL reads durations with millisecond precision.)
+The cells are displayed as `[hh]:mm:ss` (hours do not wrap at 24, seconds
+are displayed rounded to whole seconds, the stored value is exact).
+Microsoft Excel has no duration type, it stores a duration as a number of
+days with a time number format. So by design Excel shows the cell as for
+instance `72:00:00`, but shows the value as a date and time (like
+`1/3/1900 12:00:00 AM`) in the formula bar when the cell is selected. Excel
+does the same for durations typed in by hand, and LibreOffice shows
+`72:00:00` in both places for the same file.
+Notice also that Microsoft Excel cannot display negative durations (it
+shows `####`). The stored value is still correct, it is read back
+correctly and LibreOffice displays it as for instance `-00:03:58`. If
+negative durations must be readable in Microsoft Excel, consider storing
+the magnitude and the sign in separate columns.
+
+Formats without native duration support (CSV and all write-only document
+formats) write a fallback representation, selected with the optional
+argument `timedelta_fallback` (a `TimeDeltaFallback` value):
+
+| TimeDeltaFallback     | Two days, three hours and 1.5 seconds |
+|-----------------------|---------------------------------------|
+| `HMS_STRING` (default)| `51:00:01.5`                          |
+| `DHMS_STRING`         | `2 d 03:00:01.5`                      |
+| `DHMS_STRING_LONG`    | `2 days 03:00:01.5`                   |
+| `WDHMS_STRING`        | `2 d 03:00:01.5` (with `W w` if a week or more) |
+| `WDHMS_STRING_LONG`   | `2 days 03:00:01.5` (with `W weeks` if a week or more) |
+| `FLOATSECONDS`        | `183601.5`                            |
+
+Negative durations get a leading `-`. When reading such a file the values
+are strings (CSV). Convert them with `parse_timedelta()`, that accepts all
+fallback formats (and `timedelta` values, so it works for all formats).
+`format_timedelta()` formats a `timedelta` in any of the fallback formats.
+
 ## Example programs
 
 The best way to learn to use this package is to use the provided
@@ -139,9 +177,10 @@ a better start by reading the examples.
 
 ## Test summary
 
-- Test result: 1347 passed in 20s
+- Test result: 1567 passed in 9s
 - No flake8 warnings.
 - No mypy errors found.
+- No pylint warnings.
 - No python layout warnings.
-- Built version(s): 1.1
-- Build and test using Python 3.14.6
+- Built version(s): 1.2
+- Build and test using Python 3.14.7

{tableio-1.1 → tableio-1.2}/README.md

@@ -93,9 +93,10 @@ information about the build system. This README can also be viewed at
 
 ## Test summary
 
-- Test result: 1347 passed in 20s
+- Test result: 1567 passed in 9s
 - No flake8 warnings.
 - No mypy errors found.
+- No pylint warnings.
 - No python layout warnings.
-- Built version(s): 1.1
-- Build and test using Python 3.14.6
+- Built version(s): 1.2
+- Build and test using Python 3.14.7

{tableio-1.1 → tableio-1.2}/README_pypi.md

@@ -81,6 +81,7 @@ The main features are:
   - int
   - float
   - datetime
+  - timedelta (see below)
 - writing a table as a filtered data range
 - writing a table to a specific location in a spreadsheet (specified by a box)
 - reading table data from a specific location in a spreadsheet (specified by a box)
@@ -89,6 +90,43 @@ The main features are:
   at that position or at positions relative to that position.
 - several border styles for tables
 
+## Timedelta (duration) values
+
+Excel (OpenPyXL, XlsxWriter, pylightxl) and ODS (odfdo) store `timedelta`
+values natively, as duration cells, and read them back as `timedelta`.
+(OpenPyXL reads durations with millisecond precision.)
+The cells are displayed as `[hh]:mm:ss` (hours do not wrap at 24, seconds
+are displayed rounded to whole seconds, the stored value is exact).
+Microsoft Excel has no duration type, it stores a duration as a number of
+days with a time number format. So by design Excel shows the cell as for
+instance `72:00:00`, but shows the value as a date and time (like
+`1/3/1900 12:00:00 AM`) in the formula bar when the cell is selected. Excel
+does the same for durations typed in by hand, and LibreOffice shows
+`72:00:00` in both places for the same file.
+Notice also that Microsoft Excel cannot display negative durations (it
+shows `####`). The stored value is still correct, it is read back
+correctly and LibreOffice displays it as for instance `-00:03:58`. If
+negative durations must be readable in Microsoft Excel, consider storing
+the magnitude and the sign in separate columns.
+
+Formats without native duration support (CSV and all write-only document
+formats) write a fallback representation, selected with the optional
+argument `timedelta_fallback` (a `TimeDeltaFallback` value):
+
+| TimeDeltaFallback     | Two days, three hours and 1.5 seconds |
+|-----------------------|---------------------------------------|
+| `HMS_STRING` (default)| `51:00:01.5`                          |
+| `DHMS_STRING`         | `2 d 03:00:01.5`                      |
+| `DHMS_STRING_LONG`    | `2 days 03:00:01.5`                   |
+| `WDHMS_STRING`        | `2 d 03:00:01.5` (with `W w` if a week or more) |
+| `WDHMS_STRING_LONG`   | `2 days 03:00:01.5` (with `W weeks` if a week or more) |
+| `FLOATSECONDS`        | `183601.5`                            |
+
+Negative durations get a leading `-`. When reading such a file the values
+are strings (CSV). Convert them with `parse_timedelta()`, that accepts all
+fallback formats (and `timedelta` values, so it works for all formats).
+`format_timedelta()` formats a `timedelta` in any of the fallback formats.
+
 ## Example programs
 
 The best way to learn to use this package is to use the provided
@@ -109,9 +147,10 @@ a better start by reading the examples.
 
 ## Test summary
 
-- Test result: 1347 passed in 20s
+- Test result: 1567 passed in 9s
 - No flake8 warnings.
 - No mypy errors found.
+- No pylint warnings.
 - No python layout warnings.
-- Built version(s): 1.1
-- Build and test using Python 3.14.6
+- Built version(s): 1.2
+- Build and test using Python 3.14.7

{tableio-1.1 → tableio-1.2}/pyproject.toml

@@ -4,7 +4,6 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tableio"
-version = "1.1"
 authors = [
   { name="Tom Björkholm", email="klausuler_linnet0q@icloud.com" },
 ]
@@ -22,7 +21,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "Typing :: Typed"
 ]
-dynamic = ["dependencies"]
+dynamic = ["dependencies", "version"]
 
 [project.urls]
 "Source code" = "https://github.com/tom-bjorkholm/table-io"

{tableio-1.1 → tableio-1.2}/setup.py

@@ -5,7 +5,7 @@ from setuptools import setup
 
 setup(
   name='tableio',
-  version='1.1',
+  version='1.2',
   description='Uniform way to write table data to and read from different ' \
     'file formats',
   author='Tom Björkholm',
@@ -17,8 +17,8 @@ setup(
   install_requires=[
     'mformat-ext >= 0.7',
     'openpyxl >= 3.1.5',
-    'types-openpyxl >= 3.1.5.20260518',
-    'odfdo >= 3.22.10',
+    'types-openpyxl >= 3.1.5.20260827',
+    'odfdo >= 3.26.3',
     'xlsxwriter >= 3.2.9',
     'pylightxl >= 1.61'
   ]

{tableio-1.1 → tableio-1.2}/src/tableio/__init__.py

@@ -21,9 +21,11 @@ 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
+from tableio.optional_args import CsvDialect, OptionalArgs, \
+    OptionalArgsDict, TimeDeltaFallback
 from tableio.tableio import TableIO
 from tableio.tableio_types import TableBorderStyle, Box, FileAccess, Position
+from tableio.timedelta_helpers import format_timedelta, parse_timedelta
 from tableio.value_type import CellT, DictData, DictDataMap, Fmt, \
     FmtDictData, FmtDictRow, FmtListData, FmtListRow, ListData, \
     ListDataSeq, ReadResult, Value, ValueFmt
@@ -43,6 +45,8 @@ __all__ = ['create_tableio',
            'DictDataMap',
            'ReadResult',
            'Fmt',
+           'format_timedelta',
+           'parse_timedelta',
            'ValueFmt',
            'FmtListRow',
            'FmtDictRow',
@@ -63,6 +67,7 @@ __all__ = ['create_tableio',
            'list_registered_tableio',
            'list_implementations_tableio',
            'CsvDialect',
+           'TimeDeltaFallback',
            'ConfigData', 'ConfigError', 'ConfigIssue', 'ConfigSpec',
            'CsvConfigData', 'HtmlConfigData', 'LatexConfigData',
            'tio_config_create', 'tio_config_default',

{tableio-1.1 → tableio-1.2}/src/tableio/config_data.py

@@ -6,7 +6,7 @@
 
 from dataclasses import dataclass
 from typing import Optional
-from tableio.optional_args import CsvDialect
+from tableio.optional_args import CsvDialect, TimeDeltaFallback
 
 
 @dataclass
@@ -115,3 +115,10 @@ class ConfigData:  # pylint: disable=too-many-instance-attributes
 
     latex: Optional[LatexConfigData] = None
     """LaTeX-specific configuration values, or ``None`` when unset."""
+
+    timedelta_fallback: Optional[TimeDeltaFallback] = None
+    """How formats without native timedelta write it, or ``None``.
+
+    ``None`` means backend default (``TimeDeltaFallback.HMS_STRING``).
+    Formats with native timedelta support ignore this value.
+    """

{tableio-1.1 → tableio-1.2}/src/tableio/config_data_apply.py

@@ -7,6 +7,8 @@
 from typing import Callable, NoReturn, Optional, TypeVar, cast
 
 from mformat.mformat import PathLike
+from mformat.paper_size import PaperSize
+from mformat.plain_text_table import TableAlignment
 from tableio.access_capability import add_access_capabilities
 from tableio.capability import Capabilities, capability_match
 from tableio.config_data import ConfigData, CsvConfigData, HtmlConfigData, \
@@ -15,7 +17,8 @@ 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, usage_tableio
-from tableio.optional_args import CsvDialect, OptionalArgs, OptionalArgsDict
+from tableio.optional_args import CsvDialect, OptionalArgs, \
+    OptionalArgsDict, TimeDeltaFallback
 from tableio.tableio import TableIO
 from tableio.tableio_types import FileAccess
 
@@ -111,6 +114,16 @@ def _best_default_names(capabilities: Capabilities, format_name: Optional[str],
     _config_error(name, 'does not match registered TableIO backends.')
 
 
+def _paper_size(value: Optional[str]) -> Optional[PaperSize]:
+    """Return a validated paper size text as the backend enum value."""
+    return None if value is None else PaperSize.from_str(value)
+
+
+def _table_alignment(value: Optional[str]) -> Optional[TableAlignment]:
+    """Return a validated table alignment text as the backend enum value."""
+    return None if value is None else TableAlignment[value.upper()]
+
+
 def _base_arg_items(config: ConfigData) -> list[tuple[str, str, object]]:
     """Return configured top-level optional argument values."""
     return [
@@ -118,11 +131,14 @@ def _base_arg_items(config: ConfigData) -> list[tuple[str, str, object]]:
          config.character_encoding),
         ('language', 'lang', config.language),
         ('title', 'title', config.title),
-        ('paper_size', 'paper_size', config.paper_size),
+        ('paper_size', 'paper_size', _paper_size(config.paper_size)),
         ('line_length', 'line_length', config.line_length),
         ('table_max_line_length', 'table_max_line_length',
          config.table_max_line_length),
-        ('table_alignment', 'table_alignment', config.table_alignment)
+        ('table_alignment', 'table_alignment',
+         _table_alignment(config.table_alignment)),
+        ('timedelta_fallback', 'timedelta_fallback',
+         config.timedelta_fallback)
     ]
 
 
@@ -201,7 +217,8 @@ def _all_option_config(format_name: str,
                       title='HTML file', paper_size='A4', line_length=79,
                       table_max_line_length=140,
                       table_alignment='CENTER_BUT_DIGITS_RIGHT', csv=csv,
-                      html=html, latex=latex)
+                      html=html, latex=latex,
+                      timedelta_fallback=TimeDeltaFallback.HMS_STRING)
 
 
 def _include_default_impl(implementation: Optional[str],
@@ -306,6 +323,8 @@ def tio_config_create(
         TableIO:
     """Create a TableIO object from configuration and runtime values.
 
+    The implementation is selected using the capabilities together with the
+    capabilities implied by file_access, as done by the validation.
     Args:
         config: Durable configuration data.
         file_name: Runtime file name to open.
@@ -317,16 +336,18 @@ def tio_config_create(
     """
     tio_config_validate(config, capabilities=capabilities,
                         file_access=file_access)
+    match_caps = add_access_capabilities(file_access,
+                                         capabilities or Capabilities())
     extra_args = None
     if file_exists_callback is not None:
         extra_args = cast(OptionalArgsDict, {
             'file_exists_callback': file_exists_callback
         })
-    args = _filtered_args(config, capabilities, extra_args)
+    args = _filtered_args(config, match_caps, extra_args)
     return create_tableio(format_name=config.format_name, file_name=file_name,
                           file_access=file_access, args=args,
                           implementation=config.implementation,
-                          capabilities=capabilities)
+                          capabilities=match_caps)
 
 
 def tio_config_ignored_names(config: ConfigData,
@@ -386,6 +407,9 @@ def tio_config_trim(config: ConfigData,
                                                   filtered_names),
                       table_alignment=_kept(config.table_alignment,
                                             'table_alignment', filtered_names),
+                      timedelta_fallback=_kept(config.timedelta_fallback,
+                                               'timedelta_fallback',
+                                               filtered_names),
                       csv=csv, html=html, latex=latex)
 
 

{tableio-1.1 → tableio-1.2}/src/tableio/config_data_describe.py

@@ -13,7 +13,7 @@ from mformat.plain_text_table import TableAlignment
 
 from tableio.factory import list_implementations_tableio, \
     list_registered_tableio, usage_tableio
-from tableio.optional_args import CsvDialect
+from tableio.optional_args import CsvDialect, TimeDeltaFallback
 
 
 @dataclass
@@ -58,6 +58,11 @@ def _csv_dialect_choices() -> tuple[str, ...]:
     return tuple(member.name for member in CsvDialect)
 
 
+def _timedelta_fallback_choices() -> tuple[str, ...]:
+    """Return advertised timedelta fallback choices."""
+    return tuple(member.name for member in TimeDeltaFallback)
+
+
 def _table_alignment_choices() -> tuple[str, ...]:
     """Return advertised plain text table alignment choices."""
     return tuple(member.name for member in TableAlignment)
@@ -147,6 +152,13 @@ def tio_config_specs() -> dict[str, ConfigSpec]:
                              default_text='None means backend default.',
                              choices=_table_alignment_choices(),
                              optional_arg='table_alignment')),
+        _arg_spec(ConfigSpec(name='timedelta_fallback',
+                             description='How timedelta values are written '
+                             'by formats without native timedelta support.',
+                             value_type='Optional[TimeDeltaFallback]',
+                             default_text='None means backend default.',
+                             choices=_timedelta_fallback_choices(),
+                             optional_arg='timedelta_fallback')),
         _arg_spec(ConfigSpec(name='csv.dialect',
                              description='The CSV dialect template.',
                              value_type='Optional[CsvDialect]',

{tableio-1.1 → tableio-1.2}/src/tableio/config_data_validate.py

@@ -17,7 +17,7 @@ from tableio.config_data_error import ConfigError, ConfigIssue
 from tableio.factory import TableIOFactoryNoCapabilityMatch, \
     TableIOFactoryNoSuchError, filter_args_tableio, \
     list_implementations_tableio
-from tableio.optional_args import CsvDialect
+from tableio.optional_args import CsvDialect, TimeDeltaFallback
 from tableio.tableio_types import FileAccess
 
 
@@ -156,6 +156,10 @@ def _validate_top_values(config: ConfigData, specs: dict[str, ConfigSpec],
     _validate_int_min(issues, 'table_max_line_length',
                       config.table_max_line_length, 10, True)
     _valid_choice(config.table_alignment, specs['table_alignment'], issues)
+    if config.timedelta_fallback is not None and \
+            not isinstance(config.timedelta_fallback, TimeDeltaFallback):
+        _add_issue(issues, 'timedelta_fallback',
+                   'must be a TimeDeltaFallback value or None.')
 
 
 def _validate_csv(config: ConfigData, specs: dict[str, ConfigSpec],

{tableio-1.1 → tableio-1.2}/src/tableio/factory.py

@@ -6,7 +6,6 @@
 #
 
 from typing import Optional, NamedTuple
-from functools import total_ordering
 import warnings
 from mformat.mformat import PathLike
 from tableio.access_capability import check_access_capabilities
@@ -53,7 +52,6 @@ class TableIOFactoryNoCapabilityMatch(ValueError):
     """
 
 
-@total_ordering
 class ImplPrio(NamedTuple):
     """Priority of an implementation."""
 
@@ -66,25 +64,43 @@ class ImplPrio(NamedTuple):
     priority: int
     """The priority of the implementation."""
 
+    def sort_key(self) -> tuple[int, str, str]:
+        """Return the ordering key: priority, format name, implementation.
+
+        All comparison operators are defined from this key, as the
+        inherited tuple comparisons use the field order instead.
+        """
+        return (self.priority, self.format_name, self.implementation)
+
     def __lt__(self, other: object) -> bool:
         """Compare two implementation priorities."""
         if not isinstance(other, ImplPrio):
             return NotImplemented
-        if self.priority < other.priority:
-            return True
-        if self.priority > other.priority:
-            return False
-        if self.format_name < other.format_name:
-            return True
-        if self.format_name > other.format_name:
-            return False
-        return self.implementation < other.implementation
+        return self.sort_key() < other.sort_key()
+
+    def __le__(self, other: object) -> bool:
+        """Compare two implementation priorities."""
+        if not isinstance(other, ImplPrio):
+            return NotImplemented
+        return self.sort_key() <= other.sort_key()
+
+    def __gt__(self, other: object) -> bool:
+        """Compare two implementation priorities."""
+        if not isinstance(other, ImplPrio):
+            return NotImplemented
+        return self.sort_key() > other.sort_key()
+
+    def __ge__(self, other: object) -> bool:
+        """Compare two implementation priorities."""
+        if not isinstance(other, ImplPrio):
+            return NotImplemented
+        return self.sort_key() >= other.sort_key()
 
     def __eq__(self, other: object) -> bool:
         """Compare two implementation priorities."""
         if not isinstance(other, ImplPrio):
             return NotImplemented
-        return not self < other and not other < self
+        return self.sort_key() == other.sort_key()
 
 
 class BestMatch(NamedTuple):

tableio-1.2/src/tableio/optional_args.py

@@ -0,0 +1,143 @@
+#! /usr/bin/env python3
+"""Optional arguments for the tableio package."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+
+from typing import Optional, cast
+from enum import IntEnum, auto
+from mformat.factory import OptArgsDict
+
+
+class CsvDialect(IntEnum):
+    """The type of CSV file to write."""
+
+    EXCEL = auto()
+    """Excel CSV file type/dialect."""
+    UNIX = auto()
+    """Unix CSV file type/dialect."""
+
+
+class TimeDeltaFallback(IntEnum):
+    """The fallback behavior for timedelta values.
+
+    How a timedelta value is written when an implementation does not support
+    writing timedelta values. If an implementation does support timedelta
+    values, the fallback behavior specified by this enum will be ignored.
+
+    For all string formats: A negative value gets a leading '-' that applies
+    to the whole duration (for example '-01:00:00' is minus one hour).
+    Fractional seconds are written with up to six decimals, and only when
+    non-zero (for example '00:00:01.5'). The 'HH' part is always at least two
+    digits. Use ``tableio.parse_timedelta`` to read the values back.
+    """
+
+    FLOATSECONDS = auto()
+    """Convert the timedelta to a float of the total number of seconds.
+
+    Microsecond precision is lost for very large durations (roughly
+    above 100 years), as a float has limited precision.
+    """
+
+    HMS_STRING = auto()
+    """Convert the timedelta to a string in the format 'HH:MM:SS'.
+
+    Days are included in the hours, so 'HH' may exceed 24 (for example
+    '26:03:04').
+    This is the default fallback.
+    """
+
+    DHMS_STRING = auto()
+    """Convert the timedelta to a string in the format 'D d HH:MM:SS'.
+
+    The 'D d' part will only be included if the number of days is non-zero.
+    """
+
+    DHMS_STRING_LONG = auto()
+    """Convert the timedelta to a string in the format 'D days HH:MM:SS'.
+
+    The 'D days' part will only be included if the number of days is non-zero.
+    If the number of days is one, it will be written as '1 day'.
+    """
+
+    WDHMS_STRING = auto()
+    """Convert the timedelta to a string in the format 'W w D d HH:MM:SS'.
+
+    The 'W w' part will only be included if the number of weeks is non-zero.
+    The 'D d' part will only be included if the number of days is non-zero.
+    """
+
+    WDHMS_STRING_LONG = auto()
+    """Convert the timedelta to a string as 'W weeks D days HH:MM:SS'.
+
+    The 'W weeks' part will only be included if the number of weeks is
+    non-zero. If the number of weeks is one, it will be written as '1 week'.
+    The 'D days' part will only be included if the number of days is non-zero.
+    If the number of days is one, it will be written as '1 day'.
+    """
+
+
+class OptionalArgsDict(OptArgsDict, total=False):
+    """Optional arguments for the tableio package.
+
+    This is a TypedDict that describes the optional arguments that can be
+    passed to the factory in the tableio package.
+    For description of the arguments, see the class derived from TableIO
+    that uses the arguments.
+    The possible optional arguments includ the arguments in
+    mformat.factory.OptArgsDict plus the arguments specific to the tableio
+    package.
+    """
+
+    csv_dialect: Optional[CsvDialect]
+    """The type/dialect of CSV file to write. None for default type."""
+
+    csv_delimiter: Optional[str]
+    """The delimiter to use for CSV files. None for default delimiter."""
+
+    csv_quoting: Optional[str]
+    """The quoting style to use for CSV files.
+
+    Allowed values (case-insensitive): 'all', 'minimal',
+    'nonnumeric', 'none', 'strings', 'notnull'.
+    None for default quoting."""
+
+    csv_quotechar: Optional[str]
+    """The quote character to use for CSV files. None for default."""
+
+    csv_lineterminator: Optional[str]
+    """The line terminator to use for CSV files. None for default."""
+
+    csv_escapechar: Optional[str]
+    """The escape character to use for CSV files. None for default."""
+
+    timedelta_fallback: Optional[TimeDeltaFallback]
+    """The fallback format to use for timedelta, when no native support.
+
+    Silently ignored if the implementation provides native support for
+    timedelta values. None for default (TimeDeltaFallback.HMS_STRING).
+    """
+
+
+type OptionalArgs = Optional[OptionalArgsDict]
+"""Optional arguments for the factory in the tableio package."""
+
+_MFORMAT_OPTARG_NAMES: set[str] = set(OptArgsDict.__annotations__)
+
+
+def mformat_optargs_from_optionalargs(optional_args: OptionalArgs) \
+        -> Optional[OptArgsDict]:
+    """Convert the optional arguments to a dictionary of arguments for mformat.
+
+    Args:
+        optional_args: The optional arguments to convert.
+    Returns:
+        A dictionary of arguments for mformat.
+    """
+    if optional_args is None:
+        return None
+    ret = {
+        key: value for key, value in optional_args.items()
+        if key in _MFORMAT_OPTARG_NAMES and value is not None
+    }
+    return cast(OptArgsDict, ret)