PyIOBase (Jython API documentation)
Date: 2022-09-10

org.python.modules._io

## Class PyIOBase

- java.lang.Object
- - org.python.core.PyObject
  - - org.python.modules._io.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

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.python.core.PyObject

      `PyObject.ConversionException`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `close_doc`
    `static java.lang.String` | `closed_doc`
    `static java.lang.String` | `fileno_doc`
    `static java.lang.String` | `flush_doc`
    `static java.lang.String` | `isatty_doc`
    `static java.lang.String` | `readable_doc`
    `static java.lang.String` | `readline_doc`
    `static java.lang.String` | `readlines_doc`
    `static java.lang.String` | `seek_doc`
    `static java.lang.String` | `seekable_doc`
    `static java.lang.String` | `tell_doc`
    `static java.lang.String` | `truncate_doc`
    `static PyType` | `TYPE`
    `static java.lang.String` | `writable_doc`
    `static java.lang.String` | `writelines_doc`

    - ### Fields inherited from class org.python.core.PyObject

      `gcMonitorGlobal`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `__del_builtin__()` `FinalizableBuiltin.__del_builtin__()` is the built-in's own finalizer, while `FinalizablePyObjectDerived.__del_derived__()` refers to an instance's in-dict `__del__`.
    `PyObject` | `__enter__()` Called at the start of a context-managed suite (supporting the `with` clause).
    `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.
    `PyObject` | `__iter__()` Return an iterator on which `next` may be repeatedly called to produce (usually) lines from this stream or file.
    `PyObject` | `__iternext__()` Return the next element of the sequence that this is an iterator for.
    `void` | `_checkClosed()`
    `void` | `_checkClosed(java.lang.String msg)` Raise an error if the underlying IO stream is closed.
    `void` | `_checkReadable()` Raise an error if the underlying IO stream is not readable.
    `void` | `_checkReadable(java.lang.String msg)` Raise an error if the underlying IO stream is not readable.
    `void` | `_checkSeekable()` Raise an error if the pointer of underlying IO stream is not capable of being positioned.
    `void` | `_checkSeekable(java.lang.String msg)` Raise an error if the pointer of underlying IO stream is not capable of being positioned.
    `void` | `_checkWritable()` Raise an error if the underlying IO stream is not writable.
    `void` | `_checkWritable(java.lang.String msg)` Raise an error if the underlying IO stream is not writable.
    `void` | `close()` Close the stream.
    `void` | `closed_readonly(boolean value)`
    `boolean` | `closed()` Is the stream closed against further client operations?
    `PyStringMap` | `fastGetDict()` xxx implements where meaningful
    `PyObject` | `fileno()` Return a file descriptor for the stream.
    `void` | `flush()` Flush write buffers, or no-op for read-only and non-blocking streams.
    `boolean` | `isatty()` Is the stream known to be an interactive console?
    `PyObject` | `next()` May be called repeatedly to produce (usually) lines from this stream or file.
    `boolean` | `readable()` Is the stream readable?
    `PyObject` | `readline()` Return one line of text (bytes terminates by `'\n'`), or the whole stream, whichever is shorter.
    `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.
    `PyObject` | `readlines(PyObject hint)` Read a stream as a sequence of lines.
    `boolean` | `refersDirectlyTo(PyObject ob)` Optional operation.
    `long` | `seek(long pos)` Position the read or write pointer at a given byte offset `pos` relative to the start.
    `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`.
    `boolean` | `seekable()` Is the stream capable of positioning the read/write pointer?
    `long` | `tell()` Get the current stream position.
    `int` | `traverse(Visitproc visit, java.lang.Object arg)` Traverses all directly contained `PyObject`s.
    `long` | `truncate()` Truncate file to `size` bytes to the current position (as reported by `tell()`).
    `long` | `truncate(long size)` Truncate file to `size` bytes.
    `boolean` | `writable()` Is the stream writable?
    `void` | `writelines(PyObject lines)` Write an iterable sequence of strings to the stream.

    - ### Methods inherited from class org.python.core.PyObject

      `__abs__, __add__, __and__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __cmp__, __coerce__, __coerce_ex__, __complex__, __contains__, __delattr__, __delattr__, __delete__, __delitem__, __delitem__, __delslice__, __delslice__, __dir__, __div__, __divmod__, __ensure_finalizer__, __eq__, __findattr__, __findattr__, __findattr_ex__, __finditem__, __finditem__, __finditem__, __float__, __floordiv__, __format__, __ge__, __get__, __getattr__, __getattr__, __getitem__, __getitem__, __getnewargs__, __getslice__, __getslice__, __gt__, __hash__, __hex__, __iadd__, __iand__, __idiv__, __idivmod__, __ifloordiv__, __ilshift__, __imod__, __imul__, __index__, __int__, __invert__, __ior__, __ipow__, __irshift__, __isub__, __itruediv__, __ixor__, __le__, __len__, __long__, __lshift__, __lt__, __mod__, __mul__, __ne__, __neg__, __nonzero__, __not__, __oct__, __or__, __pos__, __pow__, __pow__, __radd__, __rand__, __rdiv__, __rdivmod__, __reduce__, __reduce_ex__, __reduce_ex__, __repr__, __rfloordiv__, __rlshift__, __rmod__, __rmul__, __ror__, __rpow__, __rrshift__, __rshift__, __rsub__, __rtruediv__, __rxor__, __set__, __setattr__, __setattr__, __setitem__, __setitem__, __setitem__, __setslice__, __setslice__, __str__, __sub__, __tojava__, __truediv__, __trunc__, __unicode__, __xor__, _add, _and, _callextra, _cmp, _div, _divmod, _doget, _doget, _doset, _eq, _floordiv, _ge, _gt, _iadd, _iand, _idiv, _idivmod, _ifloordiv, _ilshift, _imod, _imul, _in, _ior, _ipow, _irshift, _is, _isnot, _isub, _itruediv, _ixor, _jcall, _jcallexc, _jthrow, _le, _lshift, _lt, _mod, _mul, _ne, _notin, _or, _pow, _rshift, _sub, _truediv, _xor, asDouble, asIndex, asIndex, asInt, asInt, asIterable, asLong, asLong, asName, asName, asString, asString, asStringOrNull, asStringOrNull, bit_length, conjugate, delDict, delType, dispatch__init__, equals, fastGetClass, getDict, getType, hashCode, implementsDescrDelete, implementsDescrGet, implementsDescrSet, invoke, invoke, invoke, invoke, invoke, invoke, isCallable, isDataDescr, isIndex, isInteger, isMappingType, isNumberType, isSequenceType, noAttributeError, object___subclasshook__, readonlyAttributeError, setDict, setType, toString`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### TYPE

          public static final PyType TYPE

    - #### seek_doc

          public static final java.lang.String seek_doc

      See Also:
        Constant Field Values

    - #### tell_doc

          public static final java.lang.String tell_doc

      See Also:
        Constant Field Values

    - #### truncate_doc

          public static final java.lang.String truncate_doc

      See Also:
        Constant Field Values

    - #### flush_doc

          public static final java.lang.String flush_doc

      See Also:
        Constant Field Values

    - #### close_doc

          public static final java.lang.String close_doc

      See Also:
        Constant Field Values

    - #### closed_doc

          public static final java.lang.String closed_doc

      See Also:
        Constant Field Values

    - #### seekable_doc

          public static final java.lang.String seekable_doc

      See Also:
        Constant Field Values

    - #### readable_doc

          public static final java.lang.String readable_doc

      See Also:
        Constant Field Values

    - #### writable_doc

          public static final java.lang.String writable_doc

      See Also:
        Constant Field Values

    - #### fileno_doc

          public static final java.lang.String fileno_doc

      See Also:
        Constant Field Values

    - #### isatty_doc

          public static final java.lang.String isatty_doc

      See Also:
        Constant Field Values

    - #### readline_doc

          public static final java.lang.String readline_doc

      See Also:
        Constant Field Values

    - #### readlines_doc

          public static final java.lang.String readlines_doc

      See Also:
        Constant Field Values

    - #### writelines_doc

          public static final java.lang.String writelines_doc

      See Also:
        Constant Field Values

  - ### 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

    - #### _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

    - #### _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

    - #### _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.

    - #### _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.

    - #### 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

    - #### _checkClosed

          public final void _checkClosed()
                                  throws PyException

      Throws:
        `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

    - #### 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` -

    - #### __del_builtin__

          public void __del_builtin__()

      Description copied from interface: `FinalizableBuiltin`
      `FinalizableBuiltin.__del_builtin__()` is the built-in's own finalizer, while `FinalizablePyObjectDerived.__del_derived__()` refers to an instance's in-dict `__del__`. A FinalizeTrigger calls `FinalizablePyObjectDerived.__del_derived__()` first and - if existent - `FinalizableBuiltin.__del_builtin__()` after that. A plain `FinalizablePyObject.__del__()` would behave as overridden by `FinalizablePyObjectDerived.__del_derived__()`, i.e. won't be called if the type implements `FinalizablePyObjectDerived`, while `FinalizableBuiltin.__del_builtin__()` is called in any case.
      Specified by:
        `__del_builtin__` in interface `FinalizableBuiltin`

    - #### traverse

          public int traverse(Visitproc visit,
                              java.lang.Object arg)

      Description copied from interface: `Traverseproc`
      Traverses all directly contained `PyObject`s. Like in CPython, `arg` must be passed unmodified to `visit` as its second parameter. If `Visitproc.visit(PyObject, Object)` returns nonzero, this return value must be returned immediately by traverse. `Visitproc.visit(PyObject, Object)` must not be called with a `null` PyObject-argument.
      Specified by:
        `traverse` in interface `Traverseproc`

    - #### refersDirectlyTo

          public boolean refersDirectlyTo(PyObject ob)

      Description copied from interface: `Traverseproc`
      Optional operation. Should only be implemented if it is more efficient than calling `Traverseproc.traverse(Visitproc, Object)` with a visitproc that just watches out for `ob`. Must return `false` if `ob` is `null`.
      Specified by:
        `refersDirectlyTo` in interface `Traverseproc`

Jython homepage