. &dZddlZddlZddlZddlmZddlmZddlm Z dZ gdZ dZ Gd d e ZGd d e Zy) aY Support for spinners that represent progress on interactive terminals. The :class:`Spinner` class shows a "spinner" on the terminal to let the user know that something is happening during long running operations that would otherwise be silent (leaving the user to wonder what they're waiting for). Below are some visual examples that should illustrate the point. **Simple spinners:** Here's a screen capture that shows the simplest form of spinner: .. image:: images/spinner-basic.gif :alt: Animated screen capture of a simple spinner. The following code was used to create the spinner above: .. code-block:: python import itertools import time from humanfriendly import Spinner with Spinner(label="Downloading") as spinner: for i in itertools.count(): # Do something useful here. time.sleep(0.1) # Advance the spinner. spinner.step() **Spinners that show elapsed time:** Here's a spinner that shows the elapsed time since it started: .. image:: images/spinner-with-timer.gif :alt: Animated screen capture of a spinner showing elapsed time. The following code was used to create the spinner above: .. code-block:: python import itertools import time from humanfriendly import Spinner, Timer with Spinner(label="Downloading", timer=Timer()) as spinner: for i in itertools.count(): # Do something useful here. time.sleep(0.1) # Advance the spinner. spinner.step() **Spinners that show progress:** Here's a spinner that shows a progress percentage: .. image:: images/spinner-with-progress.gif :alt: Animated screen capture of spinner showing progress. The following code was used to create the spinner above: .. code-block:: python import itertools import random import time from humanfriendly import Spinner, Timer with Spinner(label="Downloading", total=100) as spinner: progress = 0 while progress < 100: # Do something useful here. time.sleep(0.1) # Advance the spinner. spinner.step(progress) # Determine the new progress value. progress += random.random() * 5 If you want to provide user feedback during a long running operation but it's not practical to periodically call the :func:`~Spinner.step()` method consider using :class:`AutomaticSpinner` instead. As you may already have noticed in the examples above, :class:`Spinner` objects can be used as context managers to automatically call :func:`Spinner.clear()` when the spinner ends. N)Timer)deprecated_args)ANSI_ERASE_LINE)AutomaticSpinnerGLYPHSMINIMUM_INTERVALSpinner)-\|/g?cVeZdZdZeddddddZdd Zd Zd Zd Z dd Z y)r zIShow a spinner on the terminal as a simple means of feedback to the user.labeltotalstream interactivetimerc |jd|_|jdt|_|jd|_|jdt |_|jdtj|_ |jd|_ |jd|_ d|_ d|_ |j! |jj|_y y #t$r d |_Yy wxYw) a Initialize a :class:`Spinner` object. :param label: The label for the spinner (a string or :data:`None`, defaults to :data:`None`). :param total: The expected number of steps (an integer or :data:`None`). If this is provided the spinner will show a progress percentage. :param stream: The output stream to show the spinner on (a file-like object, defaults to :data:`sys.stderr`). :param interactive: :data:`True` to enable rendering of the spinner, :data:`False` to disable (defaults to the result of ``stream.isatty()``). :param timer: A :class:`.Timer` object (optional). If this is given the spinner will show the elapsed time according to the timer. :param interval: The spinner will be updated at most once every this many seconds (a floating point number, defaults to :data:`MINIMUM_INTERVAL`). :param glyphs: A list of strings with single characters that are drawn in the same place in succession to implement a simple animated effect (defaults to :data:`GLYPHS`). rintervalrglyphsrrrrNF)getrrrrrstatessysstderrrrrcounter last_updateisatty Exception)selfoptionss D/usr/lib/python3.12/site-packages/humanfriendly/terminal/spinners.py__init__zSpinner.__init__vsT#;;}5 J0@A [[) kk(F3 kk(CJJ7 [[) [[)      # )#';;#5#5#7  $ )#(  )sC00DDNcp|jr)tj}||jz |jk\r||_|j|j t |jz}|xs |j}|s td|jr|rd|||jdz z fz}nA|jr5|jjdkDr|d|jjd}|jjtd|d|d|xj d z c_y y y ) a Advance the spinner by one step and redraw it. :param progress: The number of the current step, relative to the total given to the :class:`Spinner` constructor (an integer, optional). If not provided the spinner will not show progress. :param label: The label to use while redrawing (a string, optional). If not provided the label given to the :class:`Spinner` constructor is used instead. This method advances the spinner by one step without starting a new line, causing an animated effect which is very simple but much nicer than waiting for a prompt which is completely silent for a long time. .. note:: This method uses time based rate limiting to avoid redrawing the spinner too frequently. If you know you're dealing with code that will call :func:`step()` at a high frequency, consider using :func:`sleep()` to avoid creating the equivalent of a busy loop that's rate limiting the spinner 99% of the time. zNo label set for spinner!z %s: %.2f%%gY@z () z .. N)rtimerrrrlenrrrr elapsed_timeroundedrwriter)rprogressrtime_nowstates r!stepz Spinner.steps.   yy{H$***dmm;#+  DLL3t{{3C$CD+#$?@@ZZH(E8tzzE?Q3R+SSEZZDJJ$;$;a$?). 0B0BCE !!_eU"ST ! < c6tjty)a Sleep for a short period before redrawing the spinner. This method is useful when you know you're dealing with code that will call :func:`step()` at a high frequency. It will sleep for the interval with which the spinner is redrawn (less than a second). This avoids creating the equivalent of a busy loop that's rate limiting the spinner 99% of the time. This method doesn't redraw the spinner, you still have to call :func:`step()` in order to do that. N)r(sleeprrs r!r3z Spinner.sleeps #$r1c\|jr |jjtyy)z Clear the spinner. The next line which is shown on the standard output or error stream after calling this method will overwrite the line that used to show the spinner. N)rrr,rr4s r!clearz Spinner.clears$    KK  o . r1c|S)zq Enable the use of spinners as context managers. :returns: The :class:`Spinner` object. r4s r! __enter__zSpinner.__enter__s  r1c$|jy)z+Clear the spinner when leaving the context.N)r6rexc_type exc_value tracebacks r!__exit__zSpinner.__exit__s  r1)rNNNN) __name__ __module__ __qualname____doc__rr"r0r3r6r9r?r8r1r!r r rs@SWgxH9)I9)v$"L % /r1r c,eZdZdZddZdZddZdZy) ra Show a spinner on the terminal that automatically starts animating. This class shows a spinner on the terminal (just like :class:`Spinner` does) that automatically starts animating. This class should be used as a context manager using the :keyword:`with` statement. The animation continues for as long as the context is active. :class:`AutomaticSpinner` provides an alternative to :class:`Spinner` for situations where it is not practical for the caller to periodically call :func:`~Spinner.step()` to advance the animation, e.g. because you're performing a blocking call and don't fancy implementing threading or subprocess handling just to provide some user feedback. This works using the :mod:`multiprocessing` module by spawning a subprocess to render the spinner while the main process is busy doing something more useful. By using the :keyword:`with` statement you're guaranteed that the subprocess is properly terminated at the appropriate time. c||_||_tj|_tj |j |_y)z Initialize an automatic spinner. :param label: The label for the spinner (a string). :param show_time: If this is :data:`True` (the default) then the spinner shows elapsed time. )targetN)r show_timemultiprocessingEventshutdown_eventProcess_target subprocess)rrrHs r!r"zAutomaticSpinner.__init__s9 "-335)11Fr1c8|jjyz9Enable the use of automatic spinners as context managers.N)rNstartr4s r!r9zAutomaticSpinner.__enter__#s r1Ncl|jj|jjyrP)rKsetrNjoinr;s r!r?zAutomaticSpinner.__exit__'s$ ! r1cV |jr tnd}t|j|5}|jj s;|j |j|jj s;dddy#1swYyxYw#t$rYywxYw)N)rr) rHrr rrKis_setr0r3KeyboardInterrupt)rrspinners r!rMzAutomaticSpinner._target,s #~~EG4Etzz77--446LLNMMO--446877!   s//BABBBBB B('B()Tr@)rArBrCrDr"r9r?rMr8r1r!rrs* G  r1r)rDrIrr( humanfriendlyrhumanfriendly.deprecationrhumanfriendly.terminalr__all__rrobjectr rr8r1r!r^sVUp  52 H QlJfJZ7v7r1