passagemath-repl 10.5.1__py3-none-any.whl

sage/repl/rich_output/output_video.py

@@ -0,0 +1,231 @@
+# sage_setup: distribution = sagemath-repl
+r"""
+Video Output Types
+
+This module defines the rich output types for video formats.
+"""
+# ****************************************************************************
+#       Copyright (C) 2015 Martin von Gagern <Martin.vGagern@gmx.net>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+import importlib.resources
+
+from sage.repl.rich_output.output_basic import OutputBase
+from sage.repl.rich_output.buffer import OutputBuffer
+
+
+class OutputVideoBase(OutputBase):
+
+    def __init__(self, video, loop=True):
+        """
+        Abstract base class for rich video output.
+
+        INPUT:
+
+        - ``video`` -- :class:`~sage.repl.rich_output.buffer.OutputBuffer`;
+          the video data
+        - ``loop`` -- boolean; whether to repeat the video in an endless loop
+
+        EXAMPLES::
+
+            sage: from sage.repl.rich_output.output_catalog import OutputVideoOgg
+            sage: OutputVideoOgg.example()  # indirect doctest
+            OutputVideoOgg container
+        """
+        assert isinstance(video, OutputBuffer)
+        self.video = video
+        self.loop = loop
+
+    @classmethod
+    def example(cls):
+        r"""
+        Construct a sample video output container.
+
+        This static method is meant for doctests, so they can easily
+        construct an example.  The method is implemented in the abstract
+        :class:`OutputVideoBase` class, but should get invoked on a
+        concrete subclass for which an actual example can exist.
+
+        OUTPUT: an instance of the class on which this method is called
+
+        EXAMPLES::
+
+            sage: from sage.repl.rich_output.output_catalog import OutputVideoOgg
+            sage: OutputVideoOgg.example()
+            OutputVideoOgg container
+            sage: OutputVideoOgg.example().video
+            buffer containing 5612 bytes
+            sage: OutputVideoOgg.example().ext
+            '.ogv'
+            sage: OutputVideoOgg.example().mimetype
+            'video/ogg'
+        """
+        with importlib.resources.path(__package__, 'example' + cls.ext) as filename:
+            return cls(OutputBuffer.from_file(filename),
+                       {'controls': True, 'loop': False})
+
+    def html_fragment(self, url, link_attrs=''):
+        r"""
+        Construct a HTML fragment for embedding this video.
+
+        INPUT:
+
+        - ``url`` -- string; the URL where the data of this video can be found
+
+        - ``link_attrs`` -- string; can be used to style the fallback link
+          which is presented to the user if the video is not supported
+
+        EXAMPLES::
+
+            sage: from sage.repl.rich_output.output_catalog import OutputVideoOgg
+            sage: print(OutputVideoOgg.example().html_fragment
+            ....:       ('foo', 'class="bar"').replace('><','>\n<'))
+            <video autoplay="autoplay" controls="controls" loop="loop">
+            <source src="foo" type="video/ogg" />
+            <p>
+            <a target="_new" href="foo" class="bar">Download video/ogg video</a>
+            </p>
+            </video>
+        """
+        attrs = {
+            'autoplay': 'autoplay',
+            'controls': 'controls',
+        }
+        if self.loop:
+            attrs['loop'] = 'loop'
+        attrs = ''.join(' {}="{}"'.format(k, v)
+                        for k, v in sorted(attrs.items()))
+        txt = ('<video{attrs}>'
+               '<source src="{url}" type="{mimetype}" /><p>'
+               '<a target="_new" href="{url}" {link_attrs}>'
+               'Download {mimetype} video</a></p></video>')
+        return txt.format(url=url,
+                          mimetype=self.mimetype,
+                          attrs=attrs,
+                          link_attrs=link_attrs)
+
+
+class OutputVideoOgg(OutputVideoBase):
+    """
+    Ogg video, Ogg Theora in particular.
+
+    EXAMPLES::
+
+        sage: from sage.repl.rich_output.output_catalog import OutputVideoOgg
+        sage: OutputVideoOgg.example()
+        OutputVideoOgg container
+    """
+
+    ext = ".ogv"
+    mimetype = "video/ogg"
+
+
+class OutputVideoWebM(OutputVideoBase):
+    """
+    WebM video.
+
+    The video can be encoded using VP8, VP9 or an even more recent codec.
+
+    EXAMPLES::
+
+        sage: from sage.repl.rich_output.output_catalog import OutputVideoWebM
+        sage: OutputVideoWebM.example()
+        OutputVideoWebM container
+    """
+
+    ext = ".webm"
+    mimetype = "video/webm"
+
+
+class OutputVideoMp4(OutputVideoBase):
+    """
+    MPEG 4 video.
+
+    EXAMPLES::
+
+        sage: from sage.repl.rich_output.output_catalog import OutputVideoMp4
+        sage: OutputVideoMp4.example()
+        OutputVideoMp4 container
+    """
+
+    ext = ".mp4"
+    mimetype = "video/mp4"
+
+
+class OutputVideoFlash(OutputVideoBase):
+    """
+    Flash video.
+
+    EXAMPLES::
+
+        sage: from sage.repl.rich_output.output_catalog import OutputVideoFlash
+        sage: OutputVideoFlash.example()
+        OutputVideoFlash container
+    """
+
+    ext = ".flv"
+    mimetype = "video/x-flv"
+
+
+class OutputVideoMatroska(OutputVideoBase):
+    """
+    Matroska Video.
+
+    EXAMPLES::
+
+        sage: from sage.repl.rich_output.output_catalog import OutputVideoMatroska
+        sage: OutputVideoMatroska.example()
+        OutputVideoMatroska container
+    """
+
+    ext = ".mkv"
+    mimetype = "video/x-matroska"
+
+
+class OutputVideoAvi(OutputVideoBase):
+    """
+    AVI video.
+
+    EXAMPLES::
+
+        sage: from sage.repl.rich_output.output_catalog import OutputVideoAvi
+        sage: OutputVideoAvi.example()
+        OutputVideoAvi container
+    """
+
+    ext = ".avi"
+    mimetype = "video/x-msvideo"
+
+
+class OutputVideoWmv(OutputVideoBase):
+    """
+    Windows Media Video.
+
+    EXAMPLES::
+
+        sage: from sage.repl.rich_output.output_catalog import OutputVideoWmv
+        sage: OutputVideoWmv.example()
+        OutputVideoWmv container
+    """
+
+    ext = ".wmv"
+    mimetype = "video/x-ms-wmv"
+
+
+class OutputVideoQuicktime(OutputVideoBase):
+    """
+    Quicktime video.
+
+    EXAMPLES::
+
+        sage: from sage.repl.rich_output.output_catalog import OutputVideoQuicktime
+        sage: OutputVideoQuicktime.example()
+        OutputVideoQuicktime container
+    """
+
+    ext = ".mov"
+    mimetype = "video/quicktime"

