Output Buffer#
This is the fundamental unit of rich output, a single immutable buffer (either in-memory or as a file). Rich output always consists of one or more buffers. Ideally, the Sage library always uses the buffer object as an in-memory buffer. But you can also ask it for a filename, and it will save the data to a file if necessary. Either way, the buffer object presents the same interface for getting the content of an in-memory buffer or a temporary file. So any rich output backends do not need to know where the buffer content is actually stored.
EXAMPLES:
sage: from sage.repl.rich_output.buffer import OutputBuffer
sage: buf = OutputBuffer('this is the buffer content'); buf
buffer containing 26 bytes
sage: buf.get().decode('ascii')
'this is the buffer content'
sage: type(buf.get()) is bytes
True
>>> from sage.all import *
>>> from sage.repl.rich_output.buffer import OutputBuffer
>>> buf = OutputBuffer('this is the buffer content'); buf
buffer containing 26 bytes
>>> buf.get().decode('ascii')
'this is the buffer content'
>>> type(buf.get()) is bytes
True
- class sage.repl.rich_output.buffer.OutputBuffer(data)[source]#
Bases:
SageObject
Data stored either in memory or as a file
This class is an abstraction for “files”, in that they can either be defined by a bytes array (Python 3) or string (Python 2) or by a file (see
from_file()
).INPUT:
data
– bytes. The data that is stored in the buffer.
EXAMPLES:
sage: from sage.repl.rich_output.buffer import OutputBuffer sage: buf = OutputBuffer('this is the buffer content'); buf buffer containing 26 bytes sage: buf2 = OutputBuffer(buf); buf2 buffer containing 26 bytes sage: buf.get_str() 'this is the buffer content' sage: buf.filename(ext='.txt') '/....txt'
>>> from sage.all import * >>> from sage.repl.rich_output.buffer import OutputBuffer >>> buf = OutputBuffer('this is the buffer content'); buf buffer containing 26 bytes >>> buf2 = OutputBuffer(buf); buf2 buffer containing 26 bytes >>> buf.get_str() 'this is the buffer content' >>> buf.filename(ext='.txt') '/....txt'
- filename(ext=None)[source]#
Return the filename.
INPUT:
ext
– string. The file extension.
OUTPUT:
Name of a file, most likely a temporary file. If
ext
is specified, the filename will have that extension.You must not modify the returned file. Its permissions are set to readonly to help with that.
EXAMPLES:
sage: from sage.repl.rich_output.buffer import OutputBuffer sage: buf = OutputBuffer('test') sage: buf.filename() # random output '/home/user/.sage/temp/hostname/26085/tmp_RNSfAc' sage: os.path.isfile(buf.filename()) True sage: buf.filename(ext='txt') # random output '/home/user/.sage/temp/hostname/26085/tmp_Rjjp4V.txt' sage: buf.filename(ext='txt').endswith('.txt') True
>>> from sage.all import * >>> from sage.repl.rich_output.buffer import OutputBuffer >>> buf = OutputBuffer('test') >>> buf.filename() # random output '/home/user/.sage/temp/hostname/26085/tmp_RNSfAc' >>> os.path.isfile(buf.filename()) True >>> buf.filename(ext='txt') # random output '/home/user/.sage/temp/hostname/26085/tmp_Rjjp4V.txt' >>> buf.filename(ext='txt').endswith('.txt') True
- classmethod from_file(filename)[source]#
Construct buffer from data in file.
Warning
The buffer assumes that the file content remains the same during the lifetime of the Sage session. To communicate this to the user, the file permissions will be changed to read only.
INPUT:
filename
– string. The filename under which the data is stored.
OUTPUT:
String containing the buffer data.
EXAMPLES:
sage: from sage.repl.rich_output.buffer import OutputBuffer sage: name = sage.misc.temporary_file.tmp_filename() sage: with open(name, 'wb') as f: ....: _ = f.write(b'file content') sage: buf = OutputBuffer.from_file(name); buf buffer containing 12 bytes sage: buf.filename() == name True sage: buf.get_str() 'file content'
>>> from sage.all import * >>> from sage.repl.rich_output.buffer import OutputBuffer >>> name = sage.misc.temporary_file.tmp_filename() >>> with open(name, 'wb') as f: ... _ = f.write(b'file content') >>> buf = OutputBuffer.from_file(name); buf buffer containing 12 bytes >>> buf.filename() == name True >>> buf.get_str() 'file content'
- get()[source]#
Return the buffer content
OUTPUT:
Bytes. A string in Python 2.x.
EXAMPLES:
sage: from sage.repl.rich_output.buffer import OutputBuffer sage: c = OutputBuffer('test1234').get(); c.decode('ascii') 'test1234' sage: type(c) is bytes True sage: c = OutputBuffer('été').get() sage: type(c) is bytes True
>>> from sage.all import * >>> from sage.repl.rich_output.buffer import OutputBuffer >>> c = OutputBuffer('test1234').get(); c.decode('ascii') 'test1234' >>> type(c) is bytes True >>> c = OutputBuffer('été').get() >>> type(c) is bytes True
- get_str()[source]#
Return the buffer content as a
str
object for the current Python version.That is, returns a Python 2-style encoding-agnostic
str
on Python 2, and returns a unicodestr
on Python 3 with the buffer content decoded from UTF-8. In other words, this is equivalent toOutputBuffer.get
on Python 2 andOutputBuffer.get_unicode
on Python 3. This is useful in some cases for cross-compatible code.OUTPUT:
A
str
object.EXAMPLES:
sage: from sage.repl.rich_output.buffer import OutputBuffer sage: c = OutputBuffer('test1234').get_str(); c 'test1234' sage: type(c) is str True sage: c = OutputBuffer('été').get_str() sage: type(c) is str True
>>> from sage.all import * >>> from sage.repl.rich_output.buffer import OutputBuffer >>> c = OutputBuffer('test1234').get_str(); c 'test1234' >>> type(c) is str True >>> c = OutputBuffer('été').get_str() >>> type(c) is str True
- get_unicode()[source]#
Return the buffer content as string
OUTPUT:
String. Unicode in Python 2.x. Raises a
UnicodeEncodeError
if the data is not valid utf-8.EXAMPLES:
sage: from sage.repl.rich_output.buffer import OutputBuffer sage: OutputBuffer('test1234').get().decode('ascii') 'test1234' sage: OutputBuffer('test1234').get_unicode() 'test1234'
>>> from sage.all import * >>> from sage.repl.rich_output.buffer import OutputBuffer >>> OutputBuffer('test1234').get().decode('ascii') 'test1234' >>> OutputBuffer('test1234').get_unicode() 'test1234'
- save_as(filename)[source]#
Save a copy of the buffer content.
You may edit the returned file, unlike the file returned by
filename()
.INPUT:
filename
– string. The file name to save under.
EXAMPLES:
sage: from sage.repl.rich_output.buffer import OutputBuffer sage: buf = OutputBuffer('test') sage: buf.filename(ext='txt') # random output sage: tmp = tmp_dir() sage: filename = os.path.join(tmp, 'foo.txt') sage: buf.save_as(filename) sage: with open(filename, 'r') as f: ....: f.read() 'test'
>>> from sage.all import * >>> from sage.repl.rich_output.buffer import OutputBuffer >>> buf = OutputBuffer('test') >>> buf.filename(ext='txt') # random output >>> tmp = tmp_dir() >>> filename = os.path.join(tmp, 'foo.txt') >>> buf.save_as(filename) >>> with open(filename, 'r') as f: ... f.read() 'test'