|
1 | 1 | from __future__ import annotations
|
2 | 2 |
|
3 |
| -import contextlib |
4 |
| -import sys |
5 | 3 | from contextlib import AbstractContextManager
|
6 |
| -from typing import Callable, Generator, TypeVar, cast, overload |
| 4 | +from typing import Callable, TypeVar |
7 | 5 |
|
8 |
| -from .. import ui |
9 |
| -from ..render.renderer import Renderer, RendererT |
| 6 | +from .._deprecated import warn_deprecated |
| 7 | +from .._typing_extensions import ParamSpec |
| 8 | +from ..render.renderer import RendererT |
| 9 | +from .ui import hold |
10 | 10 |
|
11 | 11 | __all__ = ("suspend_display",)
|
12 | 12 |
|
| 13 | +P = ParamSpec("P") |
| 14 | +R = TypeVar("R") |
13 | 15 | CallableT = TypeVar("CallableT", bound=Callable[..., object])
|
14 | 16 |
|
15 | 17 |
|
@@ -45,82 +47,11 @@ def wrapper(renderer: RendererT) -> RendererT:
|
45 | 47 | return wrapper
|
46 | 48 |
|
47 | 49 |
|
48 |
| -@overload |
49 |
| -def suspend_display(fn: RendererT) -> RendererT: |
50 |
| - ... |
51 |
| - |
52 |
| - |
53 |
| -@overload |
54 |
| -def suspend_display(fn: CallableT) -> CallableT: |
55 |
| - ... |
56 |
| - |
57 |
| - |
58 |
| -@overload |
59 |
| -def suspend_display() -> AbstractContextManager[None]: |
60 |
| - ... |
61 |
| - |
62 |
| - |
63 | 50 | def suspend_display(
|
64 |
| - fn: RendererT | CallableT | None = None, |
65 |
| -) -> RendererT | CallableT | AbstractContextManager[None]: |
66 |
| - """Suppresses the display of UI elements in various ways. |
67 |
| -
|
68 |
| - If used as a context manager (`with suspend_display():`), it suppresses the display |
69 |
| - of all UI elements within the context block. (This is useful when you want to |
70 |
| - temporarily suppress the display of a large number of UI elements, or when you want |
71 |
| - to suppress the display of UI elements that are not directly under your control.) |
72 |
| -
|
73 |
| - If used as a decorator (without parentheses) on a Shiny rendering function, it |
74 |
| - prevents that function from automatically outputting itself at the point of its |
75 |
| - declaration. (This is useful when you want to define the rendering logic for an |
76 |
| - output, but want to explicitly call a UI output function to indicate where and how |
77 |
| - it should be displayed.) |
78 |
| -
|
79 |
| - If used as a decorator (without parentheses) on any other function, it turns |
80 |
| - Python's `sys.displayhook` into a no-op for the duration of the function call. |
81 |
| -
|
82 |
| - Parameters |
83 |
| - ---------- |
84 |
| - fn |
85 |
| - The function to decorate. If `None`, returns a context manager that suppresses |
86 |
| - the display of UI elements within the context block. |
87 |
| -
|
88 |
| - Returns |
89 |
| - ------- |
90 |
| - : |
91 |
| - If `fn` is `None`, returns a context manager that suppresses the display of UI |
92 |
| - elements within the context block. Otherwise, returns a decorated version of |
93 |
| - `fn`. |
94 |
| - """ |
95 |
| - |
96 |
| - if fn is None: |
97 |
| - return suspend_display_ctxmgr() |
98 |
| - |
99 |
| - # Special case for Renderer; when we decorate those, we just mean "don't |
100 |
| - # display yourself" |
101 |
| - if isinstance(fn, Renderer): |
102 |
| - # By setting the class value, the `self` arg will be auto added. |
103 |
| - fn.auto_output_ui = null_ui |
104 |
| - return cast(RendererT, fn) |
105 |
| - |
106 |
| - return suspend_display_ctxmgr()(fn) |
107 |
| - |
108 |
| - |
109 |
| -@contextlib.contextmanager |
110 |
| -def suspend_display_ctxmgr() -> Generator[None, None, None]: |
111 |
| - oldhook = sys.displayhook |
112 |
| - sys.displayhook = null_displayhook |
113 |
| - try: |
114 |
| - yield |
115 |
| - finally: |
116 |
| - sys.displayhook = oldhook |
117 |
| - |
118 |
| - |
119 |
| -def null_ui( |
120 |
| - **kwargs: object, |
121 |
| -) -> ui.TagList: |
122 |
| - return ui.TagList() |
123 |
| - |
124 |
| - |
125 |
| -def null_displayhook(x: object) -> None: |
126 |
| - pass |
| 51 | + fn: Callable[P, R] | RendererT | None = None |
| 52 | +) -> Callable[P, R] | RendererT | AbstractContextManager[None]: |
| 53 | + warn_deprecated( |
| 54 | + "`suspend_display` is deprecated. Please use `ui.hold` instead. " |
| 55 | + "It has a new name, but the exact same functionality." |
| 56 | + ) |
| 57 | + return hold(fn) # type: ignore |
0 commit comments