Display Preferences¶
This class is used to express display preferences that are not simply
a choice of a particular output format. For example, whether to prefer
vector over raster graphics. By convention, the value None
is
always a valid value for a preference and means no particular
preference.
EXAMPLES:
sage: from sage.repl.rich_output.preferences import DisplayPreferences
sage: prefs = DisplayPreferences()
sage: prefs.available_options()
(graphics, supplemental_plot, text)
sage: prefs.text is None
True
sage: prefs.text = 'ascii_art'
sage: prefs.text
'ascii_art'
sage: prefs
Display preferences:
* graphics is not specified
* supplemental_plot is not specified
* text = ascii_art
Properties can be unset by deleting them or by assigning None
:
sage: prefs.text = 'ascii_art'
sage: del prefs.text
sage: prefs.text is None
True
sage: prefs.text = 'ascii_art'
sage: prefs.text = None
sage: prefs.text is None
True
Properties have documentation attached:
sage: import pydoc
sage: doc = pydoc.render_doc(prefs)
sage: assert ' graphics' in doc
sage: assert ' Preferred graphics format' in doc
sage: assert ' text' in doc
sage: assert ' Which textual representation is preferred' in doc
Values can also be specified as keyword arguments to the constructor:
sage: DisplayPreferences(text='latex')
Display preferences:
* graphics is not specified
* supplemental_plot is not specified
* text = latex
Todo
A value-checking preference system should be used elsewhere in Sage, too. The class here is just a simple implementation, a proper implementation would use a metaclass to construct the preference items.
-
class
sage.repl.rich_output.preferences.
DisplayPreferences
(*args, **kwds)¶ Bases:
sage.repl.rich_output.preferences.PreferencesABC
-
graphics
¶ Preferred graphics format
Allowed values:
None
(default): no preference‘disable’
‘vector’
‘raster’
-
supplemental_plot
¶ Whether to graphically display graphs and other graph-like objects that implement rich output. When not specified small objects are show graphically and large objects as textual overview.
Allowed values:
None
(default): no preference‘always’
‘never’
-
text
¶ Which textual representation is preferred
Allowed values:
None
(default): no preference‘plain’
‘ascii_art’
‘unicode_art’
‘latex’
-
-
class
sage.repl.rich_output.preferences.
PreferencesABC
(*args, **kwds)¶ Bases:
sage.structure.sage_object.SageObject
Preferences for displaying graphics
These can be preferences expressed by the user or by the display backend. They are specified as keyword arguments.
INPUT:
*args*
– positional arguments are preferences instances. The property values will be inherited from left to right, that is, later parents override values from earlier parents.**kwds
– keyword arguments. Will be used to initialize properties, and override inherited values if necessary.
EXAMPLES:
sage: from sage.repl.rich_output.preferences import DisplayPreferences sage: p1 = DisplayPreferences(graphics='vector') sage: p2 = DisplayPreferences(graphics='raster') sage: DisplayPreferences(p1, p2) Display preferences: * graphics = raster * supplemental_plot is not specified * text is not specified
If specified in the opposite order, the setting from
p1
is inherited:sage: DisplayPreferences(p2, p1) Display preferences: * graphics = vector * supplemental_plot is not specified * text is not specified
Further keywords override:
sage: DisplayPreferences(p2, p1, graphics='disable') Display preferences: * graphics = disable * supplemental_plot is not specified * text is not specified
-
class
sage.repl.rich_output.preferences.
Property
(name, allowed_values, doc=None)¶ Bases:
property
Preference item
INPUT:
name
– string. The name of the property.allowed_values
– list/tuple/iterable of allowed values.doc
– string (optional). The docstring of the property.
EXAMPLES:
sage: from sage.repl.rich_output.preferences import Property sage: prop = Property('foo', [0, 1, 2], 'The Foo Property') sage: prop.__doc__ 'The Foo Property\n\nAllowed values:\n\n* ``None`` (default): no preference\n\n* 0\n\n* 1\n\n* 2' sage: prop.allowed_values (0, 1, 2)
-
deleter
(prefs)¶ Delete the current value of the property
INPUT:
prefs
– thePreferencesABC
instance that the property is bound to.
EXAMPLES:
sage: from sage.repl.rich_output.preferences import Property, PreferencesABC sage: prop = Property('foo', [0, 1, 2], 'The Foo Property') sage: prefs = PreferencesABC() sage: prop.getter(prefs) is None True sage: prop.setter(prefs, 1) sage: prop.deleter(prefs) sage: prop.getter(prefs) is None True
-
getter
(prefs)¶ Get the current value of the property
INPUT:
prefs
– thePreferencesABC
instance that the property is bound to.
OUTPUT:
One of the allowed values or
None
if not set.EXAMPLES:
sage: from sage.repl.rich_output.preferences import Property, PreferencesABC sage: prop = Property('foo', [0, 1, 2], 'The Foo Property') sage: prefs = PreferencesABC() sage: prop.getter(prefs) is None True sage: prop.setter(prefs, 1) sage: prop.getter(prefs) 1
-
setter
(prefs, value)¶ Get the current value of the property
INPUT:
prefs
– thePreferencesABC
instance that the property is bound to.value
– anything. The new value of the property. Setting a property toNone
is equivalent to deleting the value.
OUTPUT:
This method does not return anything. A
ValueError
is raised if the givenvalue
is not one of the allowed values.EXAMPLES:
sage: from sage.repl.rich_output.preferences import Property, PreferencesABC sage: prop = Property('foo', [0, 1, 2], 'The Foo Property') sage: prefs = PreferencesABC() sage: prop.getter(prefs) is None True sage: prop.setter(prefs, 1) sage: prop.getter(prefs) 1 sage: prop.setter(prefs, None) sage: prop.getter(prefs) is None True