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()
(align_latex, graphics, supplemental_plot, text)
sage: prefs.text is None
True
sage: prefs.text = 'ascii_art'
sage: prefs.text
'ascii_art'
sage: prefs
Display preferences:
* align_latex is not specified
* graphics is not specified
* supplemental_plot is not specified
* text = ascii_art

>>> from sage.all import *
>>> from sage.repl.rich_output.preferences import DisplayPreferences
>>> prefs = DisplayPreferences()
>>> prefs.available_options()
(align_latex, graphics, supplemental_plot, text)
>>> prefs.text is None
True
>>> prefs.text = 'ascii_art'
>>> prefs.text
'ascii_art'
>>> prefs
Display preferences:
* align_latex is not specified
* 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

>>> from sage.all import *
>>> prefs.text = 'ascii_art'
>>> del prefs.text
>>> prefs.text is None
True

>>> prefs.text = 'ascii_art'
>>> prefs.text = None
>>> 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

>>> from sage.all import *
>>> import pydoc
>>> doc = pydoc.render_doc(prefs)
>>> assert ' graphics' in doc
>>> assert '     Preferred graphics format' in doc
>>> assert ' text' in doc
>>> 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:
* align_latex is not specified
* graphics is not specified
* supplemental_plot is not specified
* text = latex

>>> from sage.all import *
>>> DisplayPreferences(text='latex')
Display preferences:
* align_latex is not specified
* 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)[source]#

Bases: PreferencesABC

property align_latex[source]#

Preferred mode of latex displays

Allowed values:

  • None (default): no preference

  • ‘center’

  • ‘left’

property graphics[source]#

Preferred graphics format

Allowed values:

  • None (default): no preference

  • ‘disable’

  • ‘vector’

  • ‘raster’

property supplemental_plot[source]#

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’

property text[source]#

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)[source]#

Bases: 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:
* align_latex is not specified
* graphics = raster
* supplemental_plot is not specified
* text is not specified

>>> from sage.all import *
>>> from sage.repl.rich_output.preferences import DisplayPreferences
>>> p1 = DisplayPreferences(graphics='vector')
>>> p2 = DisplayPreferences(graphics='raster')
>>> DisplayPreferences(p1, p2)
Display preferences:
* align_latex is not specified
* 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:
* align_latex is not specified
* graphics = vector
* supplemental_plot is not specified
* text is not specified

>>> from sage.all import *
>>> DisplayPreferences(p2, p1)
Display preferences:
* align_latex is not specified
* graphics = vector
* supplemental_plot is not specified
* text is not specified

Further keywords override:

sage: DisplayPreferences(p2, p1, graphics='disable')
Display preferences:
* align_latex is not specified
* graphics = disable
* supplemental_plot is not specified
* text is not specified

>>> from sage.all import *
>>> DisplayPreferences(p2, p1, graphics='disable')
Display preferences:
* align_latex is not specified
* graphics = disable
* supplemental_plot is not specified
* text is not specified
available_options()[source]#

Return the available options

OUTPUT:

Tuple of the preference items as instances of Property.

EXAMPLES:

sage: from sage.repl.rich_output.preferences import DisplayPreferences
sage: DisplayPreferences().available_options()
(align_latex, graphics, supplemental_plot, text)

>>> from sage.all import *
>>> from sage.repl.rich_output.preferences import DisplayPreferences
>>> DisplayPreferences().available_options()
(align_latex, graphics, supplemental_plot, text)
class sage.repl.rich_output.preferences.Property(name, allowed_values, doc=None)[source]#

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)

>>> from sage.all import *
>>> from sage.repl.rich_output.preferences import Property
>>> prop = Property('foo', [Integer(0), Integer(1), Integer(2)], 'The Foo Property')
>>> prop.__doc__
'The Foo Property\n\nAllowed values:\n\n* ``None`` (default): no preference\n\n* 0\n\n* 1\n\n* 2'
>>> prop.allowed_values
(0, 1, 2)
deleter(prefs)[source]#

Delete the current value of the property

INPUT:

  • prefs – the PreferencesABC 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

>>> from sage.all import *
>>> from sage.repl.rich_output.preferences import Property, PreferencesABC
>>> prop = Property('foo', [Integer(0), Integer(1), Integer(2)], 'The Foo Property')
>>> prefs = PreferencesABC()
>>> prop.getter(prefs) is None
True
>>> prop.setter(prefs, Integer(1))
>>> prop.deleter(prefs)
>>> prop.getter(prefs) is None
True
getter(prefs)[source]#

Get the current value of the property

INPUT:

  • prefs – the PreferencesABC 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

>>> from sage.all import *
>>> from sage.repl.rich_output.preferences import Property, PreferencesABC
>>> prop = Property('foo', [Integer(0), Integer(1), Integer(2)], 'The Foo Property')
>>> prefs = PreferencesABC()
>>> prop.getter(prefs) is None
True
>>> prop.setter(prefs, Integer(1))
>>> prop.getter(prefs)
1
setter(prefs, value)[source]#

Get the current value of the property

INPUT:

  • prefs – the PreferencesABC instance that the property is bound to.

  • value – anything. The new value of the property. Setting a property to None is equivalent to deleting the value.

OUTPUT:

This method does not return anything. A ValueError is raised if the given value 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

>>> from sage.all import *
>>> from sage.repl.rich_output.preferences import Property, PreferencesABC
>>> prop = Property('foo', [Integer(0), Integer(1), Integer(2)], 'The Foo Property')
>>> prefs = PreferencesABC()
>>> prop.getter(prefs) is None
True
>>> prop.setter(prefs, Integer(1))
>>> prop.getter(prefs)
1

>>> prop.setter(prefs, None)
>>> prop.getter(prefs) is None
True