@g'x dZddlZddlZddlZddlZddlZddlZddlZ ddlZddl Z ddl Z dZ ddl mZmZmZmZddlmZddlmZddlmZmZdd lmZd Zd Z d Z d ezZ edeZ dezZ dezZ! e"ddddddddZ# e"ddddddZ$ ejJdejLezZ' dZ( dZ) dZ* ejVjYdd Z- d;d!Z.d"Z/d#Z0d$Z1d%Z2d&Z3de*fd2Z?d`_. You can use the ``humanfriendly --demo`` command to get a demonstration of the available colors, see also the screen shot below. Note that the small font size in the screen shot was so that the demonstration of 256 color mode support would fit into a single screen shot without scrolling :-) (I wasn't feeling very creative). .. image:: images/ansi-demo.png **Support for 24-bit colors** In `release 4.14`_ support for 24-bit colors was added by accepting a tuple or list with three integers representing the RGB (red, green, blue) value of a color. This is not included in the demo because rendering millions of colors was deemed unpractical ;-). .. _release 4.7: http://humanfriendly.readthedocs.io/en/latest/changelog.html#release-4-7-2018-01-14 .. _release 4.14: http://humanfriendly.readthedocs.io/en/latest/changelog.html#release-4-14-2018-07-13 )color backgroundr2zCInvalid color value %r! (expected tuple or list with three numbers)rU0&r1'r4zFInvalid color value %r! (expected an integer or one of the strings %s)brightd(Z;rOrJ)itemsrget isinstancetuplelistlen ValueErrorappendextendmapintnumbersNumberr r reprsortedr joinstrrr)) kwkv sequences color_type color_valuemsgoffsetencodeds rQrrsv24[AqDT?TYZ!!$I[+ ffZ( kE4= 1;1$[ {!233   :#=R2 F   Q    Sk2 3  W^^ 4    L0b3{# "22^  [T6RbKcAd5e'f!fgg -x(bFF8,b"    V&6{&CC D9,:SXXc#y&9::XE)+0@)A}W%NwNG\sG%G% G%c*tt|S)a Calculate the effective width of the given text (ignoring ANSI escape sequences). :param text: The text whose width should be calculated (a string). :returns: The width of the text without ANSI escape sequences (an integer). This function uses :func:`ansi_strip()` to strip ANSI escape sequences from the given string and returns the length of the resulting string. )rdr)rNs rQrrs z$  rRc ttdi|}|r*t}|jdr t|}||z|zS|S)a Wrap text in ANSI escape sequences for the given color and/or style(s). :param text: The text to wrap (a string). :param kw: Any keyword arguments are passed to :func:`ansi_style()`. :returns: The result of this function depends on the keyword arguments: - If :func:`ansi_style()` generates an ANSI escape sequence based on the keyword arguments, the given text is prefixed with the generated ANSI escape sequence and suffixed with :data:`ANSI_RESET`. - If :func:`ansi_style()` returns an empty string then the text given by the caller is returned unchanged. rO)rrr`r))rNrpstart_sequence end_sequences rQrrsE  %"%N! 66" #(6L$|33 rRct|g|i|} |j|y#t$r,|jtj|t YywxYw)af Reliably write Unicode strings to the terminal. :param stream: The file-like object to write to (a value like :data:`sys.stdout` or :data:`sys.stderr`). :param text: The text to write to the stream (a string). :param args: Refer to :func:`~humanfriendly.text.format()`. :param kw: Refer to :func:`~humanfriendly.text.format()`. Renders the text using :func:`~humanfriendly.text.format()` and writes it to the given stream. If an :exc:`~exceptions.UnicodeEncodeError` is encountered in doing so, the text is encoded using :data:`DEFAULT_ENCODING` and the write is retried. The reasoning behind this rather blunt approach is that it's preferable to get output on the command line in the wrong encoding then to have the Python program blow up with a :exc:`~exceptions.UnicodeEncodeError` exception. N)r writeUnicodeEncodeErrorcodecsencoder)streamrNargsrps rQrr/sP$ $ $ $ $D< T < V]]4)9:;SZZvF}} s & 22ctrddl}|jjj |jjj dd|jjj |jjj ddyt r)dtjvry ddl }|jytS#t$rYywxYw) a Try to enable support for ANSI escape sequences (required on Windows). :returns: :data:`True` if ANSI is supported, :data:`False` otherwise. This functions checks for the following supported configurations, in the given order: 1. On Windows, if :func:`have_windows_native_ansi_support()` confirms native support for ANSI escape sequences :mod:`ctypes` will be used to enable this support. 2. On Windows, if the environment variable ``$ANSICON`` is set nothing is done because it is assumed that support for ANSI escape sequences has already been enabled via `ansicon `_. 3. On Windows, an attempt is made to import and initialize the Python package :pypi:`colorama` instead (of course for this to work :pypi:`colorama` has to be installed). 4. On other platforms this function calls :func:`connected_to_terminal()` to determine whether ANSI escape sequences are supported (that is to say all platforms that are not Windows are assumed to support ANSI escape sequences natively, without weird contortions like above). This makes it possible to call :func:`enable_ansi_support()` unconditionally without checking the current platform. The :func:`~humanfriendly.decorators.cached` decorator is used to ensure that this function is only executed once, but its return value remains available on later calls. rNir6iTANSICONF) r%ctypeswindllkernel32SetConsoleMode GetStdHandlerosenvironcoloramainit ImportErrorr)rrs rQr r sD() --fmm.D.D.Q.QRU.VXYZ --fmm.D.D.Q.QRU.VXYZ   "   MMO%&&  sC C+*C+cHtjtjtjfD] } t |}t |dk\r|cS" t}t |dk\r|S ttfS#t $rYVwxYw#t $rYttfSwxYw)a Determine the number of lines and columns visible in the terminal. :returns: A tuple of two integers with the line and column count. The result of this function is based on the first of the following three methods that works: 1. First :func:`find_terminal_size_using_ioctl()` is tried, 2. then :func:`find_terminal_size_using_stty()` is tried, 3. finally :data:`DEFAULT_LINES` and :data:`DEFAULT_COLUMNS` are returned. .. note:: The :func:`find_terminal_size()` function performs the steps above every time it is called, the result is not cached. This is because the size of a virtual terminal can change at any time and the result of :func:`find_terminal_size()` should be correct. `Pre-emptive snarky comment`_: It's possible to cache the result of this function and use :mod:`signal.SIGWINCH ` to refresh the cached values! Response: As a library I don't consider it the role of the :mod:`humanfriendly.terminal` module to install a process wide signal handler ... .. _Pre-emptive snarky comment: http://blogs.msdn.com/b/oldnewthing/archive/2008/01/30/7315957.aspx r0) rstdinrstderrr"minrr#rr)rresults rQr!r!s<))SZZ3 3F;F6{a  4 .0 v;! M  / ))      / )) s#A;B ; BB B! B!cts tdtjdt j |t jtjddddd\}}}}||fS)a Find the terminal size using :func:`fcntl.ioctl()`. :param stream: A stream connected to the terminal (a file object with a ``fileno`` attribute). :returns: A tuple of two integers with the line and column count. :raises: This function can raise exceptions but I'm not going to document them here, you should be using :func:`find_terminal_size()`. Based on an `implementation found on StackOverflow `_. z2It looks like the `fcntl' module is not available!HHHHr) HAVE_IOCTLNotImplementedErrorstructunpackfcntlioctltermios TIOCGWINSZpack)rhwhpwps rQr"r"s` !"VWW==VW=O=OQWQ\Q\]cefhiklnoQp)qrLAq"b a4KrRctjddgtjtj}|j\}}|j }t |dk7r t dttt|S)ap Find the terminal size using the external command ``stty size``. :param stream: A stream connected to the terminal (a file object). :returns: A tuple of two integers with the line and column count. :raises: This function can raise exceptions but I'm not going to document them here, you should be using :func:`find_terminal_size()`. sttysize)rrr1z Invalid output from `stty size'!) subprocessPopenPIPE communicaterrdrrbrhri)rrrtokenss rQr#r#sr   VV,#-??#-?? 4D%%'NFF \\^F 6{a:;; S&! ""rRc|r t|vrddg}n!tjjddg}tjj |ddk(r"|j d|j d|S)a Get the command to show a text on the terminal using a pager. :param text: The text to print to the terminal (a string). :returns: A list of strings with the pager command and arguments. The use of a pager helps to avoid the wall of text effect where the user has to scroll up to see where the output began (not very user friendly). If the given text contains ANSI escape sequences the command ``less --RAW-CONTROL-CHARS`` is used, otherwise the environment variable ``$PAGER`` is used (if ``$PAGER`` isn't set :man:`less` is used). When the selected pager is :man:`less`, the following options are used to make the experience more user friendly: - ``--quit-if-one-screen`` causes :man:`less` to automatically exit if the entire text can be displayed on the first screen. This makes the use of a pager transparent for smaller texts (because the operator doesn't have to quit the pager). - ``--no-init`` prevents :man:`less` from clearing the screen when it exits. This ensures that the operator gets a chance to review the text (for example a usage message) after quitting the pager, while composing the next command. lessz--RAW-CONTROL-CHARSPAGERrz --no-initz--quit-if-one-screen)r rrr`pathbasenamerf)rN command_lines rQr$r$-sp8 D  56  w78  ww Q(F2K(23 rRctr9 tdtjj dD}|dk\Sy#t $rYywxYw)a Check if we're running on a Windows 10 release with native support for ANSI escape sequences. :returns: :data:`True` if so, :data:`False` otherwise. The :func:`~humanfriendly.decorators.cached` decorator is used as a minor performance optimization. Semantically this should have zero impact because the answer doesn't change in the lifetime of a computer process. c32K|]}t|ywN)ri).0cs rQ z3have_windows_native_ansi_support..fsM/L!s1v/Ls.) ri98F)rrbplatformversionrr) componentss rQr%r%Us[|  Mx/?/?/A/G/G/LMMJ/ /     s7A AAcXttjt|dzg|i|y)a[ Print a formatted message to the standard error stream. For details about argument handling please refer to :func:`~humanfriendly.text.format()`. Renders the message using :func:`~humanfriendly.text.format()` and writes the resulting string (followed by a newline) to :data:`sys.stderr` using :func:`auto_encode()`. rN)rrrrrNrrps rQr&r&m& M$/$6DDDrRcXttjt|dzg|i|y)a\ Print a formatted message to the standard output stream. For details about argument handling please refer to :func:`~humanfriendly.text.format()`. Renders the message using :func:`~humanfriendly.text.format()` and writes the resulting string (followed by a newline) to :data:`sys.stdout` using :func:`auto_encode()`. rN)rrrrrs rQr'r'{rrRcF|jddjddS)z Remove `readline hints`_ from a string. :param text: The text to strip (a string). :returns: The stripped text. rJ)replaceexprs rQr(r(s" << # + +FB 77rRcd|zdzS)z Wrap an ANSI escape sequence in `readline hints`_. :param text: The text with the escape sequence to wrap (a string). :returns: The wrapped text. .. _readline hints: http://superuser.com/a/301355 rrr{rs rQr)r)s D=6 !!rRctrmt|}t|drTtj|tj }t |r|j|}|j|yt|y)a' Print a large text to the terminal using a pager. :param formatted_text: The text to print to the terminal (a string). :param encoding: The name of the text encoding used to encode the formatted text if the formatted text is a Unicode string (a string, defaults to :data:`DEFAULT_ENCODING`). When :func:`connected_to_terminal()` returns :data:`True` a pager is used to show the text on the terminal, otherwise the text is printed directly without invoking a pager. The use of a pager helps to avoid the wall of text effect where the user has to scroll up to see where the output began (not very user friendly). Refer to :func:`get_pager_command()` for details about the command line that's used to invoke the pager. r)r)inputN) rr$rrrrrrrr')formatted_textencodingrpagers rQr*r*sj&(8 a !$$\IE.)!/!6!6x!@   N  3  >rRctr5dtjv}dtjv}t }|s|s|syt |S)a3 Check if a stream is connected to a terminal that supports ANSI escape sequences. :param stream: The stream to check (a file-like object, defaults to :data:`sys.stdout`). :returns: :data:`True` if the terminal supports ANSI escape sequences, :data:`False` otherwise. This function was originally inspired by the implementation of `django.core.management.color.supports_color() `_ but has since evolved significantly. rrF)rrrrmodulesr%r)r have_ansicon have_coloramahave_native_supports rQr+r+sD| BJJ. "ckk1 >@ 1D  ((rRcbttjr t|}t |y)a Print a human friendly usage message to the terminal. :param text: The usage message to print (a string). This function does two things: 1. If :data:`sys.stdout` is connected to a terminal (see :func:`connected_to_terminal()`) then the usage message is formatted using :func:`.format_usage()`. 2. The usage message is shown using a pager (see :func:`show_pager()`). N)r+rrr r*) usage_texts rQr,r,s"  +!*- zrRct|}ttjr t |d}t tj|dzg|i|y)a Show a warning message on the terminal. For details about argument handling please refer to :func:`~humanfriendly.text.format()`. Renders the message using :func:`~humanfriendly.text.format()` and writes the resulting string (followed by a newline) to :data:`sys.stderr` using :func:`auto_encode()`. If :data:`sys.stderr` is connected to a terminal that supports colors, :func:`ansi_wrap()` is used to color the message in a red font (to make the warning stand out from surrounding text). r8)rTrN)rr+rrrrrs rQr-r-sB  D +U+ D4K5$5"5rRz'humanfriendly.usage.find_meta_variablesz humanfriendly.usage.format_usagez(humanfriendly.terminal.html.html_to_ansiz)humanfriendly.terminal.html.HTMLConverter) module_namefind_meta_variablesr html_to_ansi HTMLConverter)Tr)D__doc__rrjrrrKrrrrrrrhumanfriendly.compatrrrrhumanfriendly.decoratorsrhumanfriendly.deprecationrhumanfriendly.textr r humanfriendly.usager __all__r rrrrrdictr rcompilerLrrrrrr`rrrrrrrrr r!r"r#r$r%r&r'r(r)r*r+r,r-__name__r{rRrQrs$   J NM+42,# J 8 >("D ( + ;h&Bh&BaQa1ST\]^QaQZ[\ "rzz"2YRYY5O"OP =?.**..!@'J"^B !4<2GT$0'0'f-*`$#&%P. E E8 ")9>)0$6,B3<= kJsD??E  E