o bx@sfdZdZddlZddlZddlZddlZddlmZmZm Z m Z m Z m Z m Z ddlmZddlmZGdddZd Zd Zdd dd dd ddddddeefddZ    d ddZ    d!ddZde jddd dd dd dddddfddZde jdd dd dddddf ddZ    d"ddZdd dd dd ddddddeede jfddZddZdS)#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 ZreStructuredTextN) __version____version_details__ SettingsSpecioutilsreaderswriters) OptionParser)doctreec@seZdZdZddddejdejdfddZddZddZ d d Z  d*d d Z d dZ  d*ddZ ddZ  d+ddZd,ddZd,ddZd,ddZddZ   d-ddZd d!Zd"d#Zd$d%Zd&d'Zd(d)ZdS). PublisherzK A facade encapsulating the high-level logic of a Docutils system. Nc Csd|_ ||_ ||_ ||_ dD]} tt|| tr(Jdt|| | | fq||_ ||_ ||_ ||_ ||_ t |_dS)z Initial setup. If any of `reader`, `parser`, or `writer` are not specified, the corresponding ``set_...`` method should be called with a component name (`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 r r isinstancegetattrstrsource source_class destinationdestination_classsettingsrZ ErrorOutput_stderr) selfr r rrrrrrZ componentr1usr/lib/python3.10/site-packages/docutils/core.py__init__#s2 zPublisher.__init__cCs$t|}||||_|jj|_dS)zSet `self.reader` by name.N)rZget_reader_classr r )r reader_namer parser_nameZ reader_classrrr set_readerSs  zPublisher.set_readercCst|}||_dS)zSet `self.writer` by name.N)rZget_writer_classr)r writer_nameZ writer_classrrr set_writerYs  zPublisher.set_writercCsb|jdur |||j||jdur#|jjdur|j||jj|_|jdur/||dSdSN)r rr Z set_parserrr!)rrrr rrrset_components^s      zPublisher.set_componentscKsltjdtdd|r&|st}||_|}t|dkr&|ddkr&dg|_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 r r r)rr*r+ settings_specr/r)partsrrrsetup_option_parserhszPublisher.setup_option_parsercOsJttjdtd|j|i|WdS1swYdS)Nignore)category)r,catch_warningsfilterwarningsr.r4)rargskwargsrrr_setup_settings_parser{s $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. )r;Zget_default_valuesr)rr*r+r2r/r) option_parserrrr get_settingss  zPublisher.get_settingscCsD|jdur |r |ni}|dd|jd||d|dSdS)N tracebackT)r2r/r)rcopy setdefaultr=)rr2settings_overridesr/r)rrrprocess_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`). Nr&)r;sysargv parse_argsr)rrDr*r+r2r/r)r<rrrprocess_command_lines zPublisher.process_command_linecCs4|jdur |j|d|jdur|j|ddSdS)N) source_path)destination_path)r set_sourcerset_destination)rrGrHrrrset_ios   zPublisher.set_iocC:|dur |jj}n||j_|j|||jj|jjd|_dS)N)rrGencoding error_handler)r_sourcerZinput_encodingZinput_encoding_error_handlerr)rrrGrrrrI  zPublisher.set_sourcecCrL)N)rrHrMrN)rZ _destinationroutput_encodingoutput_encoding_error_handlerr)rrrHrrrrJrPzPublisher.set_destinationcCs4|jj|j|j|jj|j|jf|jjdSr") r transformerZpopulate_from_componentsrr r rrapply_transformsrrrrrTs 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. Nr&T )rrFrKpromptr readrr rrTrwriterZassemble_parts SystemExitcode Exceptionr>debugging_dumpsreport_ExceptionZreporterZ max_levelZexit_status_levelrCexit) rrDr*r+r2rAr/enable_exit_statusr_outputerrorZ exit_statusrrrpublishsR     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).0priorityZxclasspendingr:rrr s   z-Publisher.debugging_dumps..z ::: Pseudo-XML:Zraw_unicode_escape)rrZ dump_settingsprintrpprintpformat__dict__Zdump_internalsZdump_transformsrSZappliedZdump_pseudo_xmlencoderUrrrr]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+D on an empty linezuseful formatsrz Docutils z/ converting "z" into "zT". Call with option "--help" for more info. .. Waiting for source text (finish with z):rd) risattyrAttributeErrorosnamer Z supportedr IndexErrorrmr)rZeot_keyZ in_formatZ out_formatrrrrWs2    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%srdzExiting due to error. Use "--traceback" to diagnose. Please report errors to . Include "--traceback" output, Docutils version (z []rsz), Python version (rz5), your OS type & version, and the command line used.)rrZ SystemMessagereport_SystemMessageUnicodeEncodeErrorreport_UnicodeErrorrZ InputErrorrrY error_stringZ OutputErrorrmrrrCversionr0rrbrrrr^&s0      zPublisher.report_ExceptioncCs&td|jtjj|jf|jddS)Nz,Exiting due to level-%s (%s) system message.rd)rmlevelrZReporterlevelsrrrrrrz<s  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)objectstartendrrYrr}rrQrqrRrrCr~r0)rrbdatarrrr|As  zPublisher.report_UnicodeError)NNNN)NNNNN)NN)NNNNNNF)rgrf __qualname____doc__r FileInput FileOutputrrr!r#r4r;r=rBrFrKrIrJrTrcr]rWr^rzr|rrrrr sD 0         * 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)a% Set up & run a `Publisher` for command-line-based file I/O (input and output file paths taken automatically from the command line). Return the encoded string output also. 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). )rr/r`r r#rc)r rr rrr rr2rAr/r`rDr*r+pubrarrrpublish_cmdlineps rFcCs|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. Return the encoded string output also. Parameters: see `publish_programmatically`. rrrGrrrHr rr rrr rr2rAr/r`Nr)publish_programmaticallyrrr)rrGrrHr rr rrr rr2rAr/r`rarrrr publish_filesH    rcCs|tdidtjd|d|dtjddd|d|d |d |d |d |d |d| d| d| d| d| \}}|S)aB Set up & run a `Publisher` for programmatic use with string I/O. Return the encoded string or Unicode string output. For encoded string output, be sure to set the 'output_encoding' setting to the desired encoding. Set it to 'unicode' for unencoded Unicode string output. Here's one way:: publish_string(..., settings_overrides={'output_encoding': 'unicode'}) Similarly for Unicode string input (`source`):: publish_string(..., settings_overrides={'input_encoding': 'unicode'}) Parameters: see `publish_programmatically`. rrrGrrNrHr rr rrr rr2rAr/r`r)rr StringInput StringOutput)rrGrHr rr rrr rr2rAr/r`rarrrrpublish_stringsH   rcCs~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, and values are Unicode strings; encoding is up to the client. For programmatic use with string I/O. For encoded string input, be sure to set the 'input_encoding' setting to the desired encoding. Set it to 'unicode' for unencoded Unicode string input. Here's how:: publish_parts(..., settings_overrides={'input_encoding': 'unicode'}) Parameters: see `publish_programmatically`. rrGrrrNrHr rr rrr rr2rAr/r`r)rrrrr3)rrGrrHr rr rrr rr2rAr/r`rarrrr publish_partssH   rc Cs\t||d||tjd} | ||d| || | | ||| dd| j| d| jS)a Set up & run a `Publisher` for programmatic use with string I/O. Return the document tree. For encoded string input, be sure to set the 'input_encoding' setting to the desired encoding. Set it to 'unicode' for unencoded Unicode string input. Here's one way:: publish_doctree(..., settings_overrides={'input_encoding': 'unicode'}) Parameters: see `publish_programmatically`. N)r r rrrrnullr`) r rZ NullOutputr#rBrIrJrcr) rrGrr rr rrr2rAr/r`rrrrpublish_doctrees   rc Cs`tjdd} t| d|t|tj|d} |s|r| || |||| d|| j |dS)aJ Set up & run a `Publisher` to render from an existing document tree data structure, for programmatic use with string I/O. Return the encoded string output. 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. For encoded string output, be sure to set the 'output_encoding' setting to the desired encoding. Set it to 'unicode' for unencoded Unicode string output. Here's one way:: publish_from_doctree( ..., settings_overrides={'output_encoding': 'unicode'}) Parameters: `document` is a `docutils.nodes.document` object, an existing document tree. Other parameters: see `publish_programmatically`. r)rN)rrrr) r Readerr rZ DocTreeInputrr!rBrJrc) rrHrr rr2rAr/r`r 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). Return the encoded string output also. 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 rr rrr rr2rAr/r`rDr*r+rrrrarrrpublish_cmdline_to_binary7s  rcCs\t||| | ||d}||| | || |||||||||j|d}||fS)a@ Set up & run a `Publisher` for custom programmatic use. Return the encoded string output 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 string, either an encoded 8-bit string (set the 'input_encoding' setting to the correct encoding) or a Unicode string (set the 'input_encoding' setting to 'unicode'). * `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 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#rBrIrJrc)rrrGrrrHr rr rrr rr2rAr/r`rrarrrr]s d   r)NNNNNrNrNrNNNNF) NNNrNrNrNNNNF)NNrNNNNF)rZ __docformat__rnrvrCr,docutilsrrrrrrrZdocutils.frontendr Zdocutils.readersr r Z default_usageZdefault_descriptionrrrrrrrZBinaryFileOutputrrrrrrs $  E   % #   ( &