interactive-figure 0.3.3__py3-none-any.whl → 0.3.4__py3-none-any.whl

interactive_figure/__about__.py

@@ -1 +1 @@
-__version__ = "0.3.3"
+__version__ = "0.3.4"

interactive_figure/interactive_figure.py

@@ -1,326 +1,312 @@
-"""
-This module provides functions to create and interact with a Matplotlib figure.
-
-The figure registers mouse presses, keyboard input and the location of the mouse
-after any input. The user has fine-grained control over when to wait for input
-and when to draw the contents of the figure.
-
-Source: https://github.com/teuncm/interactive-figure
-"""
-
-import matplotlib.pyplot as plt
-from types import SimpleNamespace
-
-
-def create(aspect_ratio="auto", hide_toolbar=False, **kwargs):
-    """Create the interactive figure.
-
-    Parameters
-    ----------
-    aspect_ratio : str, optional
-        aspect ratio of the Axes, by default "auto"
-    hide_toolbar : bool, optional
-        whether to hide the toolbar, by default False
-
-    remaining arguments will be sent to the figure upon creation
-
-    Raises
-    ------
-    RuntimeError
-        if multiple interactive figures are created.
-    """
-    if _state.fig is None:
-        if hide_toolbar:
-            plt.rcParams["toolbar"] = "None"
-
-        # Disable interactive mode for explicit control over drawing. See:
-        # https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.isinteractive.html#matplotlib.pyplot.isinteractive
-        plt.ioff()
-
-        _state.fig = fig = plt.figure(**kwargs)
-        fig.canvas.manager.set_window_title("Interactive Figure")
-        # Create drawable axis.
-        _state.ax = ax = plt.gca()
-        ax.set_aspect(aspect_ratio)
-
-        # Show figure but allow the main thread to continue.
-        plt.show(block=False)
-
-        # Reset plot state and draw to obtain focus.
-        clear()
-        draw()
-
-        # Add our custom event handlers. For handlers, see:
-        # https://matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.FigureCanvasBase.mpl_connect
-        # For general interaction handling, see:
-        # https://matplotlib.org/stable/users/explain/figure/interactive_guide.html
-        # For mouse buttons, see:
-        # https://matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.MouseButton
-        fig.canvas.mpl_disconnect(fig.canvas.manager.key_press_handler_id)
-        fig.canvas.mpl_disconnect(fig.canvas.manager.button_press_handler_id)
-        fig.canvas.mpl_connect("key_press_event", _key_press_handler)
-        fig.canvas.mpl_connect("button_press_event", _button_press_handler)
-
-        print("Successfully created the interactive figure.")
-    else:
-        raise RuntimeError("Error: you cannot create multiple interactive figures.")
-
-
-def toggle_fullscreen():
-    """Toggle fullscreen."""
-    _check_exists()
-
-    _state.figure.canvas.manager.full_screen_toggle()
-
-
-def clear(hide_labels=False, set_limits=True):
-    """Reset contents and layout of the figure. *set_limits* will set the Axes limits to 
-    [0, 100]. *hide_labels* will remove all labels."""
-    _check_exists()
-
-    ax = _state.ax
-    ax.clear()
-
-    if set_limits:
-        ax.set_xlim([0, 100])
-        ax.set_ylim([0, 100])
-
-    if hide_labels:
-        ax.set_xticks([])
-        ax.set_yticks([])
-
-
-def wait(timeout):
-    """Timeout for the given number of seconds. During this period it is
-    not possible to interact with the figure. For sub-second timeouts use
-    time.wait() instead.
-
-    Parameters
-    ----------
-    timeout : float
-        Number of seconds to wait for
-    """
-    _check_exists()
-
-    _state.fig.canvas.start_event_loop(timeout=timeout)
-    # No button was pressed, so reset the state.
-    _state_reset_press()
-
-
-def wait_for_interaction(timeout=-1):
-    """Wait for interaction with the interactive figure. Optionally
-    use a timeout in seconds.
-
-    Parameters
-    ----------
-    timeout : int, optional
-        Timeout in seconds when waiting for input.
-
-    Returns
-    -------
-    bool | None
-        - True if a key was pressed.
-        - False if a mouse button was pressed.
-        - None if no input was given within the timeout.
-    """
-    _check_exists()
-
-    # Reimplementation of:
-    # figure.Figure.waitforbuttonpress()
-    # _blocking_input.blocking_input_loop()
-    #     but without show() to prevent redrawing the figure.
-
-    # Contains the event that was registered.
-    event = None
-
-    # Handler to stop blocking event loop.
-    def simple_handler(ev):
-        nonlocal event
-        event = ev
-        _state.fig.canvas.stop_event_loop()
-
-    # Connect event handlers and save callback ids.
-    callback_ids = [
-        _state.fig.canvas.mpl_connect(name, simple_handler) for name in ["button_press_event", "key_press_event"]
-    ]
-    try:
-        # Start a blocking event loop.
-        _state.fig.canvas.start_event_loop(timeout=timeout)
-    finally:
-        # Disconnect handlers.
-        for callback_id in callback_ids:
-            _state.fig.canvas.mpl_disconnect(callback_id)
-
-    interaction_type = None if event is None else event.name == "key_press_event"
-
-    if interaction_type is None:
-        # No button was pressed, so reset the state.
-        _state_reset_press()
-
-    return interaction_type
-
-
-def draw():
-    """Draw the figure."""
-    _check_exists()
-
-    canvas = _state.fig.canvas
-    # Mark canvas for a draw.
-    canvas.draw_idle()
-    # Force update the GUI. This is when the drawing actually happens
-    # in the backend.
-    canvas.flush_events()
-
-
-def close():
-    """Close the figure."""
-    _check_exists()
-
-    plt.close(_state.fig)
-
-    _state_reset_fig()
-    _state_reset_press()
-
-    print("Successfully closed the interactive figure.")
-
-
-def gcf():
-    """Get figure object of interactive figure.
-
-    Returns
-    -------
-        Figure handler
-    """
-    return _state.fig
-
-
-def gca():
-    """Get Axes object of interactive figure.
-
-    Returns
-    -------
-        Axes handler
-    """
-    return _state.ax
-
-
-def get_last_key_press():
-    """Get the last keypress and convert it to lowercase.
-
-    Returns
-    -------
-    str | None
-        The last key that was pressed
-    """
-    key_string = _state.last_keypress
-
-    if key_string is None:
-        return None
-    else:
-        return key_string.lower()
-
-
-def get_last_mouse_press():
-    """Get the last mousepress and convert it to an integer value.
-
-    Returns
-    -------
-    int | None
-        The identifier of the last mouse button that was pressed
-    """
-    mouse_button = _state.last_mousepress
-
-    if mouse_button is None:
-        return None
-    else:
-        return mouse_button.value
-
-
-def get_last_mouse_pos():
-    """Get the last mouse position.
-
-    Returns
-    -------
-    (x: float, y: float) | (None, None)
-        The last registered mouse position after any interaction
-    """
-    return (_state.last_mouse_x, _state.last_mouse_y)
-
-
-# PRIVATE METHODS
-
-
-def _get_state():
-    """Get all state information of the interactive figure.
-
-    Returns
-    -------
-    SimpleNamespace
-        Namespace with figure state information
-    """
-    return _state
-
-
-def _check_exists():
-    """Check if the interactive figure exists.
-
-    Raises
-    ------
-    RuntimeError
-        If the figure is not available
-    """
-    if _state.fig is None:
-        raise RuntimeError("Error: the interactive figure is not available.")
-
-
-def _state_reset_fig():
-    """Reset figure information."""
-    _state.fig = None
-    _state.ax = None
-
-
-def _state_reset_press():
-    """Reset last registered press information."""
-    _state.last_keypress = None
-    _state.last_mousepress = None
-    _state.last_mouse_x = None
-    _state.last_mouse_y = None
-
-
-def _key_press_handler(event):
-    """Register key and mouse coordinates on press.
-
-    Parameters
-    ----------
-    event
-        The event object that was generated internally
-    """
-    _state.last_keypress = event.key
-    _state.last_mousepress = None
-    _state.last_mouse_x = event.xdata
-    _state.last_mouse_y = event.ydata
-
-
-def _button_press_handler(event):
-    """Register key, mouse button and mouse coordinates on press.
-
-    Parameters
-    ----------
-    event
-        The event object that was generated internally
-    """
-    _state.last_keypress = event.key
-    _state.last_mousepress = event.button
-    _state.last_mouse_x = event.xdata
-    _state.last_mouse_y = event.ydata
-
-
-# Namespace to track the internal state of the interactive figure.
-_state = SimpleNamespace(
-    fig=None,
-    ax=None,
-    last_keypress=None,
-    last_mousepress=None,
-    last_mouse_x=None,
-    last_mouse_y=None,
-)
+"""
+This module provides functions to create and interact with a Matplotlib figure. The figure registers mouse presses, keyboard input and the location of the mouse
+after any input.
+
+Source: https://github.com/teuncm/interactive-figure
+"""
+
+import matplotlib.pyplot as plt
+from types import SimpleNamespace
+
+
+def create(aspect_ratio="auto", hide_toolbar=False, **kwargs):
+    """Create the interactive figure.
+
+    Parameters
+    ----------
+    aspect_ratio : str, optional
+        aspect ratio of the Axes, by default "auto"
+    hide_toolbar : bool, optional
+        whether to hide the toolbar, by default False
+
+    remaining arguments will be sent to the figure upon creation
+
+    Raises
+    ------
+    RuntimeError
+        if multiple interactive figures are created.
+    """
+    if _state.fig is None:
+        if hide_toolbar:
+            plt.rcParams["toolbar"] = "None"
+
+        # Disable interactive mode for explicit control over drawing. See:
+        # https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.isinteractive.html#matplotlib.pyplot.isinteractive
+        plt.ioff()
+
+        _state.fig = fig = plt.figure(**kwargs)
+        fig.canvas.manager.set_window_title("Interactive Figure")
+        # Create drawable axis.
+        _state.ax = ax = plt.gca()
+        ax.set_aspect(aspect_ratio)
+
+        # Show figure but allow the main thread to continue.
+        plt.show(block=False)
+
+        # Reset plot state and draw to obtain focus.
+        clear()
+        draw()
+
+        # Add our custom event handlers. For handlers, see:
+        # https://matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.FigureCanvasBase.mpl_connect
+        # For general interaction handling, see:
+        # https://matplotlib.org/stable/users/explain/figure/interactive_guide.html
+        # For mouse buttons, see:
+        # https://matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.MouseButton
+        fig.canvas.mpl_disconnect(fig.canvas.manager.key_press_handler_id)
+        fig.canvas.mpl_disconnect(fig.canvas.manager.button_press_handler_id)
+        fig.canvas.mpl_connect("key_press_event", _key_press_handler)
+        fig.canvas.mpl_connect("button_press_event", _button_press_handler)
+
+        print("Successfully created the interactive figure.")
+    else:
+        raise RuntimeError("Error: you cannot create multiple interactive figures.")
+
+def draw():
+    """Draw contents of the figure."""
+    _check_exists()
+
+    canvas = _state.fig.canvas
+    # Mark canvas for a draw.
+    canvas.draw_idle()
+    # Force update the GUI. This is when the drawing actually happens
+    # in the backend.
+    canvas.flush_events()
+
+
+def clear(hide_labels=False, set_limits=True):
+    """Reset contents and layout of the figure. 
+    
+    *set_limits* will set the Axes limits to 
+    [0, 100]. *hide_labels* will remove all labels."""
+    _check_exists()
+
+    ax = _state.ax
+    ax.clear()
+
+    if set_limits:
+        ax.set_xlim([0, 100])
+        ax.set_ylim([0, 100])
+
+    if hide_labels:
+        ax.set_xticks([])
+        ax.set_yticks([])
+
+
+def toggle_fullscreen():
+    """Toggle fullscreen."""
+    _check_exists()
+
+    _state.figure.canvas.manager.full_screen_toggle()
+
+
+def close():
+    """Close the figure."""
+    _check_exists()
+
+    plt.close(_state.fig)
+
+    _state_reset_fig()
+    _state_reset_press()
+
+    print("Successfully closed the interactive figure.")
+
+
+def wait_for_interaction(timeout=-1):
+    """Wait for interaction. 
+    
+    Optionally use a timeout in seconds.
+
+    Parameters
+    ----------
+    timeout : int, optional
+        Timeout in seconds when waiting for input.
+
+    Returns
+    -------
+    bool | None
+        - True if a key was pressed.
+        - False if a mouse button was pressed.
+        - None if no input was given within the timeout.
+    """
+    _check_exists()
+
+    # Reimplementation of:
+    # figure.Figure.waitforbuttonpress()
+    # _blocking_input.blocking_input_loop()
+    #     but without show() to prevent redrawing the figure.
+
+    # Contains the event that was registered.
+    event = None
+
+    # Handler to stop blocking event loop.
+    def simple_handler(ev):
+        nonlocal event
+        event = ev
+        _state.fig.canvas.stop_event_loop()
+
+    # Connect event handlers and save callback ids.
+    callback_ids = [
+        _state.fig.canvas.mpl_connect(name, simple_handler) for name in ["button_press_event", "key_press_event"]
+    ]
+    try:
+        # Start a blocking event loop.
+        _state.fig.canvas.start_event_loop(timeout=timeout)
+    finally:
+        # Disconnect handlers.
+        for callback_id in callback_ids:
+            _state.fig.canvas.mpl_disconnect(callback_id)
+
+    interaction_type = None if event is None else event.name == "key_press_event"
+
+    if interaction_type is None:
+        # No button was pressed, so reset the state.
+        _state_reset_press()
+
+    return interaction_type
+
+
+def get_last_key_press():
+    """Get the last key press in lowercase.
+
+    Returns
+    -------
+    str | None
+        The last key that was pressed
+    """
+    _check_exists()
+
+    key_string = _state.last_keypress
+
+    if key_string is None:
+        return None
+    else:
+        return key_string.lower()
+
+
+def get_last_mouse_press():
+    """Get the ID of the last mouse press.
+
+    Returns
+    -------
+    int | None
+        The identifier of the last mouse button that was pressed
+    """
+    _check_exists()
+
+    mouse_button = _state.last_mousepress
+
+    if mouse_button is None:
+        return None
+    else:
+        return mouse_button.value
+
+
+def get_last_mouse_pos():
+    """Get the last mouse position.
+
+    Returns
+    -------
+    (x: float, y: float) | (None, None)
+        The last registered mouse position after any interaction
+    """
+    _check_exists()
+
+    return (_state.last_mouse_x, _state.last_mouse_y)
+
+
+def wait(timeout):
+    """Freeze for the given number of seconds. 
+    
+    During this period it is not possible to interact 
+    with the figure. For sub-second timeouts use time.wait() instead.
+
+    Parameters
+    ----------
+    timeout : float
+        Number of seconds to wait for
+    """
+    _check_exists()
+
+    _state.fig.canvas.start_event_loop(timeout=timeout)
+    # No button was pressed, so reset the state.
+    _state_reset_press()
+
+
+# PRIVATE METHODS
+
+
+def _get_state():
+    """Get all state information of the interactive figure.
+
+    Returns
+    -------
+    SimpleNamespace
+        Namespace with figure state information
+    """
+    return _state
+
+
+def _check_exists():
+    """Check if the interactive figure exists.
+
+    Raises
+    ------
+    RuntimeError
+        If the figure is not available
+    """
+    if _state.fig is None:
+        raise RuntimeError("Error: the interactive figure is not available.")
+
+
+def _state_reset_fig():
+    """Reset figure information."""
+    _state.fig = None
+    _state.ax = None
+
+
+def _state_reset_press():
+    """Reset last registered press information."""
+    _state.last_keypress = None
+    _state.last_mousepress = None
+    _state.last_mouse_x = None
+    _state.last_mouse_y = None
+
+
+def _key_press_handler(event):
+    """Register key and mouse coordinates on press.
+
+    Parameters
+    ----------
+    event
+        The event object that was generated internally
+    """
+    _state.last_keypress = event.key
+    _state.last_mousepress = None
+    _state.last_mouse_x = event.xdata
+    _state.last_mouse_y = event.ydata
+
+
+def _button_press_handler(event):
+    """Register key, mouse button and mouse coordinates on press.
+
+    Parameters
+    ----------
+    event
+        The event object that was generated internally
+    """
+    _state.last_keypress = event.key
+    _state.last_mousepress = event.button
+    _state.last_mouse_x = event.xdata
+    _state.last_mouse_y = event.ydata
+
+
+# Namespace to track the internal state of the interactive figure.
+_state = SimpleNamespace(
+    fig=None,
+    ax=None,
+    last_keypress=None,
+    last_mousepress=None,
+    last_mouse_x=None,
+    last_mouse_y=None,
+)

