Metadata-Version: 2.1
Name: linesep
Version: 0.4.0
Summary: Handling lines with arbitrary separators
Home-page: https://github.com/jwodder/linesep
Author: John Thorvald Wodder II
Author-email: linesep@varonathe.org
License: MIT
Project-URL: Source Code, https://github.com/jwodder/linesep
Project-URL: Bug Tracker, https://github.com/jwodder/linesep/issues
Project-URL: Documentation, https://linesep.readthedocs.io
Keywords: delimiters,line break,line-ending,linebreak,newline,paragraphs,separator
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: ~=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE

.. image:: http://www.repostatus.org/badges/latest/active.svg
    :target: http://www.repostatus.org/#active
    :alt: Project Status: Active — The project has reached a stable, usable
          state and is being actively developed.

.. image:: https://github.com/jwodder/linesep/workflows/Test/badge.svg?branch=master
    :target: https://github.com/jwodder/linesep/actions?workflow=Test
    :alt: CI Status

.. image:: https://codecov.io/gh/jwodder/linesep/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/jwodder/linesep

.. image:: https://img.shields.io/pypi/pyversions/linesep.svg
    :target: https://pypi.org/project/linesep

.. image:: https://img.shields.io/github/license/jwodder/linesep.svg
    :target: https://opensource.org/licenses/MIT
    :alt: MIT License

`GitHub <https://github.com/jwodder/linesep>`_
| `PyPI <https://pypi.org/project/linesep>`_
| `Documentation <https://linesep.readthedocs.io>`_
| `Issues <https://github.com/jwodder/linesep/issues>`_
| `Changelog <https://github.com/jwodder/linesep/blob/master/CHANGELOG.md>`_

``linesep`` provides basic functions & classes for reading, writing, splitting,
& joining text with custom separators that can occur either before, between, or
after the segments they separate.

Installation
============
``linesep`` requires Python 3.7 or higher.  Just use `pip
<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install::

    python3 -m pip install linesep


Examples
========

Reading sections separated by a "``---``" line:

.. code:: python

    with open('text.txt') as fp:
        for entry in linesep.read_separated(fp, '\n---\n'):
            ...

Parsing output from ``find -print0``:

.. code:: python

    find = subprocess.Popen(
        ['find', '/', '-some', '-complicated', '-condition', '-print0'],
        stdout=subprocess.PIPE,
    )
    for filepath in linesep.read_terminated(find.stdout, '\0'):
        ...

A poor man's `JSON Text Sequence <https://tools.ietf.org/html/rfc7464>`_ parser:

.. code:: python

    for entry in linesep.read_preceded(fp, '\x1E'):
        try:
            obj = json.loads(entry)
        except ValueError:
            pass
        else:
            yield obj

Read from a text file one paragraph at a time:

.. code:: python

    with open("my-novel.txt") as fp:
        for paragraph in linesep.read_paragraphs(fp):
            ...

Split input from an ``anyio.TextReceiveStream`` on newlines:

.. code:: python

    async with anyio.TextReceiveStream( ... ) as stream:
        splitter = linesep.UnicodeNewlineSplitter()
        async for line in splitter.aitersplit(stream):
            print(line)
