o i@sdZddlmZdZddlZddlZddlZddlZddlZddl m Z m Z m Z m Z mZmZmZmZddlmZddlmZdZerNdd lmZdd lmZGd d d Zd ZdZddddddddddddeefddZ       d>ddZ       d?ddZ de j!ddddddddddddfddZ"de j!dddddddddf ddZ#     d@ddZ$ddddddddddddeede j%fdd Z&dAd#d$Z'd%d&Z(dBdAd(d)Z)dAd*d+Z*dAd,d-Z+dAd.d/Z,dAd0d1Z-dAd2d3Z.dAd4d5Z/dAd6d7Z0dAd8d9Z1dAd:d;Z2dAdpartsr&r&r'_setup_settings_parsers"  $z Publisher._setup_settings_parsercKs(|j||||fi|}||_|jS)a Return settings from components and config files. Please set components first (`self.set_reader` & `self.set_writer`). Use keyword arguments to override component defaults (before updating from configuration files). Calling this function also sets `self.settings` which makes `self.publish()` skip parsing command line options. )rKget_default_valuesr")r%r@rArIrEr> option_parserr&r&r' get_settingss  zPublisher.get_settingscCsD|jdur |r |ni}|dd|jd||d|dSdS)N tracebackT)rIrEr&)r"copy setdefaultrN)r%rIsettings_overridesrEr>r&r&r'process_programmatic_settingss   z'Publisher.process_programmatic_settingscKs>|j||||fi|}|durtjdd}|||_dS)z Parse command line arguments and set ``self.settings``. Pass an empty sequence to `argv` to avoid reading `sys.argv` (the default behaviour). Set components first (`self.set_reader` & `self.set_writer`). Nr9)rKsysargv parse_argsr")r%rUr@rArIrEr>rMr&r&r'process_command_lines zPublisher.process_command_linecCs4|jdur |j|d|jdur|j|ddSdS)N) source_path)destination_path)r set_sourcer set_destination)r%rXrYr&r&r'set_ios   zPublisher.set_ior str | NonerXStrPath | NonecCsD|dur |jj}n t|}||j_|j|||jj|jjd|_dS)N)rrXencoding error_handler)r"_sourceosfspathrinput_encodinginput_encoding_error_handlerr)r%rrXr&r&r'rZs   zPublisher.set_sourcer TextIO | NonerYcCs|dur t||j_n;t|jddr|jjs|jj|j_|jjr1|jjr1|jj|jjkr1td|jjdur=|jj|j_|jjdkrGd|j_|jj|j_|j_|j||jj|jj |jj d|_ dS)NoutputznThe --output-path option obsoletes the second positional argument (DESTINATION). You cannot use them together.-)r rYr_r`) rbrcr" output_pathgetattrrg _destination SystemExitr!output_encodingoutput_encoding_error_handlerr )r%r rYr&r&r'r[s*     zPublisher.set_destinationcCs4|jj|j|j|jj|j|jf|jjdS)N) r transformerpopulate_from_componentsrrrrr apply_transformsr%r&r&r'rqs zPublisher.apply_transformsFc CsHd}z<|jdur|j|||||fi|pi|||j|j|j|j|_| |j |j|j } |j Wn>tyU} z d}| j} WYd} ~ n,d} ~ wty|} z|js`|jjri||| d}d} WYd} ~ nd} ~ ww||r|jr|jjj|jjkrt|jjjd| S|rt| | S)z Process command line options and arguments (if `self.settings` not already set), run `self.reader` and then `self.writer`. Return `self.writer`'s output. NTr9 )r"rWr\promptrreadrrrrqrwriter assemble_partsrlcode ExceptionrOdebugging_dumpsreport_Exceptionreporter max_levelexit_status_levelrTexit) r%rUr@rArIrRrEenable_exit_statusexit_rgerror exit_statusr&r&r'publishsR     zPublisher.publishcCs|jsdS|jjrtd|jdtt|jj|jd|jjr3td|jdtt|jj|jd|jj rWtd|jdtd|jdttdd|jj j D|jd|jj rqtd|jdt|j d |jddSdS) Nz ::: Runtime settings:filez ::: Document internals:z ::: Transforms applied:z@ (priority, transform class, pending node details, keyword args)cSs2g|]\}}}}|d|j|jf|o|j|fqS)z%s.%s) __module____name__details).0priorityxclasspendingkwargsr&r&r' 5s   z-Publisher.debugging_dumps..z ::: Pseudo-XML:raw_unicode_escape)rr" dump_settingsprintr$pprintpformat__dict__dump_internalsdump_transformsroapplieddump_pseudo_xmlencoderrr&r&r'rz's8  zPublisher.debugging_dumpsc Csz|jr |jsWdSWn tyYdSwtjdkr!dnd}d}d}z|jjd}|jjd}Wn tt fy@Ynwt dt d |d |d |d |jd dS)z=Print info and prompt when waiting for input from a terminal.NntzCtrl+ZzCtrl+Dzuseful formatsrz Docutils z/ converting "z" into "zT". Call with option "--help" for more info. .. Waiting for source text (finish with z on an empty line):r) risattyr$AttributeErrorrbnamer supportedr IndexErrorrr)r%eot_key in_format out_formatr&r&r'rt>s2    zPublisher.promptcCst|tjr ||dSt|tr||dSt|tjr,|j dt |dSt|tj r?|j dt |dSt dt ||jdt dt trWdtdndd tjd d |jddS) Nz-Unable to open source file for reading: %s z2Unable to open destination file for writing: %s z%srzExiting due to error. Use "--traceback" to diagnose. Please report errors to . Include "--traceback" output, Docutils version (z []rz), Python version (rz5), your OS type & version, and the command line used.)rr SystemMessagereport_SystemMessageUnicodeEncodeErrorreport_UnicodeErrorr InputErrorr$rv error_string OutputErrorrrrrTversionrFr%rr&r&r'r{Ts0      zPublisher.report_ExceptioncCs&td|jtjj|jf|jddS)Nz,Exiting due to level-%s (%s) system message.r)rlevelrReporterlevelsr$rr&r&r'rjs  zPublisher.report_SystemMessagec Cs\|j|j|j}|jdt||jj| dd| dd|jj t t j dfdS)Na%s The specified output encoding (%s) cannot handle all of the output. Try setting "--output-encoding-error-handler" to * "xmlcharrefreplace" (for HTML & XML output); the output will contain "%s" and should be usable. * "backslashreplace" (for other output formats); look for "%s" in the output. * "replace"; look for "?" in the output. "--output-encoding-error-handler" is currently set to "%s". Exiting due to error. Use "--traceback" to diagnose. If the advice above doesn't eliminate the error, please report it to . Include "--traceback" output, Docutils version (%s), Python version (%s), your OS type & version, and the command line used. asciixmlcharrefreplacebackslashreplacer)objectstartendr$rvrrr"rmrrnrrTrrF)r%rdatar&r&r'ros  zPublisher.report_UnicodeErrorrr)NN)NNNN)NNNNN)rr]rXr^rr)r rfrYr^rr)NNNNNNF)rr __qualname____doc__r FileInput FileOutputr(r+r.r6rKrNrSrWr\rZr[rqrrzrtr{rrr&r&r&r'r%sJ 6        *   rz*%prog [options] [ []]zReads from (default is stdin) and writes to (default is stdout). See https://docutils.sourceforge.io/docs/user/config.html for a detailed settings reference.Tc Cs\t||||p |p d}|p|pd}|p|pd}t||||d}|j| | | ||| | d}|S)aT Set up & run a `Publisher` for command-line-based file I/O (input and output file paths taken automatically from the command line). Also return the output as `str` or `bytes` (for binary output document formats). Parameters: see `publish_programmatically()` for the remainder. - `argv`: Command-line argument list to use instead of ``sys.argv[1:]``. - `usage`: Usage string, output if there's a problem parsing the command line. - `description`: Program description, output for the "--help" option (along with command-line option descriptions). standalonerestructuredtext pseudoxml)r"rEr)_name_arg_warningrr)rr5rr)rr,r"rIrRrErrUr@rA publisherrgr&r&r'publish_cmdlines     rcCst||| tdidtjd|d|dtjd|d|d|d|d |d |d |d | d | d| d| d| d|\}}|S)z Set up & run a `Publisher` for programmatic use with file-like I/O. Also return the output as `str` or `bytes` (for binary output document formats). Parameters: see `publish_programmatically()`. rrrXr!r rYrr5rr)rr,r"rIrRrErNr&)rpublish_programmaticallyrrr)rrXr rYrr5rr)rr,r"rIrRrErrg _publisherr&r&r' publish_filesJ    rcCst|||tdidtjd|d|dtjddd|d|d |d |d |d |d |d| d| d| d| d| \}}|S)u Set up & run a `Publisher` for programmatic use with string I/O. Accepts a `bytes` or `str` instance as `source`. The output is encoded according to the `output_encoding`_ setting; the return value is a `bytes` instance (unless `output_encoding`_ is "unicode", cf. `docutils.io.StringOutput.write()`). Parameters: see `publish_programmatically()` or https://docutils.sourceforge.io/docs/api/publisher.html#publish-string This function is provisional because in Python 3 name and behaviour no longer match. .. _output_encoding: https://docutils.sourceforge.io/docs/user/config.html#output-encoding rrrXr!r NrYrr5rr)rr,r"rIrRrErr&)rrr StringInput StringOutput)rrXrYrr5rr)rr,r"rIrRrErrgrr&r&r'publish_stringsJ    rcCst||| tdid|d|d|dtjddd|d|d |d |d |d |d | d| d| d| d| d|\}}|jjS)a Set up & run a `Publisher`, and return a dictionary of document parts. Dictionary keys are the names of parts. Dictionary values are `str` instances; encoding is up to the client, e.g.:: parts = publish_parts(...) body = parts['body'].encode(parts['encoding'], parts['errors']) See the `API documentation`__ for details on the provided parts. Parameters: see `publish_programmatically()`. __ https://docutils.sourceforge.io/docs/api/publisher.html#publish-parts rrXrr!r NrYrr5rr)rr,r"rIrRrErr&)rrrrrrJ)rrXrrYrr5rr)rr,r"rIrRrEr_outputrr&r&r' publish_parts sJ    rc Cst||dtdid|d|d|dddddtjd|d |d |d |d d ddd|d|d| d| d| \} } | jS)z Set up & run a `Publisher` for programmatic use. Return a document tree. Parameters: see `publish_programmatically()`. NrrXrr rYr!rr5rr)rnullr,r"rIrRrErr&)rrr NullOutputr)rrXrrr5rr)r"rIrRrErrrr&r&r'publish_doctree2sJ     rc CsXtdd|tt|p|pdt|tj|d} | |||| d|| j |dS)u Set up & run a `Publisher` to render from an existing document tree data structure. For programmatic use with string output (`bytes` or `str`, cf. `publish_string()`). Note that ``document.settings`` is overridden; if you want to use the settings of the original `document`, pass ``settings=document.settings``. Also, new `document.transformer` and `document.reporter` objects are generated. Parameters: `document` is a `docutils.nodes.document` object, an existing document tree. Other parameters: see `publish_programmatically()`. This function is provisional because in Python 3 name and behaviour of the `io.StringOutput` class no longer match. Nr)rrrr!r"r) rrr rr DocTreeInputrrSr[r) rrYrr,r"rIrRrErrr&r&r'publish_from_doctreeOs    rrrrc CsLtjdtddt|||||d}|||||j| | | ||| | d}|S)u  Set up & run a `Publisher` for command-line-based file I/O (input and output file paths taken automatically from the command line). Also return the output as `bytes`. This is just like publish_cmdline, except that it uses io.BinaryFileOutput instead of io.FileOutput. Parameters: see `publish_programmatically()` for the remainder. - `argv`: Command-line argument list to use instead of ``sys.argv[1:]``. - `usage`: Usage string, output if there's a problem parsing the command line. - `description`: Program description, output for the "--help" option (along with command-line option descriptions). Deprecated. Use `publish_cmdline()` (works with `bytes` since Docutils 0.20). Will be removed in Docutils 0.24. zg"publish_cmdline_to_binary()" is obsoleted by "publish_cmdline()" and will be removed in Docutils 0.24.r/r0)r"r!r)r2r3rDrr6r)rr5rr)rr,r"rIrRrErrUr@rAr r!rrgr&r&r'publish_cmdline_to_binaryts   rrrc GsDtd|D]\}}|durtjd|d|d|dtddqdS)N)rrrz Argument "z1_name" will be removed in Docutils 2.0. Specify z name in the "z " argument.r0)zipr2r3r4) name_args componentname_argr&r&r'rs rcCsr|p|pd}|p | p d}| p| pd} t||| | ||d}|| |||||||||j|d}||fS)aH Set up & run a `Publisher` for custom programmatic use. Return the output (as `str` or `bytes`, depending on `destination_class`, writer, and the "output_encoding" setting) and the Publisher object. Internal: Applications should not call this function directly. If it does seem to be necessary to call this function directly, please write to the Docutils-develop mailing list . Parameters: * `source_class` **required**: The class for dynamically created source objects. Typically `io.FileInput` or `io.StringInput`. * `source`: Type depends on `source_class`: - If `source_class` is `io.FileInput`: Either a file-like object (must have 'read' and 'close' methods), or ``None`` (`source_path` is opened). If neither `source` nor `source_path` are supplied, `sys.stdin` is used. - If `source_class` is `io.StringInput` **required**: The input as either a `bytes` object (ensure the 'input_encoding' setting matches its encoding) or a `str` object. * `source_path`: Type depends on `source_class`: - `io.FileInput`: Path to the input file, opened if no `source` supplied. - `io.StringInput`: Optional. Path to the file or name of the object that produced `source`. Only used for diagnostic output. * `destination_class` **required**: The class for dynamically created destination objects. Typically `io.FileOutput` or `io.StringOutput`. * `destination`: Type depends on `destination_class`: - `io.FileOutput`: Either a file-like object (must have 'write' and 'close' methods), or ``None`` (`destination_path` is opened). If neither `destination` nor `destination_path` are supplied, `sys.stdout` is used. - `io.StringOutput`: Not used; pass ``None``. * `destination_path`: Type depends on `destination_class`: - `io.FileOutput`: Path to the output file. Opened if no `destination` supplied. - `io.StringOutput`: Path to the file or object which will receive the output; optional. Used for determining relative paths (stylesheets, source links, etc.). * `reader`: A `docutils.readers.Reader` instance, name, or alias. Default: "standalone". * `reader_name`: Deprecated. Use `reader`. * `parser`: A `docutils.parsers.Parser` instance, name, or alias. Default: "restructuredtext". * `parser_name`: Deprecated. Use `parser`. * `writer`: A `docutils.writers.Writer` instance, name, or alias. Default: "pseudoxml". * `writer_name`: Deprecated. Use `writer`. * `settings`: A runtime settings (`docutils.frontend.Values`) object, for dotted-attribute access to runtime settings. It's the end result of the `SettingsSpec`, config file, and option processing. If `settings` is passed, it's assumed to be complete and no further setting/config/option processing is done. * `settings_spec`: A `docutils.SettingsSpec` subclass or object. Provides extra application-specific settings definitions independently of components. In other words, the application becomes a component, and its settings data is processed along with that of the other components. Used only if no `settings` specified. * `settings_overrides`: A dictionary containing application-specific settings defaults that override the defaults of other components. Used only if no `settings` specified. * `config_section`: A string, the name of the configuration file section for this application. Overrides the ``config_section`` attribute defined by `settings_spec`. Used only if no `settings` specified. * `enable_exit_status`: Boolean; enable exit status at end of processing? rrr)r"rr!r)rrSrZr[r)rrrXr!r rYrr5rr)rr,r"rIrRrErrrgr&r&r'rs f      rrc Cstd|d|dt}z ttjdWntjy1}ztjd|dWYd}~nd}~wwt||ddS)Nz Generate zZ documents from standalone reStructuredText sources . rz(WARNING: Cannot set the default locale: z. )rrA) default_descriptionlocale setlocaleLC_ALLErrorrTstderrrvr)r documenttypedoc_pathrAer&r&r' rst2something!s rcCtddddS)NhtmlHTMLzuser/html.html#htmlrr&r&r&r'rst2html2rcCr)Nhtml4z XHTML 1.1zuser/html.html#html4css1rr&r&r&r' rst2html46rrcCr)Nhtml5HTML5zuser/html.html#html5-polyglotrr&r&r&r' rst2html5:rrcCr)NlatexLaTeXuser/latex.htmlrr&r&r&r' rst2latex>rrcCr)NmanpagezUnix manual (troff)zuser/manpage.htmlrr&r&r&r'rst2manBrrcCr)NodtzOpenDocument text (ODT)z user/odt.htmlrr&r&r&r'rst2odtFrrcCr)Nrzpseudo-XML (test)ref/doctree.htmlrr&r&r&r' rst2pseudoxmlJrrcCr)Ns5zS5 HTML slideshowzuser/slide-shows.htmlrr&r&r&r'rst2s5NrrcCr)NxetexzLaTeX (XeLaTeX/LuaLaTeX)rrr&r&r&r' rst2xetexRrrcCr)NxmlzDocutils-native XMLrrr&r&r&r'rst2xmlVrr)NNNNNNNNNNNNNNF) NNNNNNNNNNNNF)NNNNNNNFr)r)4r __future__r __docformat__rrrbrTr2docutilsrrrrrr r r docutils.frontendr docutils.readersr TYPE_CHECKINGtypingrdocutils.nodesrr default_usagerrrrrrrrBinaryFileOutputrrrrrrrrrrrrrrr&r&r&r's (    k "  * )  % , x