{interactive_figure-0.3.3.dist-info → interactive_figure-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: interactive-figure
-Version: 0.3.3
+Version: 0.3.4
 Summary: Create interactive Matplotlib figures!
 Project-URL: Documentation, https://teuncm.github.io/interactive-figure/autoapi/interactive_figure/interactive_figure/index.html
 Project-URL: Issues, https://github.com/teuncm/interactive-figure/issues
@@ -38,29 +38,15 @@ pip install interactive-figure
 from interactive_figure import interactive_figure
 
 interactive_figure.create()
-# Stall until user input is received.
+# Wait until user input is received.
 interactive_figure.wait_for_interaction()
-key = interactive_figure.get_last_keypress()
+key = interactive_figure.get_last_key_press()
 print(f"Pressed key: {key}")
 interactive_figure.close()
 ```
 
 Demos can be found in the *demo* folder on GitHub.
 
-## Functionality
-
-#### User interaction
-- Capture key presses, button presses and mouse location
-
-#### Figure control
-- Create
-- Toggle fullscreen
-- Clear
-- Wait
-- Wait for interaction (optionally timeout)
-- Draw
-- Close
-
 ## Limitations
 
 - Waiting for user input will not work in Jupyter Notebooks and the interactive interpreter due to the way Matplotlib handles events.
@@ -74,6 +60,7 @@ pipx install hatch
 hatch shell
 
 # Build
+hatch version fix
 hatch build -c
 ./generate_docs.sh
 ```

interactive_figure-0.3.4.dist-info/RECORD

@@ -0,0 +1,7 @@
+interactive_figure/__about__.py,sha256=EVh84K2XkED4bsPB10qR4q6SCbIp-6LdYq5IuJweVoo,23
+interactive_figure/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+interactive_figure/interactive_figure.py,sha256=l3AWVe6oQePBCcv3kGb5qEV_qxHWiuZeXyrxd5OlZTk,8318
+interactive_figure-0.3.4.dist-info/METADATA,sha256=Yx_G-2KYRrZ0IcVf1ZO1zewjlEZG66a02eVbOJJAQvQ,2413
+interactive_figure-0.3.4.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+interactive_figure-0.3.4.dist-info/licenses/LICENSE.txt,sha256=R6IpPdPKA5nLHPKRXIhlFHLE59dMUtve0qeXhZPr0Hk,1043
+interactive_figure-0.3.4.dist-info/RECORD,,

{interactive_figure-0.3.3.dist-info → interactive_figure-0.3.4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.18.0
+Generator: hatchling 1.25.0
 Root-Is-Purelib: true
 Tag: py3-none-any

{interactive_figure-0.3.3.dist-info → interactive_figure-0.3.4.dist-info}/licenses/LICENSE.txt

@@ -1,7 +1,7 @@
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

interactive_figure-0.3.3.dist-info/RECORD

@@ -1,7 +0,0 @@
-interactive_figure/__about__.py,sha256=8KcCYTXH99C2-gCLuPILJvtT9YftRWJsartIx6TQ2ZY,22
-interactive_figure/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-interactive_figure/interactive_figure.py,sha256=rc73FSaCdyErSDnJ8xdPiSWzROCOhjLnv-Ex2QGO4ZU,8357
-interactive_figure-0.3.3.dist-info/METADATA,sha256=G0OtQklXD3z93CoEDZrGSJrsSkWU20uDnxFXJYdKimA,2617
-interactive_figure-0.3.3.dist-info/WHEEL,sha256=9QBuHhg6FNW7lppboF2vKVbCGTVzsFykgRQjjlajrhA,87
-interactive_figure-0.3.3.dist-info/licenses/LICENSE.txt,sha256=WvwiBQtt_VVnf6szbVDxrAuRc6U6TLa7mbnvJSWzMGw,1036
-interactive_figure-0.3.3.dist-info/RECORD,,