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