tableio-cfg-json 0.1__tar.gz

tableio_cfg_json-0.1/LICENSE.txt

@@ -0,0 +1,21 @@
+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_cfg_json-0.1/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: tableio-cfg-json
+Version: 0.1
+Summary: config-as-json configuration encapsulation for tableio.
+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/tableio_cfg_json
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: setuptools>=82.0.1
+Requires-Dist: build>=1.4.2
+Requires-Dist: wheel>=0.46.3
+Requires-Dist: tableio>=0.9
+Requires-Dist: config-as-json>=0.9
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+
+# tableio-cfg-json
+
+`tableio-cfg-json` stores
+[TableIO](https://pypi.org/project/tableio/) configuration as validated JSON
+by using [config-as-json](https://pypi.org/project/config-as-json/).
+
+Use it when an application uses TableIO for table-like files and wants
+persistent, user-editable configuration for formats, implementations and
+format-specific options. The configuration objects are both TableIO
+`ConfigData` objects and config-as-json `Config` objects, so the same object
+can be written as configuration file (as JSON), read back later, validated,
+and passed to TableIO.
+
+## Is this package for you?
+
+This package is a good fit when one or more of these apply:
+
+- Your application uses TableIO.
+- You already use config-as-json, or can accept using it for persistent
+  configuration.
+- You want one configuration file to describe one TableIO input or output
+  endpoint.
+- You want to nest one or more TableIO endpoint configurations inside a
+  larger application configuration file.
+- You want validation and generated user documentation for the TableIO
+  options that are relevant to your application's capabilities.
+
+This package is probably not the right one when:
+
+- You are looking for the table reader or writer itself. Use
+  [TableIO](https://pypi.org/project/tableio/) directly.
+- Your program always uses one hard-coded table format and has no persistent
+  configuration.
+- You do not want to use config-as-json for configuration files.
+
+## Installation
+
+`tableio-cfg-json` requires Python 3.12 or newer.
+
+```sh
+pip install --upgrade tableio-cfg-json
+```
+
+## Quick start
+
+Create a compact JSON configuration file for one TableIO endpoint:
+
+```python
+from pathlib import Path
+import sys
+
+from tableio import FileAccess, access_capabilities
+from tableio_cfg_json import tio_json_config_default
+
+config_file = Path('tableio.cfg')
+file_access = FileAccess.CREATE
+capabilities = access_capabilities(file_access, error_file=sys.stderr)
+config = tio_json_config_default(capabilities=capabilities,
+                                 file_access=file_access,
+                                 format_name='CSV')
+config.write(to_json_filename=config_file)
+```
+
+For CSV this writes a small file like:
+
+```json
+{
+    "format_name": "CSV"
+}
+```
+
+Read the configuration back and use it with TableIO:
+
+```python
+from pathlib import Path
+import sys
+
+from tableio import FileAccess, access_capabilities, tio_config_create
+from tableio_cfg_json import TioJsonConfig
+
+config_file = Path('tableio.cfg')
+table_file = Path('capitals.csv')
+file_access = FileAccess.CREATE
+capabilities = access_capabilities(file_access, error_file=sys.stderr)
+config = TioJsonConfig(capabilities=capabilities,
+                       file_access=file_access,
+                       from_json_filename=config_file)
+with tio_config_create(config=config, file_name=table_file,
+                       file_access=file_access,
+                       capabilities=capabilities) as table_io:
+    table_io.write_table_listdata([
+        ['Capital', 'Country'],
+        ['Copenhagen', 'Denmark']
+    ])
+```
+
+If `implementation` is omitted, TableIO chooses a matching implementation at
+runtime. If the user wants to lock down a specific implementation, it can be
+stored explicitly in JSON.
+
+Optional settings can be added at the top level or in format-specific nested
+sections such as `csv`, `html` and `latex`. Compact output omits unset
+optional values, while template-style output can include all current default
+options.
+
+Please see the [teaching examples](https://bitbucket.org/tom-bjorkholm/tableio_cfg_json/src/master/example/src/example/README.md) for a more
+thorough introduction.
+
+## Main entry points
+
+- `TioJsonConfig`
+  Complete JSON-backed TableIO configuration for one endpoint. It can read
+  JSON, write JSON and be passed to TableIO as normal configuration data.
+
+- `tio_config_create()` create a TableIO object from a `TioJsonConfig`
+  object.
+
+### Helpers and details
+
+- `tio_json_config_default()`
+  Create a validated default `TioJsonConfig` using TableIO's recommended
+  choices for the requested capabilities and file access.
+
+- `TioJsonCsvConfig`, `TioJsonHtmlConfig`, `TioJsonLatexConfig`
+  Optional nested configuration sections for format-specific settings.
+
+- `describe_config()`, `describe_config_members()`,
+  `describe_config_reference()`, `describe_config_example()`,
+  `get_config_member_names()` and `get_general_cfg_info()`
+  Helpers for generating plain text syntax guides for configuration files.
+
+- `tio_json_config_wizard()`
+  Interactive helper for creating one TableIO endpoint configuration through
+  a user interface bridge.
+
+- `WizardUiBridge` and `WizardUiBridgeConsole`
+  Interfaces for connecting the wizard to a console, GUI or scripted UI.
+
+## Validation model
+
+The configuration file (in JSON) stores durable TableIO choices such
+as `format_name`, `implementation`, character encoding, presentation
+options and format-specific settings. Runtime values such as the actual
+file name are not stored in this configuration.
+
+Validation happens in two layers:
+
+- config-as-json validates JSON structure, member names and member value
+  types.
+- TableIO validates whether the selected format, implementation,
+  capabilities and file access can work together.
+
+Choice values are matched case-insensitively where TableIO defines a finite
+set of choices. For example, configuration file may use `excel` and the
+config object will store TableIO's normal `Excel` spelling after validation.
+
+## Nested application configs
+
+`TioJsonConfig` can be used as the whole configuration file for a small
+program, or as a nested member inside a larger config-as-json application
+configuration. This is useful when one application has several TableIO
+endpoints, for example one input table and two independently configured
+output tables.
+
+For larger configs, create each nested `TioJsonConfig` with the capabilities
+and file access for that endpoint. A read endpoint and a create endpoint may
+need different defaults and may validate different implementations.
+
+The teaching examples show both styles.
+
+## Documentation
+
+- Teaching examples and walkthroughs: [example/src/example/README.md](https://bitbucket.org/tom-bjorkholm/tableio_cfg_json/src/master/example/src/example/README.md)
+
+- Public API notes: [doc/api.md](https://bitbucket.org/tom-bjorkholm/tableio_cfg_json/src/master/doc/api.md)
+
+- Protected/internal API notes: [doc/protected_api.md](https://bitbucket.org/tom-bjorkholm/tableio_cfg_json/src/master/doc/protected_api.md)
+
+- Source repository: [tableio_cfg_json](https://bitbucket.org/tom-bjorkholm/tableio_cfg_json/)
+
+## License
+
+MIT
+
+## Test summary
+
+- Test result: 380 passed in 14s
+- No flake8 warnings.
+- No mypy errors found.
+- No python layout warnings.
+- Built version(s): 0.1
+- Build and test using Python 3.14.4

tableio_cfg_json-0.1/README.md

@@ -0,0 +1,86 @@
+# tableio-cfg-json
+
+> Looking for installation and user-facing package information?
+> See [README_pypi.md](README_pypi.md) or the
+> [PyPI project page](https://pypi.org/project/tableio-cfg-json).
+
+## Repository purpose
+
+This is a small package that stores
+[TableIO](https://pypi.org/project/tableio/) configuration as validated JSON
+by using [config-as-json](https://pypi.org/project/config-as-json/).
+
+## Related documentation
+
+- User-facing package overview: [README_pypi.md](README_pypi.md)
+- Public API notes: [doc/api.md](doc/api.md)
+- Protected/internal API notes: [doc/protected_api.md](doc/protected_api.md)
+- Build system design: [common_build_tools/README.md](common_build_tools/README.md)
+
+The example directory contains worked examples for new users and is also
+useful for maintainers who want to see intended API usage in context.
+
+## Cloning
+
+This repository uses submodules. Clone it with:
+
+```sh
+git clone --recurse-submodules \
+  git@bitbucket.org:tom-bjorkholm/tableio_cfg_json
+```
+
+If you already cloned without submodules, initialize them with:
+
+```sh
+git submodule update --init --recursive
+```
+
+To update the checked-out submodule revisions:
+
+```sh
+git submodule update --remote --merge
+```
+
+## Supported Python versions
+
+- Package runtime baseline: Python 3.12 or newer
+- Maintainer validation target: Python 3.12, 3.13, and 3.14
+- Main day-to-day development: usually the newest supported Python version
+
+## Development workflow
+
+On macOS and Linux, the normal workflow is:
+
+1. Run `./run_setup_build_environment.py` once after cloning or when the
+   build environment needs to be recreated.
+2. Run `./run_build.py` for the normal build-and-test cycle.
+3. Run `./run_clean_build.py` before review or release work that needs a
+   completely fresh build.
+
+The helper scripts are:
+
+- `run_setup_build_environment.py`
+  Create or refresh the build environment.
+- `run_build.py`
+  Build the package and run the configured checks in the project virtual
+  environment.
+- `run_clean.py`
+  Remove files generated by the build system.
+- `run_clean_build.py`
+  Perform a clean build from scratch. This is especially useful because some
+  duplicate-code diagnostics only appear on a clean build.
+- `run_pypi_build.py`
+  Create the distribution artifacts intended for PyPI publishing.
+
+The standard verification suite includes pytest, pylint, flake8, and mypy.
+After a build, the generated reports can be browsed through
+`reports/index.html`.
+
+## Test summary
+
+- Test result: 380 passed in 14s
+- No flake8 warnings.
+- No mypy errors found.
+- No python layout warnings.
+- Built version(s): 0.1
+- Build and test using Python 3.14.4

tableio_cfg_json-0.1/README_pypi.md

@@ -0,0 +1,192 @@
+# tableio-cfg-json
+
+`tableio-cfg-json` stores
+[TableIO](https://pypi.org/project/tableio/) configuration as validated JSON
+by using [config-as-json](https://pypi.org/project/config-as-json/).
+
+Use it when an application uses TableIO for table-like files and wants
+persistent, user-editable configuration for formats, implementations and
+format-specific options. The configuration objects are both TableIO
+`ConfigData` objects and config-as-json `Config` objects, so the same object
+can be written as configuration file (as JSON), read back later, validated,
+and passed to TableIO.
+
+## Is this package for you?
+
+This package is a good fit when one or more of these apply:
+
+- Your application uses TableIO.
+- You already use config-as-json, or can accept using it for persistent
+  configuration.
+- You want one configuration file to describe one TableIO input or output
+  endpoint.
+- You want to nest one or more TableIO endpoint configurations inside a
+  larger application configuration file.
+- You want validation and generated user documentation for the TableIO
+  options that are relevant to your application's capabilities.
+
+This package is probably not the right one when:
+
+- You are looking for the table reader or writer itself. Use
+  [TableIO](https://pypi.org/project/tableio/) directly.
+- Your program always uses one hard-coded table format and has no persistent
+  configuration.
+- You do not want to use config-as-json for configuration files.
+
+## Installation
+
+`tableio-cfg-json` requires Python 3.12 or newer.
+
+```sh
+pip install --upgrade tableio-cfg-json
+```
+
+## Quick start
+
+Create a compact JSON configuration file for one TableIO endpoint:
+
+```python
+from pathlib import Path
+import sys
+
+from tableio import FileAccess, access_capabilities
+from tableio_cfg_json import tio_json_config_default
+
+config_file = Path('tableio.cfg')
+file_access = FileAccess.CREATE
+capabilities = access_capabilities(file_access, error_file=sys.stderr)
+config = tio_json_config_default(capabilities=capabilities,
+                                 file_access=file_access,
+                                 format_name='CSV')
+config.write(to_json_filename=config_file)
+```
+
+For CSV this writes a small file like:
+
+```json
+{
+    "format_name": "CSV"
+}
+```
+
+Read the configuration back and use it with TableIO:
+
+```python
+from pathlib import Path
+import sys
+
+from tableio import FileAccess, access_capabilities, tio_config_create
+from tableio_cfg_json import TioJsonConfig
+
+config_file = Path('tableio.cfg')
+table_file = Path('capitals.csv')
+file_access = FileAccess.CREATE
+capabilities = access_capabilities(file_access, error_file=sys.stderr)
+config = TioJsonConfig(capabilities=capabilities,
+                       file_access=file_access,
+                       from_json_filename=config_file)
+with tio_config_create(config=config, file_name=table_file,
+                       file_access=file_access,
+                       capabilities=capabilities) as table_io:
+    table_io.write_table_listdata([
+        ['Capital', 'Country'],
+        ['Copenhagen', 'Denmark']
+    ])
+```
+
+If `implementation` is omitted, TableIO chooses a matching implementation at
+runtime. If the user wants to lock down a specific implementation, it can be
+stored explicitly in JSON.
+
+Optional settings can be added at the top level or in format-specific nested
+sections such as `csv`, `html` and `latex`. Compact output omits unset
+optional values, while template-style output can include all current default
+options.
+
+Please see the [teaching examples](https://bitbucket.org/tom-bjorkholm/tableio_cfg_json/src/master/example/src/example/README.md) for a more
+thorough introduction.
+
+## Main entry points
+
+- `TioJsonConfig`
+  Complete JSON-backed TableIO configuration for one endpoint. It can read
+  JSON, write JSON and be passed to TableIO as normal configuration data.
+
+- `tio_config_create()` create a TableIO object from a `TioJsonConfig`
+  object.
+
+### Helpers and details
+
+- `tio_json_config_default()`
+  Create a validated default `TioJsonConfig` using TableIO's recommended
+  choices for the requested capabilities and file access.
+
+- `TioJsonCsvConfig`, `TioJsonHtmlConfig`, `TioJsonLatexConfig`
+  Optional nested configuration sections for format-specific settings.
+
+- `describe_config()`, `describe_config_members()`,
+  `describe_config_reference()`, `describe_config_example()`,
+  `get_config_member_names()` and `get_general_cfg_info()`
+  Helpers for generating plain text syntax guides for configuration files.
+
+- `tio_json_config_wizard()`
+  Interactive helper for creating one TableIO endpoint configuration through
+  a user interface bridge.
+
+- `WizardUiBridge` and `WizardUiBridgeConsole`
+  Interfaces for connecting the wizard to a console, GUI or scripted UI.
+
+## Validation model
+
+The configuration file (in JSON) stores durable TableIO choices such
+as `format_name`, `implementation`, character encoding, presentation
+options and format-specific settings. Runtime values such as the actual
+file name are not stored in this configuration.
+
+Validation happens in two layers:
+
+- config-as-json validates JSON structure, member names and member value
+  types.
+- TableIO validates whether the selected format, implementation,
+  capabilities and file access can work together.
+
+Choice values are matched case-insensitively where TableIO defines a finite
+set of choices. For example, configuration file may use `excel` and the
+config object will store TableIO's normal `Excel` spelling after validation.
+
+## Nested application configs
+
+`TioJsonConfig` can be used as the whole configuration file for a small
+program, or as a nested member inside a larger config-as-json application
+configuration. This is useful when one application has several TableIO
+endpoints, for example one input table and two independently configured
+output tables.
+
+For larger configs, create each nested `TioJsonConfig` with the capabilities
+and file access for that endpoint. A read endpoint and a create endpoint may
+need different defaults and may validate different implementations.
+
+The teaching examples show both styles.
+
+## Documentation
+
+- Teaching examples and walkthroughs: [example/src/example/README.md](https://bitbucket.org/tom-bjorkholm/tableio_cfg_json/src/master/example/src/example/README.md)
+
+- Public API notes: [doc/api.md](https://bitbucket.org/tom-bjorkholm/tableio_cfg_json/src/master/doc/api.md)
+
+- Protected/internal API notes: [doc/protected_api.md](https://bitbucket.org/tom-bjorkholm/tableio_cfg_json/src/master/doc/protected_api.md)
+
+- Source repository: [tableio_cfg_json](https://bitbucket.org/tom-bjorkholm/tableio_cfg_json/)
+
+## License
+
+MIT
+
+## Test summary
+
+- Test result: 380 passed in 14s
+- No flake8 warnings.
+- No mypy errors found.
+- No python layout warnings.
+- Built version(s): 0.1
+- Build and test using Python 3.14.4

tableio_cfg_json-0.1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tableio-cfg-json"
+version = "0.1"
+authors = [
+  { name="Tom Björkholm", email="klausuler_linnet0q@icloud.com" },
+]
+description = "config-as-json configuration encapsulation for tableio."
+readme = "README_pypi.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent"
+]
+dynamic = ["dependencies"]
+
+[project.urls]
+"Source code" = "https://bitbucket.org/tom-bjorkholm/tableio_cfg_json"
+

tableio_cfg_json-0.1/setup.cfg

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

tableio_cfg_json-0.1/setup.py

@@ -0,0 +1,19 @@
+#! /usr/local/bin/python3
+"""Setup file specifying build of .whl."""
+
+from setuptools import setup  # type: ignore[import-untyped]
+
+setup(
+  name='tableio-cfg-json', version='0.1',
+  description='config-as-json configuration encapsulation for tableio.',
+  author='Tom Björkholm', author_email='klausuler_linnet0q@icloud.com',
+  python_requires='>=3.12', packages=['tableio_cfg_json'],
+  package_dir={'tableio_cfg_json': 'src/tableio_cfg_json'},
+  package_data={'tableio_cfg_json': ['py.typed']},
+  install_requires=[
+    'setuptools >= 82.0.1',
+    'build >= 1.4.2',
+    'wheel >= 0.46.3',
+    'tableio >= 0.9',
+    'config-as-json >= 0.9',
+  ])

tableio_cfg_json-0.1/src/tableio_cfg_json/__init__.py

@@ -0,0 +1,21 @@
+#! /usr/local/bin/python3
+"""Public API for the tableio config-as-json bridge."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+
+from tableio_cfg_json.config import TioJsonConfig, TioJsonCsvConfig, \
+    TioJsonHtmlConfig, TioJsonLatexConfig, tio_json_config_default
+from tableio_cfg_json.describe import describe_config, \
+    describe_config_example, describe_config_members, \
+    describe_config_reference, get_config_member_names, get_general_cfg_info
+from tableio_cfg_json.wizard import WizardUiBridge, WizardUiBridgeConsole, \
+    tio_json_config_wizard
+
+__all__ = ['TioJsonConfig', 'TioJsonCsvConfig', 'TioJsonHtmlConfig',
+           'TioJsonLatexConfig', 'describe_config',
+           'describe_config_example', 'describe_config_members',
+           'describe_config_reference', 'get_config_member_names',
+           'get_general_cfg_info', 'tio_json_config_default',
+           'tio_json_config_wizard', 'WizardUiBridge',
+           'WizardUiBridgeConsole']