tableio 0.1__tar.gz

tableio-0.1/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Tom Björkholm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

tableio-0.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: tableio
+Version: 0.1
+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>
+License-Expression: MIT
+Project-URL: Source code, https://bitbucket.org/tom-bjorkholm/table-io
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 2 - Pre-Alpha
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: pip>=26.0.1
+Requires-Dist: setuptools>=82.0.1
+Requires-Dist: build>=1.4.0
+Requires-Dist: wheel>=0.46.3
+Requires-Dist: mformat-ext>=0.6
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: types-openpyxl>=3.1.5.20260322
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+
+# tableio
+
+The tableio package contains a number of classes providing a uniform way for
+a python program to write table data (rows of columns) to and read table data
+from a number of different common file formats.
+
+The primary intended use is for text output from a python program, where the
+programmer would like the user to be able to select the input and output file
+formats.
+
+The support for spreadsheets is for reading and writing data. There is no
+intention to support reading or writing formulas. There is no support for
+running calculations in the spreadsheets (although nothing will stop a
+receiver of a spreadsheet created by tableio package to manually add
+formulas in the received spreadsheet).
+
+## Early design phase
+
+This project is in an early design phase. This means that major changes to the APIs are still expected.
+
+## Installing tableio
+
+### Installing tableio on mac and Linux
+
+````sh
+pip3 install --upgrade tableio
+````
+
+### Installing tableio on Microsoft Windows
+
+````sh
+pip install --upgrade tableio
+````
+
+## Supported formats
+
+The currently supported formats are:
+
+| File format | Implementation | Can write | Can read |
+|-------------|----------------|-----------|----------|
+| CSV         | csv            | yes       | yes      |
+| Excel       | OpenPyXL       | yes       | yes      |
+| HTML        | mformat        | yes       | -        |
+| LaTeX       | mformat        | yes       | -        |
+| docx        | mformat        | yes       | -        |
+| md          | mformat        | yes       | -        |
+| odt         | mformat        | yes       | -        |
+| pdf         | mformat        | yes       | -        |
+| rst         | mformat        | yes       | -        |
+| rtf         | mformat        | yes       | -        |
+| txt         | mformat        | yes       | -        |
+
+## Example programs
+
+Some example programs are available at: [https://bitbucket.org/tom-bjorkholm/table-io/src/master/example/src/example/](https://bitbucket.org/tom-bjorkholm/table-io/src/master/example/src/example/).
+
+## API documentation
+
+Be aware that this is still in early development. The APIs may change between versions.
+
+You can find the public API documentation at [https://bitbucket.org/tom-bjorkholm/table-io/src/master/doc/api.md](https://bitbucket.org/tom-bjorkholm/table-io/src/master/doc/api.md)
+
+You can find the protected API documentation at [https://bitbucket.org/tom-bjorkholm/table-io/src/master/doc/protected_api.md](https://bitbucket.org/tom-bjorkholm/table-io/src/master/doc/protected_api.md)
+The protected API documentation is only for developers that want to
+extend the framework with by adding their own classes as registered
+readers/writers to the factory.
+
+Even though the API documentation exists, most users and programmers probably get
+a better start by reading the examples.
+
+## Version history
+
+| Version | Date        | Python version | Comment                |
+|---------|-------------|----------------|------------------------|
+| 0.1     | 2026 Mar 23 | 3.12 or newer  | First released version |
+
+## Test summary
+
+- Test result: 634 passed in 17s
+- No Flake8 warnings.
+- No mypy errors found.
+- Built version(s): 0.1
+- Build and test using Python 3.14.3

tableio-0.1/README.md

@@ -0,0 +1,105 @@
+# tableio
+
+## Early protoype
+
+This package is still an early prototype. This means that major changes to the APIs are expected.
+
+## Use
+
+> **👤 Looking to use this in your program**  
+> This repository is for developers of the package. If you want to install and use `tableio` including writing programs that use them, please visit the **PyPI project page [https://pypi.org/project/tableio](https://pypi.org/project/tableio) for installation instructions and user documentation.
+
+## What is it
+
+The tableio package contains a number of classes providing a uniform way for
+a python program to write table data (rows of columns) to and read table data
+from a number of different common file formats.
+
+The primary intended use is for text output from a python program, where the
+programmer would like the user to be able to select the input and output file
+formats.
+
+The support for spreadsheets is for reading and writing data. There is no
+intention to support reading or writing formulas. There is no support for
+running calculations in the spreadsheets (although nothing will stop a
+receiver of a spreadsheet created by tableio package to manually add
+formulas in the received spreadsheet).
+
+## For developers
+
+### Cloning
+
+The tableio repo uses submodules. To clone it use the command:
+
+````sh
+git clone --recurse-submodules git@bitbucket.org:tom-bjorkholm/table-io.git
+````
+
+If you forgot to include the `--recurse-submodules` in your `git clone` command
+you can fix it later with the command:
+
+````sh
+git submodule update --init --recursive 
+````
+
+To update the version of thr submodule repo that you see in the main repo use the command:
+
+````sh
+git submodule update --remote --merge
+````
+
+### Needed environment
+
+#### OS
+
+For running the script and running the test suite you need a mac or a Linux computer. Even if the resulting package can be installed and used on Windows, the scripts for building and testing are only implemented for mac and Linux.
+
+#### Python version
+
+Please see README_pypi.md for information on needed python version. Main development is on newest Python version.
+
+#### Zsh
+
+Most scripts are Python.
+Some scripts are zsh. zsh is available by default on modern macs. zsh can easily be installed on Linux (on Ubuntu: `sudo apt install zsh`).
+
+### Quick start
+
+1. Clone this repository
+2. Run `./setup_build_environment.zsh` to set up the build environment
+3. Run `./doBuild.zsh` to build and test the package
+
+### Building application
+
+There are 3 main scripts (and 2 extra convinience scripts) for building the application:
+
+- `run_setup_build_environment.py` Run this script first to get the
+  environment set up for building.
+- `run_build.py` Run this script to build an installation package (.whl) and
+  to run the tests on it in a venv (virtual environment).
+- `run_clean.py` Deletes all files that was produced by the build to start
+  over from a clean state.
+- `run_clean_build.py` Combines the use of `run_clean.py`,
+  `run_setup_build_environment.py` and `run_build.py` into one script.
+  Pylint discover some duplicate code warnings only on a clean build so this
+  is useful.
+- `run_pypi_build.py` Builds for PyPI upload and can do the upload too.
+
+The "testing" includes pytest, pylint, flake8 and mypy.
+
+After running `run_build.py` you can open `reports/index.html` to see all test
+reports.
+
+### More build system information
+
+The file `./common_build_tools/README.md` (in git submodule - see above) contains more
+information about the build system. This README can also be viewed at
+[https://bitbucket.org/tom-bjorkholm/common_build_tools/src/master/README.md](https://bitbucket.org/tom-bjorkholm/common_build_tools/src/master/README.md)
+
+## Test summary
+
+- Test result: 634 passed in 17s
+- No Flake8 warnings.
+- No mypy errors found.
+- Built version(s): 0.1
+- Build and test using Python 3.14.3

tableio-0.1/README_pypi.md

@@ -0,0 +1,83 @@
+# tableio
+
+The tableio package contains a number of classes providing a uniform way for
+a python program to write table data (rows of columns) to and read table data
+from a number of different common file formats.
+
+The primary intended use is for text output from a python program, where the
+programmer would like the user to be able to select the input and output file
+formats.
+
+The support for spreadsheets is for reading and writing data. There is no
+intention to support reading or writing formulas. There is no support for
+running calculations in the spreadsheets (although nothing will stop a
+receiver of a spreadsheet created by tableio package to manually add
+formulas in the received spreadsheet).
+
+## Early design phase
+
+This project is in an early design phase. This means that major changes to the APIs are still expected.
+
+## Installing tableio
+
+### Installing tableio on mac and Linux
+
+````sh
+pip3 install --upgrade tableio
+````
+
+### Installing tableio on Microsoft Windows
+
+````sh
+pip install --upgrade tableio
+````
+
+## Supported formats
+
+The currently supported formats are:
+
+| File format | Implementation | Can write | Can read |
+|-------------|----------------|-----------|----------|
+| CSV         | csv            | yes       | yes      |
+| Excel       | OpenPyXL       | yes       | yes      |
+| HTML        | mformat        | yes       | -        |
+| LaTeX       | mformat        | yes       | -        |
+| docx        | mformat        | yes       | -        |
+| md          | mformat        | yes       | -        |
+| odt         | mformat        | yes       | -        |
+| pdf         | mformat        | yes       | -        |
+| rst         | mformat        | yes       | -        |
+| rtf         | mformat        | yes       | -        |
+| txt         | mformat        | yes       | -        |
+
+## Example programs
+
+Some example programs are available at: [https://bitbucket.org/tom-bjorkholm/table-io/src/master/example/src/example/](https://bitbucket.org/tom-bjorkholm/table-io/src/master/example/src/example/).
+
+## API documentation
+
+Be aware that this is still in early development. The APIs may change between versions.
+
+You can find the public API documentation at [https://bitbucket.org/tom-bjorkholm/table-io/src/master/doc/api.md](https://bitbucket.org/tom-bjorkholm/table-io/src/master/doc/api.md)
+
+You can find the protected API documentation at [https://bitbucket.org/tom-bjorkholm/table-io/src/master/doc/protected_api.md](https://bitbucket.org/tom-bjorkholm/table-io/src/master/doc/protected_api.md)
+The protected API documentation is only for developers that want to
+extend the framework with by adding their own classes as registered
+readers/writers to the factory.
+
+Even though the API documentation exists, most users and programmers probably get
+a better start by reading the examples.
+
+## Version history
+
+| Version | Date        | Python version | Comment                |
+|---------|-------------|----------------|------------------------|
+| 0.1     | 2026 Mar 23 | 3.12 or newer  | First released version |
+
+## Test summary
+
+- Test result: 634 passed in 17s
+- No Flake8 warnings.
+- No mypy errors found.
+- Built version(s): 0.1
+- Build and test using Python 3.14.3

tableio-0.1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tableio"
+version = "0.1"
+authors = [
+  { name="Tom Björkholm", email="klausuler_linnet0q@icloud.com" },
+]
+description = "Uniform way to write table data to and read from different file formats"
+readme = "README_pypi.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Development Status :: 2 - Pre-Alpha"
+]
+dynamic = ["dependencies"]
+
+[project.urls]
+"Source code" = "https://bitbucket.org/tom-bjorkholm/table-io"

tableio-0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tableio-0.1/setup.py

@@ -0,0 +1,26 @@
+#! /usr/local/bin/python3
+"""Setup file specifying build of .whl."""
+
+from setuptools import setup
+
+setup(
+  name='tableio',
+  version='0.1',
+  description='Uniform way to write table data to and read from different ' \
+    'file formats',
+  author='Tom Björkholm',
+  author_email='klausuler_linnet0q@icloud.com',
+  python_requires='>=3.12',
+  packages=['tableio'],
+  package_dir={'tableio': 'src/tableio'},
+  package_data={'tableio': ['src/py.typed']},
+  install_requires=[  # pylint: disable=duplicate-code
+    'pip >= 26.0.1',
+    'setuptools >= 82.0.1',
+    'build >= 1.4.0',
+    'wheel >= 0.46.3',
+    'mformat-ext >= 0.6',
+    'openpyxl >= 3.1.5',
+    'types-openpyxl >= 3.1.5.20260322'
+  ]
+)

tableio-0.1/src/tableio/__init__.py

@@ -0,0 +1,6 @@
+#! /usr/local/bin/python3
+"""Initialize the tableio package."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+#

tableio-0.1/src/tableio/capability.py

@@ -0,0 +1,156 @@
+#! /usr/bin/env python3
+"""Capabilities of the reader/writer class for a file format."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+
+from typing import NamedTuple
+from enum import IntEnum, auto
+
+
+class Strictness(IntEnum):
+    """Strictness of a capability."""
+
+    STRICT = auto()
+    """Strictly enforce, raise if not supported."""
+    IGNORE = auto()
+    """Ignored if not supported."""
+
+
+class SingleCapability(NamedTuple):
+    """Single capability of aspect of reader/writer class.
+
+    Describes if a reader/writer class for a file format can handle a
+    specific aspect when reading or writing a file.
+
+    A reader/writer class will provide information about its capabilities in a
+    Capabilities object. For the single capability this says if it is
+    supported, but also how the class behaves if it is requested and not
+    supported.
+    If supported is True, the strictness is not used.
+    If supported is False, and the strictness is STRICT, an exception is raised
+    when a call to the reader/writer class is made that requires the
+    capability.
+    If supported is False, and the strictness is IGNORE, the call is ignored.
+
+    When requesting reader/writer class from the factory, the requester can
+    specify that only reader/writer classes that support the requested
+    capabilities are returned.
+    If the requester sets supported to True for a capability, it means that
+    the requester will be making calls to the reader/writer class that requires
+    the capability.
+    If the requester sets supported to False for a capability, it means that
+    the requester will not be making calls to the reader/writer class that
+    requires the capability. (If the requester sets supported to false, the
+    strictness will not be used.)
+    If the requester sets supported to True and strictness to STRICT, it means
+    that the requester is only accepting reader/writer classes that support
+    the capability.
+    If the requester sets supported to True and strictness to IGNORE, it means
+    that the requester is accepting reader/writer classes that may ignore
+    calls using the capability.
+    """
+
+    supported: bool = False
+    """If the capability is supported."""
+    strictness: Strictness = Strictness.IGNORE
+    """How the capability is handled if not supported. Default is to ignore."""
+
+
+class Capabilities(NamedTuple):
+    """Capabilities of a reader/writer class for a file format."""
+
+    can_write: SingleCapability = SingleCapability()
+    """The reader/writer class can write to the file format."""
+
+    can_read: SingleCapability = SingleCapability()
+    """The reader/writer class can read from the file format."""
+
+    can_fmt_row: SingleCapability = SingleCapability()
+    """The writer class can apply a format to a row."""
+
+    can_fmt_value: SingleCapability = SingleCapability()
+    """The writer class can apply a format to a value."""
+
+    filtered_data_range: SingleCapability = SingleCapability()
+    """The writer class can mark a table as a filterable data range."""
+
+    can_write_box: SingleCapability = SingleCapability()
+    """The writer class can write to position given by a box."""
+
+    can_read_box: SingleCapability = SingleCapability()
+    """The reader class can read from position given by a box."""
+
+    can_write_highlight: SingleCapability = SingleCapability()
+    """The writer class can write highlight according to format."""
+
+
+def single_capability_match(offered: SingleCapability,
+                            will_use: SingleCapability,
+                            ignore_allowed: bool = True) -> bool:
+    """Check if the offered single capability matches the will use.
+
+    Args:
+        offered: The offered single capability. Does the reader/writer
+                 class support this capability?
+        will_use: The will use single capability. Does the requester intend to
+                  use this capability?
+        ignore_allowed: If False: when the offered single capability would
+                        ignore the will use single capability it is
+                        considered a mismatch, and will return False.
+                        If False: when the offered single capability would
+                        ignore the will use single capability it is
+                        considered a match, and will return True.
+    Returns:
+        True if the offered single capability matches the will use,
+        False otherwise.
+    """
+    if not will_use.supported:
+        return True
+    if offered.supported:
+        return True
+    if Strictness.STRICT in (offered.strictness, will_use.strictness):
+        return False
+    if ignore_allowed:
+        return True
+    return False
+
+
+def capability_match(offered: Capabilities,
+                     will_use: Capabilities,
+                     ignore_allowed: bool = False) -> bool:
+    """Check if the offered capabilities match the required capabilities.
+
+    Args:
+        offered: The offered capabilities. What capabilities does the
+                 reader/writer class support?
+        will_use: The recuested capabilities. What capabilities
+                  does the requester intend to use?
+        ignore_allowed: If False: when an offered capability would ignore a
+                        will use capability it is considered a mismatch, and
+                        considered a mismatch, and will return False.
+                        If True: when an offered capability would ignore a
+                        will use capability it is considered a match, and
+                        will return True.
+    Returns:
+        True if the offered capabilities match the will_use capabilities,
+        False otherwise.
+    """
+    for single_offered, single_will_use in zip(offered, will_use):
+        if not single_capability_match(single_offered, single_will_use,
+                                       ignore_allowed):
+            return False
+    return True
+
+
+class CapabilityNotSupported(ValueError):
+    """Exception raised when a capability is not supported."""
+
+    def __init__(self, action: str):
+        """Initialize the exception.
+
+        Args:
+            action: The requested action that is not supported.
+        """
+        self.action = action
+        super().__init__(f'The class does not support {action}.')

tableio-0.1/src/tableio/color.py

@@ -0,0 +1,20 @@
+#! /usr/bin/env python3
+"""Highlight colors for the tableio package."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+
+from enum import IntEnum
+
+
+class Color(IntEnum):
+    """Highlight colors for the tableio package."""
+
+    NONE = 0
+    """No hightlight color."""
+    RED = 1
+    """Red highlight color."""
+    GREEN = 2
+    """Green highlight color."""
+    YELLOW = 3
+    """Yellow highlight color."""