linear-tsv

library1.1.0pypypi✓ verified 84d ago

Linear TSV is a Python library providing a simple, line-oriented, and portable tabular data format. Unlike standard CSV, it uses escape codes for newlines and tabs within field data, enabling robust processing with line-oriented shell tools. The format aligns with the TEXT serialization mode of Postgres and MySQL, making it ideal for reliable data exchange. It is currently at version 1.1.0 and maintains an active release cadence.

serialization data

pip install linear-tsv

github ↗package ↗

INSTALL

IMPORT

SIG · LINEAR-TSV

linear-tsv

serializationpythonv1.1.0

Install

2.4s avg

Import

12ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.012s · 19.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.4s · import 0.012s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ from tsv import un

✗ import tsv

reader

✓ from tsv import reader

✗ import tsv

DictReader

✓ from tsv import DictReader

✗ import tsv

This quickstart demonstrates how to parse a `linear-tsv` formatted string using the `tsv.un()` function. It shows how to handle embedded newlines and tabs using their defined escape sequences (`\n`, `\t`) and also the `\N` representation for `NULL` values. The `tsv.un()` function returns a generator of lists of strings.

import tsv import io # Example TSV data string with escaped newline and tab data_string = "col1\tcol2\nval1a\\nwithnewline\tval1b\\twithtab\nval2a\t\\N" # Use io.StringIO to simulate a file stream data_stream = io.StringIO(data_string) # Parse the TSV stream to a generator of lists of strings parsed_data = list(tsv.un(data_stream)) # Print the parsed data for row in parsed_data: print(row) # Output: # ['col1', 'col2'] # ['val1a\nwithnewline', 'val1b\twithtab'] # ['val2a', '\N']

Debug

Known issues

gotchaThe `linear-tsv` library implements a specific TSV format where newlines (\n), tabs (\t), carriage returns (\r), and backslashes (\\) within field data *must* be escaped. Generic TSV parsers (e.g., `csv.reader` with `delimiter='\t'`) will not correctly interpret these escape sequences, leading to data corruption or incorrect parsing.

fix

Always use `linear-tsv.tsv.un()` for parsing files adhering to the linear-tsv format. If using other parsers, ensure they are configured to handle these specific escape sequences (e.g., `quoting=csv.QUOTE_NONE` in pandas and custom escape handling).

affects: All versions

gotchaThe `linear-tsv` format does not natively include or interpret header rows. The `tsv.un()` function treats all lines as data rows.

fix

If your TSV file includes a header, you must manually separate the first row after parsing to use as column names. For example, `header = parsed_data[0]` and `data_rows = parsed_data[1:]`.

affects: All versions

gotchaThe format uses `\N` (backslash followed by capital N) to represent `NULL` values, akin to PostgreSQL/MySQL TEXT format. The `tsv.un()` function returns `\N` as a literal string.

fix

Post-process the parsed data to convert `"\\N"` strings to `None` or your desired representation for null values. Example: `[None if x == '\\N' else x for x in row]`.

affects: All versions

Upgrade

Version history

1.1.0latest on PyPI · released Jan 20, 2018

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/solidsnack/tsv ↗

packagehttps://pypi.org/project/linear-tsv/ ↗