Zj7B;rdZddlZddlZddlZddlZddlmZddlmZddl m Z m Z m Z dZ dZ dZ ej d ej"Zej d Zej(eZd Zd Zd ZdZdZdZdZdZy)a Parsing and reformatting of usage messages. The :mod:`~humanfriendly.usage` module parses and reformats usage messages: - The :func:`format_usage()` function takes a usage message and inserts ANSI escape sequences that highlight items of special significance like command line options, meta variables, etc. The resulting usage message is (intended to be) easier to read on a terminal. - The :func:`render_usage()` function takes a usage message and rewrites it to reStructuredText_ suitable for inclusion in the documentation of a Python package. This provides a DRY solution to keeping a single authoritative definition of the usage message while making it easily available in documentation. As a cherry on the cake it's not just a pre-formatted dump of the usage message but a nicely formatted reStructuredText_ fragment. - The remaining functions in this module support the two functions above. Usage messages in general are free format of course, however the functions in this module assume a certain structure from usage messages in order to successfully parse and reformat them, refer to :func:`parse_usage()` for details. .. _DRY: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself .. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText N) import_module)StringIO)dedentsplit_paragraphstrim_empty_lines)find_meta_variables format_usager inject_usage parse_usage render_usage USAGE_MARKERzUsage:Supported options:a # Make sure whatever we're matching isn't preceded by a non-whitespace # character. (?zformat_usage..zs i_E) humanfriendly.terminalrrrstrip splitlines startswithr appendreplace_special_tokensjoin) usage_textformatted_linesmeta_variableslinerrs @@rr r \s&BO(4N  "--d3 ??< (  " "9T#I J  " "#9nE$  4 77? ##rct}tj|D]N}|jd}|j ds&|j d\}}}|s>|j |Pt|S)a Find the meta variables in the given usage message. :param usage_text: The usage message to parse (a string). :returns: A list of strings with any meta variables found in the usage message. When a command line option requires an argument, the convention is to format such options as ``--option=ARG``. The text ``ARG`` in this example is the meta variable. r-=)set USAGE_PATTERNfinditergroupr partitionaddlist)r"r$matchroption_values rrrsnUN'' 3 A   C $s3 FAu""5) 4  rcg}g}t|}|r2|dtk(}|j|jd|rn|r2tj d||r|jt |jdg}|r~tjd|dDcgc]&}|s|jr|j(}}td|Drn#|j|jd|r~|jt dj||rtj d|||fScc}w)a Parse a usage message by inferring its structure (and making some assumptions :-). :param text: The usage message to parse (a string). :returns: A tuple of two lists: 1. A list of strings with the paragraphs of the usage message's "introduction" (the paragraphs before the documentation of the supported command line options). 2. A list of strings with pairs of command line options and their descriptions: Item zero is a line listing a supported command line option, item one is the description of that command line option, item two is a line listing another supported command line option, etc. Usage messages in general are free format of course, however :func:`parse_usage()` assume a certain structure from usage messages in order to successfully parse them: - The usage message starts with a line ``Usage: ...`` that shows a symbolic representation of the way the program is to be invoked. - After some free form text a line ``Supported options:`` (surrounded by empty lines) precedes the documentation of the supported command line options. - The command line options are documented as follows:: -v, --verbose Make more noise. So all of the variants of the command line option are shown together on a separate line, followed by one or more paragraphs describing the option. - There are several other minor assumptions, but to be honest I'm not sure if anyone other than me is ever going to use this functionality, so for now I won't list every intricate detail :-). If you're curious anyway, refer to the usage message of the `humanfriendly` package (defined in the :mod:`humanfriendly.cli` module) and compare it with the usage message you see when you run ``humanfriendly --help`` and the generated usage message embedded in the readme. Feel free to request more detailed documentation if you're interested in using the :mod:`humanfriendly.usage` module outside of the little ecosystem of Python packages that I have been building over the past years. rzParsed introduction: %sz,\sc3FK|]}tj|ywN)OPTION_PATTERNr0).0ts r zparse_usage..s;Fq>''*Fs! zParsed options: %s) rSTART_OF_OPTIONS_MARKERrpoploggerdebugrresplitisspacerallr!)text introductiondocumented_options paragraphs end_of_intro descriptionr9tokenss rr r s5dL!$'J "1 )@@ JNN1-.    LL*L9 !!&):";<  *,&*Q-)Hb)HAAVWV_V_Vaaggi)HFb;F;;"":>>!#45 !!&[)A"BC   LL%'9: + ++cs$E ,E =E c  t| t|\}}|Dcgc]}t| }}|r|jdj gdt }t j|}|rq|jd}|jd}|jt| dj fdt|Djg|rq|jj} |jdj d| Dtjd|dj d|DScc}w) z Reformat a command line program's usage message to reStructuredText_. :param text: The plain text usage message (a string). :returns: The usage message rendered to reStructuredText_ (a string).  )z.. csv-table::z :header: Option, Descriptionz :widths: 30, 70rrr;c36K|]}t|ywr6)render_paragraph)r8pr$s rr:zrender_usage..shJgQ-a@Jgsc3&K|] }d|z yw)z %sNr)r8r%s rr:zrender_usage..sE94$9szRendered output: %sc32K|]}t|ywr6)r)r8os rr:zrender_usage..s;Fq'*Fs)rr rNrr!rcsvwriterr=writerowrrstripgetvaluerr>r?) rDrEoptionsrOoutput csv_buffer csv_writervariantsrI csv_linesr$s @rr r s/).N'-L';G H:hJZ[fJghhppr! '')446  diiE9EEF LL&/ ;;;F; ;;)IsEcvddl}t|j}|jdt |zdzy)a Use cog_ to inject a usage message into a reStructuredText_ file. :param module_name: The name of the module whose ``__doc__`` attribute is the source of the usage message (a string). This simple wrapper around :func:`render_usage()` makes it very easy to inject a reformatted usage message into your documentation using cog_. To use it you add a fragment like the following to your ``*.rst`` file:: .. [[[cog .. from humanfriendly.usage import inject_usage .. inject_usage('humanfriendly.cli') .. ]]] .. [[[end]]] The lines in the fragment above are single line reStructuredText_ comments that are not copied to the output. Their purpose is to instruct cog_ where to inject the reformatted usage message. Once you've added these lines to your ``*.rst`` file, updating the rendered usage message becomes really simple thanks to cog_: .. code-block:: sh $ cog.py -r README.rst This will inject or replace the rendered usage message in your ``README.rst`` file with an up to date copy. .. _cog: http://nedbatchelder.com/code/cog/ rNrLr;)cogr__doc__outr ) module_namer_r"s rr r s3@{+33JGGD< + +f 45rc>|jtr.|j}d|dddj|dddS|dk(rd|zSt j d |rj|j }|djs|Dcgc]}d |z }}|jdd |jdd d j|S|djs7t jdd|}|jdd}t||d}|Scc}w)Nz**rz** ` `rz**%s**z ^\s*\$\s+\Sz %sz.. code-block:: shrrLz`(.+?)'z"\1"*z\*c d|zS)Nz``%s``r)rs rrz"render_paragraph..Ns (U*r) rr rAr!r@r0rrBinsertsubreplacer ) paragraphr$rJlinesr%s rrNrN/sL)" &q 388F12J+?@@(()## xx *$$&|##%/45utVd]uE5 Q,- Qyy Q<   !FF9gy9 %%c51 * ~ *  #6s Dcbtjtjt|||S)N)r$ replace_fn)r*rj functoolspartialreplace_tokens_callback)rDr$ros rr r Ss0   Y..%   rcl|jd}tjd|r||vs||}|S)Nrz^[A-Z][A-Z0-9_]+$)r,r@r0)r0r$rors rrrrr[s4 KKNE HH(% 0U.5P5! Lr)r`rSrploggingr@ importlibrhumanfriendly.compatrhumanfriendly.textrrr__all__r r<compileVERBOSEr*r7 getLogger__name__r>r rr r r rNr rrrrrr}s:  $*II  ?.M "ZZ# (:;   8 $ $F ,R,j<@"6J!H r