BufferProtocol (Jython API documentation)
Date: 2024-08-18

org.python.core

## Interface BufferProtocol

- All Known Subinterfaces:
    PyBuffer
  All Known Implementing Classes:
    Base1DBuffer, BaseArrayBuffer, BaseBuffer, BaseNIOBuffer, Py2kBuffer, PyArray, PyArrayDerived, PyByteArray, PyByteArrayDerived, PyMemoryView, PyShadowString, PyShadowStringDerived, PyString, PyStringDerived, PyUnicode, PyUnicodeDerived, SimpleBuffer, SimpleNIOBuffer, SimpleStringBuffer, SimpleWritableBuffer, Strided1DBuffer, Strided1DNIOBuffer, Strided1DWritableBuffer, SyspathArchive, ZeroByteBuffer

      public interface BufferProtocol

  Interface marking an object as capable of exposing its internal state as a `PyBuffer`.

  A few objects implement `BufferProtocol` (e.g. by inheritance) but cannot actually provide their value as a `PyBuffer`. These should throw `ClassCastException`, permitting the idiom:

           try (PyBuffer buf = ((BufferProtocol) obj).getBuffer(PyBUF.SIMPLE)) {
               ... // Do something with buf
           } catch (ClassCastException e) {
               ... // expected bytes object or buffer not obj.getType()
           }

  The `catch` is executed identically whether the cause is the explicit cast of `obj` or `getBuffer`, and the try-with-resources releases the buffer if one was obtained.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `PyBuffer` | `getBuffer(int flags)` Method by which the consumer requests the buffer from the exporter.

- - ### Method Detail

    - #### getBuffer

          PyBuffer getBuffer(int flags)
                      throws PyException,
                             java.lang.ClassCastException

      Method by which the consumer requests the buffer from the exporter. The consumer provides information on its ability to understand buffer navigation. Each consumer requesting a buffer in this way, when it has finished using it, should make a corresponding call to `PyBuffer.release()` on the buffer it obtained, or `PyBuffer.close()` using try-with-resources, since some objects alter their behaviour while buffers are exported.
      Parameters:
        `flags` - specifying features demanded and the navigational capabilities of the consumer
      Returns:
        exported buffer
      Throws:
        `PyException` - `BufferError` when expectations do not correspond with the buffer
        `java.lang.ClassCastException` - when the object only formally implements `BufferProtocol`

Jython homepage