jvmioutils

tuprolog.jvmioutils

Bridging Python streams and JVM ones.

2P-Kt reads and writes through JVM streams (java.io.InputStream and java.io.OutputStream, for bytes) and through JVM readers and writers (java.io.Reader and java.io.Writer, for text). This module converts Python streams into JVM ones, and vice versa:

• ensure_input_stream, ensure_reader, ensure_output_stream and ensure_writer turn paths, Python streams (e.g. open(...), sys.stdin, io.StringIO, io.BytesIO) and JVM streams into the JVM stream, reader or writer wanted; text is encoded and decoded as UTF-8;
• Python binary streams are accepted wherever JVM code expects an InputStream or an OutputStream, and Python text streams wherever it expects a Reader or a Writer;
• JVM input streams are Python io.IOBases: they can be read line by line, iterated over, and closed, as Python text streams.

Examples:

>>> import io
>>> stream = ensure_input_stream(io.BytesIO(b"first\nsecond\n"))
>>> stream.readline()
'first\n'
>>> list(stream)
['second\n']
>>> output = io.StringIO()
>>> writer = ensure_writer(output)
>>> writer.write("hello")
>>> writer.flush()
>>> output.getvalue()
'hello'

See Also

tuprolog.jvmutils, for the other conversions between Python and the JVM.

InputStream module-attribute

InputStream = _jio.InputStream

Java's stream of input bytes, java.io.InputStream.

Instances are Python io.IOBases, readable line by line as text (UTF-8), and iterable over their lines.

Reader module-attribute

Reader = _jio.Reader

Java's stream of input characters, java.io.Reader (see ensure_reader).

InputStreamReader module-attribute

InputStreamReader = _jio.InputStreamReader

Java's java.io.InputStreamReader: a Reader decoding the bytes of an InputStream.

BufferedReader module-attribute

BufferedReader = _jio.BufferedReader

Java's java.io.BufferedReader: a Reader buffering another one.

Files module-attribute

Files = _jnio_file.Files

Java's java.nio.file.Files utility class, operating on files (see open_file).

Paths module-attribute

Paths = _jnio_file.Paths

Java's java.nio.file.Paths utility class, creating file paths (e.g. Paths.get("kb.pl")).

OutputStream module-attribute

OutputStream = _jio.OutputStream

Java's stream of output bytes, java.io.OutputStream (see ensure_output_stream).

Writer module-attribute

Writer = _jio.Writer

Java's stream of output characters, java.io.Writer (see ensure_writer).

Channels module-attribute

Channels = _jnio_channels.Channels

Java's java.nio.channels.Channels utility class, adapting byte channels into streams, readers and writers.

PythonByteChannel

PythonByteChannel(stream: IOBase)

A JVM byte channel reading from, or writing to, a Python stream.

Text streams are encoded and decoded as UTF-8, binary ones are passed through. Closing the channel leaves the stream open, as the stream belongs to its Python owner. Text streams are read line by line, so that interactive streams (e.g. sys.stdin) give their input as soon as a line is entered.

Parameters:

Name	Type	Description	Default
stream	IOBase	The Python stream to read from, or to write to.	required

Examples:

>>> import io
>>> PythonByteChannel(io.BytesIO(b"bytes")).isOpen()
True

read

read(buffer) -> int

Reads bytes from the stream into a JVM java.nio.ByteBuffer.

Returns:

Type	Description
int	The number of bytes read, 0 if a non-blocking stream has no data yet, or -1 at the
int	end of the stream.

write

write(buffer) -> int

Writes the bytes remaining in a JVM java.nio.ByteBuffer to the stream.

Returns:

Type	Description
int	The number of bytes written.

isOpen

isOpen()

Whether the channel was not closed.

close

close()

Closes the channel, leaving the stream open.

open_file

open_file(path: str) -> InputStream

Opens a file for reading, as a JVM input stream.

Parameters:

Name	Type	Description	Default
path	str	The path of the file.	required

Returns:

Type	Description
InputStream	The input stream, to be closed by the caller.

Raises:

Type	Description
NoSuchFileException	If the file does not exist.

ensure_input_stream

ensure_input_stream(
    input: str | PathLike | IOBase | InputStream,
) -> InputStream

Turns a path, a Python stream, or a JVM input stream into a JVM input stream.

Parameters:

Name	Type	Description	Default
input	str | PathLike | IOBase | InputStream	A path (a string or a path-like object) of a file to open, a Python stream (text streams are encoded as UTF-8), or a JVM input stream, returned as it is. Strings are always paths, never the text to read.	required

Returns:

Type	Description
InputStream	The JVM input stream.

Raises:

Type	Description
TypeError	If input is none of the above.

Examples:

>>> import io
>>> ensure_input_stream(io.StringIO("text")).readline()
'text'

ensure_reader

ensure_reader(
    input: str | PathLike | IOBase | InputStream | Reader,
) -> Reader

Turns a path, a Python stream, or a JVM input stream or reader into a JVM reader.

Parameters:

Name	Type	Description	Default
input	str | PathLike | IOBase | InputStream | Reader	A JVM reader, returned as it is, a Python stream, or anything ensure_input_stream accepts. Bytes are decoded as UTF-8.	required

Returns:

Type	Description
Reader	The JVM reader.

Raises:

Type	Description
TypeError	If input is none of the above.

Examples:

>>> import io
>>> chr(ensure_reader(io.StringIO("hi")).read())
'h'

ensure_output_stream

ensure_output_stream(
    output: IOBase | OutputStream,
) -> OutputStream

Turns a Python stream, or a JVM output stream, into a JVM output stream.

Parameters:

Name	Type	Description	Default
output	IOBase | OutputStream	A Python stream (text streams receive the bytes decoded as UTF-8), or a JVM output stream, returned as it is.	required

Returns:

Type	Description
OutputStream	The JVM output stream.

Raises:

Type	Description
TypeError	If output is none of the above.

Examples:

>>> import io
>>> buffer = io.BytesIO()
>>> ensure_output_stream(buffer).write(65)
>>> buffer.getvalue()
b'A'

ensure_writer

ensure_writer(
    output: IOBase | OutputStream | Writer,
) -> Writer

Turns a Python stream, or a JVM output stream or writer, into a JVM writer.

The writer buffers what it is given: flush it to reach the stream.

Parameters:

Name	Type	Description	Default
output	IOBase | OutputStream | Writer	A JVM writer, returned as it is, a JVM output stream, or a Python stream. Text is encoded as UTF-8.	required

Returns:

Type	Description
Writer	The JVM writer.

Raises:

Type	Description
TypeError	If output is none of the above.