sage/repl/rich_output/preferences.py

@@ -0,0 +1,432 @@
+# sage_setup: distribution = sagemath-repl
+r"""
+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
+
+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:
+    * 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.
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2015 Volker Braun <vbraun.name@gmail.com>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  as published by the Free Software Foundation; either version 2 of
+#  the License, or (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
+
+from textwrap import dedent
+
+from sage.structure.sage_object import SageObject
+
+
+class Property(property):
+
+    def __init__(self, name, allowed_values, doc=None):
+        r"""
+        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)
+        """
+        self.name = name
+        self.underscore_name = '_{0}'.format(name)
+        self.allowed_values = tuple(allowed_values)
+        self.__doc__ = doc = self._make_doc(doc)
+        super().__init__(fget=self.getter, fset=self.setter,
+                         fdel=self.deleter, doc=doc)
+
+    def _make_doc(self, doc):
+        """
+        Generate the documentation.
+
+        INPUT:
+
+        - ``doc`` -- the title line of the documentation
+
+        OUTPUT:
+
+        string; the docstring with auto-generated documentation about
+        the allowed values added
+
+        EXAMPLES::
+
+            sage: from sage.repl.rich_output.preferences import Property
+            sage: prop = Property('foo', [0, 1, 2], 'The Foo Property')
+            sage: print(prop._make_doc('this is the title'))
+            this is the title
+            <BLANKLINE>
+            Allowed values:
+            <BLANKLINE>
+            * ``None`` (default): no preference
+            <BLANKLINE>
+            * 0
+            <BLANKLINE>
+            * 1
+            <BLANKLINE>
+            * 2
+        """
+        doc = dedent(doc)
+        doc += '\n\n'
+        doc += 'Allowed values:\n\n'
+        values_doc = ['* ``None`` (default): no preference']
+        values_doc.extend('* {0}'.format(repr(value))
+                          for value in self.allowed_values)
+        return doc + '\n\n'.join(values_doc)
+
+    def __repr__(self):
+        """
+        Return a string representation.
+
+        OUTPUT: string
+
+        EXAMPLES::
+
+            sage: from sage.repl.rich_output.preferences import Property
+            sage: prop = Property('foo', [0, 1, 2], 'The Foo Property')
+            sage: prop.__repr__()
+            'foo'
+        """
+        return self.name
+
+    def getter(self, prefs):
+        """
+        Get the current value of the property.
+
+        INPUT:
+
+        - ``prefs`` -- the :class:`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
+        """
+        try:
+            return getattr(prefs, self.underscore_name)
+        except AttributeError:
+            return None
+
+    def setter(self, prefs, value):
+        """
+        Get the current value of the property.
+
+        INPUT:
+
+        - ``prefs`` -- the :class:`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 :exc:`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
+        """
+        if value is None:
+            return self.deleter(prefs)
+        allowed = self.allowed_values
+        if value not in allowed:
+            raise ValueError('value must be unset (None) or one of {0}, got {1}'
+                             .format(allowed, value))
+        setattr(prefs, self.underscore_name, value)
+
+    def deleter(self, prefs):
+        """
+        Delete the current value of the property.
+
+        INPUT:
+
+        - ``prefs`` -- the :class:`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
+        """
+        underscore_name = self.underscore_name
+        try:
+            delattr(prefs, underscore_name)
+        except AttributeError:
+            pass
+
+
+class PreferencesABC(SageObject):
+
+    def __init__(self, *args, **kwds):
+        """
+        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
+
+        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
+
+        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
+        """
+        for parent in args:
+            for option in self.available_options():
+                value = option.getter(parent)
+                if value is not None:
+                    option.setter(self, value)
+        for key, value in kwds.items():
+            setattr(self, key, value)
+
+    @classmethod
+    def _add_option(cls, name, values, doc):
+        """
+        Add an option to the preferences system.
+
+        This method should only be called during the import of
+        :mod:`sage.repl.rich_output.preferences`.
+
+        INPUT:
+
+        - ``name`` -- the name of the option
+
+        - ``values`` -- the allowed values
+
+        - ``doc`` -- docstring
+
+        EXAMPLES::
+
+            sage: from sage.repl.rich_output.preferences import PreferencesABC
+            sage: class MyPrefs(PreferencesABC):
+            ....:     pass
+            sage: MyPrefs._add_option('foo', [0, 1, 2], 'The Foo Option')
+            sage: prefs = MyPrefs()
+            sage: prefs.foo
+            sage: prefs.foo = 0
+            sage: prefs.foo
+            0
+        """
+        prop = Property(name, values, doc)
+        setattr(cls, name, prop)
+
+    def available_options(self):
+        """
+        Return the available options.
+
+        OUTPUT:
+
+        tuple of the preference items as instances of :class:`Property`
+
+        EXAMPLES::
+
+            sage: from sage.repl.rich_output.preferences import DisplayPreferences
+            sage: DisplayPreferences().available_options()
+            (align_latex, graphics, supplemental_plot, text)
+        """
+        options = []
+        for value in self.__class__.__dict__.values():
+            if isinstance(value, Property):
+                options.append(value)
+        return tuple(sorted(options, key=str))
+
+    def _repr_(self):
+        r"""
+        Return a string representation.
+
+        OUTPUT: string
+
+        EXAMPLES::
+
+            sage: from sage.repl.rich_output.preferences import DisplayPreferences
+            sage: DisplayPreferences()._repr_()
+            'Display preferences:\n* align_latex is not specified\n* graphics is not specified\n* supplemental_plot is not specified\n* text is not specified'
+        """
+        s = ['Display preferences:']
+        for opt in self.available_options():
+            value = opt.getter(self)
+            if value is None:
+                s += ['* {0} is not specified'.format(opt.name)]
+            else:
+                s += ['* {0} = {1}'.format(opt.name, value)]
+        return '\n'.join(s)
+
+
+class DisplayPreferences(PreferencesABC):
+    pass
+
+
+DisplayPreferences._add_option(
+    'text',
+    ('plain', 'ascii_art', 'unicode_art', 'latex'),
+    """
+    Which textual representation is preferred
+    """
+)
+
+
+DisplayPreferences._add_option(
+    'align_latex',
+    ('center', 'left'),
+    """
+    Preferred mode of latex displays
+    """
+)
+
+
+DisplayPreferences._add_option(
+    'graphics',
+    ('disable', 'vector', 'raster'),
+    """
+    Preferred graphics format
+    """
+)
+
+
+DisplayPreferences._add_option(
+    'supplemental_plot',
+    ('always', 'never'),
+    """
+    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.
+    """
+)