U ZSh@sdZdZddlZddlZddlZddlZddlZddlmZm Z m Z m Z m Z m Z mZddlmZddlmZGdddZd Zd Zdd dd dd ddddddeefddZd7ddZd8ddZde jddd dd dd dddddfddZde jdd dd dddddf ddZd9ddZdd dd dd ddddddeede jfddZddZd:d!d"Z d#d$Z!d%d&Z"d'd(Z#d)d*Z$d+d,Z%d-d.Z&d/d0Z'd1d2Z(d3d4Z)d5d6Z*dS);a Calling the ``publish_*`` convenience functions (or instantiating a `Publisher` object) with component names will result in default behavior. For custom behavior (setting component options), create custom component objects first, and pass *them* to ``publish_*``/`Publisher`. See `The Docutils Publisher`_. .. _The Docutils Publisher: https://docutils.sourceforge.io/docs/api/publisher.html reStructuredTextN) __version____version_details__ SettingsSpecioutilsreaderswriters) OptionParser)doctreec@seZdZdZddddejdejdfddZddZddZ d d Z d*d d Z d dZ d+ddZ ddZd,ddZd-ddZd.ddZd/ddZddZd0ddZd d!Zd"d#Zd$d%Zd&d'Zd(d)ZdS)1 PublisherzK A facade encapsulating the high-level logic of a Docutils system. Nc Csvd|_||_||_||_dD],} tt|| trtdt|| | | fq||_||_ ||_ ||_ ||_ t |_dS)a Initial setup. If any of `reader`, `parser`, or `writer` are not specified, ``set_components()`` or the corresponding ``set_...()`` method should be called with component names (`set_reader` sets the parser as well). N)readerparserwriterzpassed string "%s" as "%s" parameter; pass an instance, or use the "%s_name" parameter instead (in docutils.core.publish_* convenience functions).)documentr rr isinstancegetattrstrAssertionErrorsource source_class destinationdestination_classsettingsrZ ErrorOutput_stderr) selfr rrrrrrr componentr@/root/rtd-docs/venv/lib/python3.8/site-packages/docutils/core.py__init__$s zPublisher.__init__cCs$t|}||||_|jj|_dS)zSet `self.reader` by name.N)rZget_reader_classr r)r reader_namer parser_nameZ reader_classrrr set_readerUs  zPublisher.set_readercCst|}||_dS)zSet `self.writer` by name.N)r Zget_writer_classr)r writer_nameZ writer_classrrr set_writer[s zPublisher.set_writercCs^|jdkr|||j||jdkrF|jjdkr<|j||jj|_|jdkrZ||dSN)r r"r set_parserrr$)rr r!r#rrrset_components`s      zPublisher.set_componentscKsltjdtdd|rL|st}||_|}t|dkrL|ddkrLdg|_t|j |j |j |f|d||d S) NzRPublisher.setup_option_parser is deprecated, and will be removed in Docutils 0.21.) stacklevelZ applicationZ applicationsT) componentsdefaultsZread_config_filesusage description) warningswarnDeprecationWarningrconfig_sectionsplitlenZconfig_section_dependenciesr rr r)rr.r/ settings_specr3r-partsrrrsetup_option_parserjs$zPublisher.setup_option_parserc Os:t(tjdtd|j||W5QRSQRXdS)Nignore)category)r0catch_warningsfilterwarningsr2r8)rargskwargsrrr_setup_settings_parser}s z Publisher._setup_settings_parsercKs$|j||||f|}||_|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. )r?get_default_valuesr)rr.r/r6r3r- option_parserrrr get_settingss  zPublisher.get_settingscCs@|jdkr<|r|ni}|dd|jf||d|dS)N tracebackT)r6r3)rcopy setdefaultrB)rr6settings_overridesr3r-rrrprocess_programmatic_settingss  z'Publisher.process_programmatic_settingscKs:|j||||f|}|dkr*tjdd}|||_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`). Nr*)r?sysargv parse_argsr)rrIr.r/r6r3r-rArrrprocess_command_lines zPublisher.process_command_linecCs0|jdkr|j|d|jdkr,|j|ddS)N) source_path)destination_path)r set_sourcerset_destination)rrLrMrrrset_ios   zPublisher.set_iocCs:|dkr|jj}n||j_|j|||jj|jjd|_dS)N)rrLencoding error_handler)r_sourcerZinput_encodingZinput_encoding_error_handlerr)rrrLrrrrNs zPublisher.set_sourcecCs||dkrT|jjr0|jjr0|jj|jjkr0td|jjdkrDd|j_|jjpR|jj}||j_|j|||jj|jjd|_dS)NziThe positional argument is obsoleted by the --output option. You cannot use them together.-)rrMrQrR)routputZ _destination SystemExitroutput_encodingoutput_encoding_error_handlerr)rrrMrrrrOs" zPublisher.set_destinationcCs4|jj|j|j|jj|j|jf|jjdSr%) r transformerZpopulate_from_componentsrr rrrapply_transformsrrrrrZs zPublisher.apply_transformsFc CsFd}zt|jdkr*|j|||||f|p&i|||j|j|j|j|_| |j |j|j } |j Wnxtk r} zd}| j} W5d} ~ XYnNtk r} z0|js|jjr||| d}d} W5d} ~ XYnX||r2|jr2|jjj|jjkr2t|jjjdn|rBt| | 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. NTr* )rrKrPpromptr readrrrrZrwriterZassemble_partsrVcode ExceptionrCdebugging_dumpsreport_ExceptionreporterZ max_levelZexit_status_levelrHexit) rrIr.r/r6rFr3enable_exit_statusrerUerror exit_statusrrrpublishsT   zPublisher.publishcCs|js dS|jjr8td|jdtt|jj|jd|jjrftd|jdtt|jj|jd|jj rtd|jdtd|jdttdd|jj j D|jd|jj rtd|jdt|j d |jddS) 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).0priorityZxclasspendingr>rrr s  z-Publisher.debugging_dumps..z ::: Pseudo-XML:Zraw_unicode_escape)rrZ dump_settingsprintrpprintpformat__dict__Zdump_internalsZdump_transformsrYZappliedZdump_pseudo_xmlencoder[rrrrbs6 zPublisher.debugging_dumpsc Csz|jr|jsWdSWntk r4YdSXtjdkrDdnd}d}d}z|jjd}|jjd}Wntt fk rYnXt 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):rj) risattyrAttributeErrorosnamer supportedr IndexErrorrsr)rZeot_keyZ in_formatZ out_formatrrrr]s   zPublisher.promptcCst|tjr||nt|tr.||nt|tjrR|j dt |nvt|tj rv|j dt |nRt dt ||jdt dt trdtdndd tjd d |jddS) Nz-Unable to open source file for reading: %s z2Unable to open destination file for writing: %s z%srjzExiting due to error. Use "--traceback" to diagnose. Please report errors to . Include "--traceback" output, Docutils version (z []ryz), Python version (rz5), your OS type & version, and the command line used.)rrZ SystemMessagereport_SystemMessageUnicodeEncodeErrorreport_UnicodeErrorrZ InputErrorrr_ error_stringZ OutputErrorrsrrrHversionr4rrgrrrrc1s0       zPublisher.report_ExceptioncCs&td|jtjj|jf|jddS)Nz,Exiting due to level-%s (%s) system message.rj)rslevelrZReporterZlevelsrrrrrrGs  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)objectstartendrr_rrrrWrwrXrrHrr4)rrgdatarrrrLs   zPublisher.report_UnicodeError)NNNN)NNNN)NNNNN)NN)NN)NN)NNNNNNF)rmrl __qualname____doc__r FileInput FileOutputrr"r$r'r8r?rBrGrKrPrNrOrZrirbr]rcrrrrrrr sP 1        *r z*%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. standalonerestructuredtext pseudoxmlTc Cs: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). )rr3rfr r'ri)r r rr!rr#rr6rFr3rfrIr.r/ publisherrUrrrpublish_cmdline{srFcCs6ttj||tj|||||||| | | | | |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()`. rrrLrrrMr r rr!rr#rr6rFr3rf)publish_programmaticallyrrr)rrLrrMr r rr!rr#rr6rFr3rfrUrrrr publish_files( rcCs6ttj||tjd|||||||| | | | | d\}}|S)uC 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()`. 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 Nr)rr StringInput StringOutput)rrLrMr r rr!rr#rr6rFr3rfrUrrrrpublish_strings( rcCs8t|||tjd||||||| | | | | |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 N)rrLrrrrMr r rr!rr#rr6rFr3rf)rrrrr7)rrLrrMr r rr!rr#rr6rFr3rfrUrrrr publish_partss( rc Cs6t|||ddtj||||dd||| | | d\} } | jS)z Set up & run a `Publisher` for programmatic use. Return a document tree. Parameters: see `publish_programmatically()`. Nnull)rrLrrrMrr r rr!rr#rr6rFr3rf)rrZ NullOutputr)rrLrr r rr!rr6rFr3rf_outputrrrrpublish_doctrees(  rc Cs`tjdd} t| d|t|tj|d} |s:|r:| || |||| 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. r)r!N)rrrrf) r Readerr rZ DocTreeInputrr$rGrOri) rrMrr#rr6rFr3rfr rrrrpublish_from_doctrees   rc Cs<t|||||d}|||||j| | | ||| | d}|S)a 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). )rrrr)r r rr!rr#rr6rFr3rfrIr.r/rrrrUrrrpublish_cmdline_to_binary?s rcCs\t||| | ||d}||| | || |||||||||j|d}||fS)a^ 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. Applications should not need to 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` object. * `reader_name`: Name or alias of the Reader class to be instantiated if no `reader` supplied. * `parser`: A `docutils.parsers.Parser` object. * `parser_name`: Name or alias of the Parser class to be instantiated if no `parser` supplied. * `writer`: A `docutils.writers.Writer` object. * `writer_name`: Name or alias of the Writer class to be instantiated if no `writer` supplied. * `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? )rrrr)r r'rGrNrOri)rrrLrrrMr r rr!rr#rr6rFr3rfrrUrrrrese    rrycCs4d|d|dt}ttjdt||ddS)Nz Generate zZ documents from standalone reStructuredText sources . ry)r#r/)default_descriptionlocale setlocaleLC_ALLr)rZ documenttypeZdoc_pathr/rrr rst2somethings rcCstddddS)NhtmlHTMLzuser/html.html#htmlrrrrrrst2htmlsrcCstddddS)NZhtml4z XHTML 1.1zuser/html.html#html4css1rrrrr rst2html4srcCstddddS)Nhtml5ZHTML5zuser/html.html#html5-polyglotrrrrr rst2html5srcCstddddS)NlatexZLaTeXuser/latex.htmlrrrrr rst2latexsrcCstddddS)NZmanpagezUnix manual (troff)zuser/manpage.htmlrrrrrrst2mansrcCstddddS)NZodtzOpenDocument text (ODT)z user/odt.htmlrrrrrrst2odtsrcCstddddS)Nrzpseudo-XML (test)ref/doctree.htmlrrrrr rst2pseudoxmlsrcCstddddS)NZs5zS5 HTML slideshowzuser/slide-shows.htmlrrrrrrst2s5srcCstddddS)NZxetexzLaTeX (XeLaTeX/LuaLaTeX)rrrrrr rst2xetexsrcCstddddS)NxmlzDocutils-native XMLrrrrrrrst2xml sr)NNNNNrNrNrNNNNF) NNNrNrNrNNNNF)NNrNNNNF)ry)+r __docformat__rrtr|rHr0Zdocutilsrrrrrrr Zdocutils.frontendr Zdocutils.readersr r Z default_usagerrrrrrrrZBinaryFileOutputrrrrrrrrrrrrrrrrrs $  O   & &  % &t