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, 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
* text = ascii_art

Properties can be unset by deleting them or by assinging 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
* 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

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
* text is not specified

If specified in the opposite order, the setting from p1 is inherited:

sage: DisplayPreferences(p2, p1)
Display preferences:
* graphics = vector
* text is not specified

Further keywords override:

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

graphics

Preferred graphics format

Allowed values:

• None (default): no preference
• ‘disable’
• ‘vector’
• ‘raster’

text

Which textual representation is preferred

Allowed values:

• None (default): no preference
• ‘plain’
• ‘ascii_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
* text is not specified

If specified in the opposite order, the setting from p1 is inherited:

sage: DisplayPreferences(p2, p1)
Display preferences:
* graphics = vector
* text is not specified

Further keywords override:

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

available_options()

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()
(graphics, text)

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

getter(prefs)

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

setter(prefs, value)

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