a I”DgÈ5ã@sÂdZddlZddlZddlZddlZddlmZddlmZddl m Z m Z m Z dZ dZdZe d ej¡Ze d ¡Ze e¡Zd d „Zd d„Zdd„Zdd„Zdd„Zdd„Zdd„Zdd„ZdS)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)ÚdedentÚsplit_paragraphsÚtrim_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. (?}| t¡rL| ˆ|ˆd¡q*| t ||‡‡fdd„ƒ¡q*d  |¡S)aö Highlight special items in a usage message. :param usage_text: The usage message to process (a string). :returns: The usage message with special items highlighted. This function highlights the following special items: - The initial line of the form "Usage: ..." - Short and long command line options - Environment variables - Meta variables (see :func:`find_meta_variables()`) All items are highlighted in the color defined by :data:`.HIGHLIGHT_COLOR`. r)Ú ansi_wrapÚHIGHLIGHT_COLORT©Úcolorcs ˆ|ˆdS)Nr©©Útoken©rrrúd/mounts/lovelace/software/anaconda3/envs/paleomix/lib/python3.9/site-packages/humanfriendly/usage.pyÚzózformat_usage..Ú) Zhumanfriendly.terminalrrrÚstripÚ splitlinesÚ startswithr ÚappendÚreplace_special_tokensÚjoin)Ú usage_textZformatted_linesÚmeta_variablesÚlinerrrr\s  þrcCsPtƒ}t |¡D]6}| d¡}| d¡r| d¡\}}}|r| |¡qt|ƒ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_PATTERNÚfinditerÚgrouprÚ partitionÚaddÚlist)r r!ÚmatchrÚoptionÚ_Úvaluerrrrs    rcCsÐg}g}t|ƒ}|r8|dtk}| | d¡¡|rq8qt d|¡|r¼| t| d¡ƒ¡g}|r¦dd„t d|d¡Dƒ}t dd„|Dƒƒr”q¦q`| | d¡¡q`| td  |¡ƒ¡qDt d |¡||fS) 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: %scSs g|]}|r| ¡s| ¡‘qSr)Úisspacer©Ú.0ÚtrrrÚ Þrzparse_usage..z,\scss|]}t |¡VqdS©N)ÚOPTION_PATTERNr,r1rrrÚ ßrzparse_usage..ú zParsed options: %s) rÚSTART_OF_OPTIONS_MARKERrÚpopÚloggerÚdebugrÚreÚsplitÚallr)ÚtextÚ introductionZdocumented_optionsZ paragraphsZ end_of_introÚ descriptionÚtokensrrrr •s(2   r c sÞt|ƒ‰t|ƒ\}}‡fdd„|Dƒ}|r¾| d gd¢¡¡tƒ}t |¡}|r˜| d¡}| d¡}| t |ˆƒd ‡fdd„t |ƒDƒ¡  ¡g¡qN|  ¡  ¡}| d d d„|Dƒ¡¡t d |¡d d d„|Dƒ¡S) 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). csg|]}t|ˆƒ‘qSr©Úrender_paragraph©r2Úp©r!rrr4órz render_usage..Ú )z.. csv-table::z :header: Option, Descriptionz :widths: 30, 70rrr8c3s|]}t|ˆƒVqdSr5rDrFrHrrr7rzrender_usage..css|]}d|VqdS)z %sNr©r2r"rrrr7rzRendered output: %scss|]}t|ƒVqdSr5)r)r2Úorrrr7r)rr rrrÚcsvÚwriterr:ÚwriterowrErÚrstripÚgetvaluerr;r<) r@rAÚoptionsÚoutputZ csv_bufferZ csv_writerÚvariantsrBZ csv_linesrrHrr ês$    þ  r cCs,ddl}t|ƒj}| dt|ƒd¡dS)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/ rNrIr8)ÚcogrÚ__doc__Úoutr )Ú module_namerTr rrrr s  r cCsÊ| t¡r0| ¡}d|dd |dd…¡fS|dkr@d|St d|¡r| ¡}|d ¡sndd „|Dƒ}| dd ¡| dd ¡d  |¡S|d ¡sÆt  d d|¡}|  dd¡}t ||dd„ƒ}|S)Nz **%s** `%s`rú ér z**%s**z ^\s*\$\s+\ScSsg|] }d|‘qS)z %srrJrrrr4?rz$render_paragraph..z.. code-block:: shrrIz`(.+?)'z"\1"Ú*z\*cSsd|S)Nz``%s``rrrrrrNrz"render_paragraph..) rr r>rr=r,rr0ÚinsertÚsubÚreplacer)Z paragraphr!rCÚlinesrrrrE/s(        þrEcCst tjt||d|¡S)N)r!Ú replace_fn)r&r\Ú functoolsÚpartialÚreplace_tokens_callback)r@r!r_rrrrSsýürcCs*| d¡}t d|¡r||vs&||ƒ}|S)Nrz^[A-Z][A-Z0-9_]+$)r(r=r,)r,r!r_rrrrrb[s rb)rUrLr`Úloggingr=Ú importlibrZhumanfriendly.compatrZhumanfriendly.textrrrÚ__all__r r9ÚcompileÚVERBOSEr&r6Ú getLoggerÚ__name__r;rrr r r rErrbrrrrÚs.   ï  #U %$