Package org.python.modules._io

Class PyIOBase

  • All Implemented Interfaces:
    java.io.Serializable, FinalizableBuiltin, Traverseproc
    Direct Known Subclasses:
    PyIOBaseDerived, PyRawIOBase
    public class PyIOBase
extends PyObject
implements FinalizableBuiltin, Traverseproc
    The Python module _io._IOBase, on which the io module depends directly.

    Implementation note: The code is based heavily on the Jython 2.6-ish _fileio.PyFileIO, the purely Java-accessible IOBase (both Philip Jenvey's work), and the Python implementation in Lib/_pyio. We do not simply delegate to the implementation in org.python.core.io because of the need to override parts of the implementation in Python subclasses. A call to close(), for example, is required to call flush(), but if delegated to the pure Java implementation would not call the version of flush() overridden in a Python sub-class of _io._IOBase. Equally, the use made by PyRawIOBase.read(int) of readinto(bytearray) would not pick up the version of readinto defined in Python.

    See Also:
    Serialized Form

    • Method Detail

      • fastGetDict

        public PyStringMap fastGetDict()
        Description copied from class: PyObject
        xxx implements where meaningful
        Overrides:
        fastGetDict in class PyObject
        Returns:
        internal object per instance dict or null

      • seek

        public long seek​(long pos,
                 int whence)
        Position the read or write pointer at a given byte offset pos relative to a position indicated by whence.
        • If whence=0, the position will be set to pos bytes.
        • If whence=1 the position will be set to the current position plus pos.
        • If whence=2 the position will be set to the stream size plus pos (and usually pos<=0).
        Parameters:
        pos - relative to the specified point
        whence - 0=from start, 1=from here, 2=from end
        Returns:
        the new current position

      • seek

        public final long seek​(long pos)
        Position the read or write pointer at a given byte offset pos relative to the start.
        Parameters:
        pos - relative to the start
        Returns:
        the new current position

      • tell

        public long tell()
        Get the current stream position.
        Returns:
        stream position

      • truncate

        public long truncate​(long size)
        Truncate file to size bytes.
        Parameters:
        size - requested for stream
        Returns:
        the new size

      • truncate

        public long truncate()
        Truncate file to size bytes to the current position (as reported by tell()).
        Returns:
        the new size

      • flush

        public void flush()
        Flush write buffers, or no-op for read-only and non-blocking streams. Irrespective of the concrete type of the i/o object, locally-buffered write data is written downstream. Whether the downstream in object is also flushed depends upon the specific type of this object.

      • closed_readonly

        public final void closed_readonly​(boolean value)

      • close

        public void close()
        Close the stream. If closed already, this is a no-op.

      • seekable

        public boolean seekable()
                 throws PyException
        Is the stream capable of positioning the read/write pointer?
        Returns:
        True if may be positioned
        Throws:
        PyException(ValueError) - if the object is closed to client operations
        PyException

      • _checkSeekable

        public void _checkSeekable​(java.lang.String msg)
        Raise an error if the pointer of underlying IO stream is not capable of being positioned.
        Parameters:
        msg - optional custom message
        Throws:
        PyException(ValueError) - if the object is closed to client operations
        PyException(IOError) - if the stream is not capable of being positioned.

      • _checkSeekable

        public final void _checkSeekable()
        Raise an error if the pointer of underlying IO stream is not capable of being positioned.
        Throws:
        PyException(ValueError) - if the object is closed to client operations
        PyException(IOError) - if the stream is not capable of being positioned.

      • readable

        public boolean readable()
                 throws PyException
        Is the stream readable?
        Returns:
        true if readable
        Throws:
        PyException(ValueError) - if the object is closed to client operations
        PyException

      • _checkReadable

        public void _checkReadable​(java.lang.String msg)
        Raise an error if the underlying IO stream is not readable.
        Parameters:
        msg - optional custom message
        Throws:
        PyException(ValueError) - if the object is closed to client operations
        PyException(IOError) - if the stream is not readable.

      • _checkReadable

        public final void _checkReadable()
        Raise an error if the underlying IO stream is not readable.
        Throws:
        PyException(ValueError) - if the object is closed to client operations
        PyException(IOError) - if the stream is not readable.

      • writable

        public boolean writable()
                 throws PyException
        Is the stream writable?
        Returns:
        true if writable
        Throws:
        PyException(ValueError) - if the object is closed to client operations
        PyException

      • _checkWritable

        public void _checkWritable​(java.lang.String msg)
                    throws PyException
        Raise an error if the underlying IO stream is not writable.
        Parameters:
        msg - optional custom message
        Throws:
        PyException(ValueError) - if the object is closed to client operations
        PyException(IOError) - if the stream is not writable.
        PyException

      • _checkWritable

        public final void _checkWritable()
                          throws PyException
        Raise an error if the underlying IO stream is not writable.
        Throws:
        PyException(ValueError) - if the object is closed to client operations
        PyException(IOError) - if the stream is not writable.
        PyException

      • closed

        public final boolean closed()
        Is the stream closed against further client operations?
        Returns:
        true if closed

      • _checkClosed

        public void _checkClosed​(java.lang.String msg)
                  throws PyException
        Raise an error if the underlying IO stream is closed. (Note opposite sense from _checkSeekable(java.lang.String), etc..
        Parameters:
        msg - optional custom message
        Throws:
        PyException(ValueError) - if the object is closed to client operations
        PyException

      • __enter__

        public PyObject __enter__()
        Called at the start of a context-managed suite (supporting the with clause).
        Returns:
        this object

      • __exit__

        public boolean __exit__​(PyObject type,
                        PyObject value,
                        PyObject traceback)
        Called at the end of a context-managed suite (supporting the with clause), and will normally close the stream.
        Returns:
        false

      • fileno

        public PyObject fileno()
        Return a file descriptor for the stream. A CPython file descriptor is an int, but this is not the natural choice in Jython, since Java has no such convention of using integers. File descriptors should be passed around opaquely, so their actual type is irrelevant, as long as (say) _jyio.open(PyObject[], String[]) accepts the type that RawIOBase.fileno() returns.
        Returns:
        a file descriptor (as opaque object)

      • isatty

        public boolean isatty()
        Is the stream known to be an interactive console? This relies on the ability of the underlying stream to know, which is not always possible.
        Returns:
        true if a console: false if not or we can't tell

      • readline

        public PyObject readline​(int limit)
        Return one line of text (bytes terminates by '\n'), or the specified number of bytes, or the whole stream, whichever is shortest.
        Parameters:
        limit - maximum number of bytes (<0 means no limit)
        Returns:
        the line (or fragment)

      • readline

        public PyObject readline()
        Return one line of text (bytes terminates by '\n'), or the whole stream, whichever is shorter.
        Returns:
        the line (or fragment)

      • __iter__

        public PyObject __iter__()
        Return an iterator on which next may be repeatedly called to produce (usually) lines from this stream or file.
        Overrides:
        __iter__ in class PyObject

      • __iternext__

        public PyObject __iternext__()
        Description copied from class: PyObject
        Return the next element of the sequence that this is an iterator for. Returns null when the end of the sequence is reached.
        Overrides:
        __iternext__ in class PyObject

      • next

        public PyObject next()
              throws PyException
        May be called repeatedly to produce (usually) lines from this stream or file.
        Returns:
        next line from the stream or file
        Throws:
        PyException(StopIteration) - when iteration has reached a natural conclusion
        PyException(ValueError) - if the file or stream is closed
        PyException(IOError) - reflecting an I/O error in during the read
        PyException

      • readlines

        public PyObject readlines​(PyObject hint)
        Read a stream as a sequence of lines.
        Parameters:
        hint - stop reading lines after this many bytes (if not EOF first)
        Returns:
        list containing the lines read

      • writelines

        public void writelines​(PyObject lines)
        Write an iterable sequence of strings to the stream.
        Parameters:
        lines -