o b@sdZdZddlZddlZddlZddlmZddlZddlZddlZddl Z ddl Z ddl m Z m Z ddZ dd Z d6d d Z d6d d Z d6ddZ d6ddZ d6ddZ d6ddZ d6ddZ d6ddZ d6ddZ d6ddZ d6ddZ d6d d!Z d6d"d#Zd7d$d%Zd&d'Zd(d)ZGd*d+d+ejZGd,d-d-ej Z Gd.d/d/ej!e j"Z!Gd0d1d1ej#Z$Gd2d3d3e%Z&d4d5Z'dS)8a  Command-line and common processing for Docutils front-end tools. This module is provisional. Major changes will happen with the switch from the deprecated "optparse" module to "arparse". Applications should use the high-level API provided by `docutils.core`. See https://docutils.sourceforge.io/docs/api/runtime-settings.html. Exports the following classes: * `OptionParser`: Standard Docutils command-line processing. Deprecated. Will be replaced by an ArgumentParser. * `Option`: Customized version of `optparse.Option`; validation support. Deprecated. Will be removed. * `Values`: Runtime settings; objects are simple structs (``object.attribute``). Supports cumulative list settings (attributes). Deprecated. Will be removed. * `ConfigParser`: Standard Docutils config file processing. Provisional. Details will change. Also exports the following functions: Interface function: `get_default_settings()`. New in 0.19. Option callbacks: `store_multiple()`, `read_config_file()`. Deprecated. Setting validators: `validate_encoding()`, `validate_encoding_error_handler()`, `validate_encoding_and_error_handler()`, `validate_boolean()`, `validate_ternary()`, `validate_nonnegative_int()`, `validate_threshold()`, `validate_colon_separated_string_list()`, `validate_comma_separated_list()`, `validate_url_trailing_slash()`, `validate_dependency_file()`, `validate_strip_class()` `validate_smartquotes_locales()`. Provisional. Misc: `make_paths_absolute()`, `filter_settings_spec()`. Provisional. ZreStructuredTextN) SUPPRESS_HELP)ioutilscOs<|D] }t|j|dq|D] \}}t|j||qdS)z Store multiple values in `parser.values`. (Option callback.) Store `None` for each attribute named in `args`, and store the value for each key (attribute name) in `kwargs`. N)setattrvaluesitems)optionoptvalueparserargskwargs attributekeyr5usr/lib/python3.10/site-packages/docutils/frontend.pystore_multipleEs rc CsPz||}Wnty}z ||WYd}~nd}~ww|j||dS)zQ Read a configuration file during option processing. (Option callback.) N)get_config_file_settings ValueErrorerrorrupdate)rr r r Z new_settingserrrrrread_config_fileRsrcCs0zt|W|Stytd||fw)Nz$setting "%s": unknown encoding: "%s")codecslookup LookupErrorsettingr option_parser config_parserconfig_sectionrrrvalidate_encoding]s  r!cCs,zt|W|Stytd|w)Nzunknown encoding error handler: "%s" (choices: "strict", "ignore", "replace", "backslashreplace", "xmlcharrefreplace", and possibly others; see documentation for the Python ``codecs`` module))r lookup_errorrrrrrvalidate_encoding_error_handlergs  r#cCsnd|vr+|d\}}t|d|||||r!|||d|n t|j|d|n|}t||||||S)z Side-effect: if an error handler is included in the value, it is inserted into the appropriate place as if it was a separate setting/option. :Z_error_handler)splitr#setrrr!)rr rrr encodinghandlerrrr#validate_encoding_and_error_handlerts   r)cCs>t|tr|Sz |j|WStytd|w)z|Check/normalize boolean settings: True: '1', 'on', 'yes', 'true' False: '0', 'off', 'no','false', '' zunknown boolean value: "%s") isinstanceboolbooleansstriplowerKeyErrorrrrrrvalidate_booleans   r0cCsBt|ts |dur |Sz |j|WSty |YSw)zCheck/normalize three-value settings: True: '1', 'on', 'yes', 'true' False: '0', 'off', 'no','false', '' any other value: returned as-is. N)r*r+r,r-r.r/rrrrvalidate_ternarys r1cCst|}|dkr td|S)Nrz(negative value; must be positive or zero)intrrrrrvalidate_nonnegative_intsr3c CsNzt|WSty&z |j|WYSttfy%td|ww)Nzunknown threshold: %r.)r2r thresholdsr.r/AttributeErrorrrrrrvalidate_thresholds   r6cCs4t|ts |d}|S|}||d|S)Nr$)r*listr%popextend)rr rrr lastrrr$validate_colon_separated_string_lists  r;cCs:t|ts|g}|}dd|dD}|||S)zHCheck/normalize list arguments (split at "," and strip whitespace). cSs g|] }|dr|dqS)z )r-).0irrr  z1validate_comma_separated_list..,)r*r7r8r%r9)rr rrr r:rrrrvalidate_comma_separated_lists  rAcCs|sdS|dr |S|dS)Nz.//)endswithrrrrvalidate_url_trailing_slashs  rDcCs*zt|WStytdYSwN)rDependencyListOSErrorrrrrvalidate_dependency_files   rHcCsBt|||||}|D]}tj|}||krtd||fq |S)Nz$Invalid class value %r (perhaps %r?))rAdocutilsnodesZmake_idr)rr rrr cls normalizedrrrvalidate_strip_classs rMc Cst|||||}g}|D]T}z |dd\}}Wnty&||Yq ty6td|ddw|}|d} t| dkrI| }nt|dkrYtd|dd|||fq |S)z~Check/normalize a comma separated list of smart quote definitions. Return a list of (language-tag, quotes) string tuples.r$z4Invalid value "%s". Format is ":".asciibackslashreplacez[Invalid value "%s". Please specify 4 quotes (primary open/close; secondary open/close).)rAr%r5appendrencoder-len) rr rrr Z lc_quotesitemlangquotesZmultichar_quotesrrrvalidate_smartquotes_localess2        rXcsbdurt|D]$}||vr.||}t|tr#fdd|D}n|r*t|}|||<q dS)z Interpret filesystem path settings relative to the `base_path` given. Paths are values in `pathdict` whose keys are in `keys`. Get `keys` from `OptionParser.relative_path_settings`. Ncsg|]}t|qSr)make_one_path_absolute)r<path base_pathrrr>'sz'make_paths_absolute..)osgetcwdr*r7rY)Zpathdictkeysr\rr rr[rmake_paths_absolutes   r`cCstjtj||SrE)r]rZabspathjoin)r\rZrrrrY.srYcOst|}tdt|dD]4}g}||D]%}dd|dDd}||vr&q||vr4|||q||qt|||<q t|S)ajReturn a copy of `settings_spec` excluding/replacing some settings. `settings_spec` is a tuple of configuration settings (cf. `docutils.SettingsSpec.settings_spec`). Optional positional arguments are names of to-be-excluded settings. Keyword arguments are option specification replacements. (See the html4strict writer for an example.) cSs*g|]}|dr|ddddqS)z--rcN-_) startswithreplace)r<Z opt_stringrrrr>Bsz(filter_settings_spec..rNr)r7rangerTr_rRtuple) settings_specexcluderhsettingsr=ZnewoptsZopt_specopt_namerrrfilter_settings_spec2s     rocs8eZdZdZfddZddZddZdd ZZS) ValueszStorage for option values. Updates list attributes by extension rather than by replacement. Works in conjunction with the `OptionParser.lists` instance attribute. Deprecated. Will be removed. csDtjdtddtj|i|t|dddur t|_dSdS)Nz@frontend.Values class will be removed in Docutils 0.21 or later.rc stacklevelrecord_dependencies) warningswarnDeprecationWarningsuper__init__getattrrrFrsselfr r  __class__rrrxXszValues.__init__cCsht|tr|j}t|}|jD]}t||r,||vr,t||}|r,|||7}||=q||dSrE) r*rp__dict__dictlistsr_hasattrryZ _update_loose)r{ other_dictrrr rrrras   z Values.updatecCsHttjdtd|j|jdWdS1swYdS)z Return a shallow copy of `self`.ignorecategory)defaultsN)rtcatch_warningsfilterwarningsrvr}r~)r{rrrcopyms  $z Values.copycCs&t||ddurt|||t||S)zUV.setdefault(n[,d]) -> getattr(V,n,d), also set D.n=d if n not in D or None. N)ryr)r{namedefaultrrr setdefaultss  zValues.setdefault) __name__ __module__ __qualname____doc__rxrrr __classcell__rrr|rrpOs    rpcs<eZdZdZejjddgZfddZfddZZ S)Optionz`Add validation and override support to `optparse.Option`. Deprecated. Will be removed. validator overridescs&tjdtddtj|i|dS)NzDThe frontend.Option class will be removed in Docutils 0.21 or later.rcrq)rtrurvrwrxrzr|rrrxszOption.__init__c st||||}|j}|rH|jr>t||}z ||||}Wnty7}z td|t |fd}~wwt ||||j rHt ||j d|S)z Call the validator function on applicable settings and evaluate the 'overrides' option. Extends `optparse.Option.process`. zError in option "%s": %sN) rwprocessdestrry ExceptionoptparseZOptionValueErrorr error_stringrr) r{r r rr resultr new_valuerr|rrrs&   zOption.process) rrrrrrZATTRSrxrrrrr|rr{s  rc seZdZdZgdZ dZ dddddd Z d d d d d d d d d d Z e e j d dp1e j p1dZdZddgddgifdddgdedfddgdddfddd gd!d"d#d$fd%d&d'gd!d(d#d$fd)d*gd!dd#d$fd+d,d-gdedfd.d/gd0d1ifd2d3gd4ed5d6fd7d8gd9d!d:d:d;fdd?fd@dAgd9ddBfdCdDgddedEfdFdGgdHddBfdIdJgddKdedLfdMdNgddKdfdOdPgdedfdQdRgddSdfdTdUgdVdWdXedYfdZd[gdVd\dXedYfd]d^d_gedd`daedbfdcdddegd!dd`d$fdfdgdhgd!dd`d$fdidjgedkddaedlfdmdngd!ddkd$fdodpgedqddaedlfdrdsgdedfdtdugddvdfdwdxgdydzd{fd|d}gddedEfd~dgdddBfdddgdedfddgdedfdddgddedfddgdedfdeefddgdeedfdedgeedfdddgddddfddgdzeddfddgdzdd4edfdddgddifdddgddifedgddifedgddifedgddifedgddifedgddifedgddifedgdVdedfedgddifRfZ dddddZ dZdejejr for a source link; implies --source-link.z --source-urlmetavarzz-Do not include a "View document source" link.z--no-source-linkcallback)Z source_linkZ source_url)rrZ callback_argsz4Link from section headers to TOC entries. (default)z--toc-entry-backlinksZ toc_backlinksentry)rrrrz0Link from section headers to the top of the TOC.z--toc-top-backlinkstop)rrrz+Disable backlinks to the table of contents.z--no-toc-backlinks)rrz6Link from footnotes/citations to references. (default)z--footnote-backlinks)rrrz/Disable backlinks from footnotes and citations.z--no-footnote-backlinksZfootnote_backlinksz0Enable section numbering by Docutils. (default)z--section-numberingZ sectnum_xform)rrrrz&Disable section numbering by Docutils.z--no-section-numberingz/Remove comment elements from the document tree.z--strip-commentsz6Leave comment elements in the document tree. (default)z--leave-commentsstrip_commentszRemove all elements with classes="" from the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.)z--strip-elements-with-classrRZstrip_elements_with_classesz)rrrrzRemove all classes="" attributes from elements in the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.)z --strip-classZ strip_classeszReport system messages at or higher than : "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5"z--reportz-rZ report_levelz)choicesrrrrz4Report all system messages. (Same as "--report=1".)z --verbosez-vz3Report no system messages. (Same as "--report=5".)z--quietz-qzdHalt execution at system messages at or above . Levels as in --report. Default: 4 (severe).z--haltZ halt_level)rrrrrz6Halt at the slightest problem. Same as "--halt=info".z--strictzjEnable a non-zero exit status for non-halting system messages at or above . Default: 5 (disabled).z --exit-statusZexit_status_levelz3Enable debug-level system messages and diagnostics.z--debugz Disable debug output. (default)z --no-debugdebugz-Send the output of system messages to .z --warningswarning_streamz)rrz1Enable Python tracebacks when Docutils is halted.z --tracebackz%Disable Python tracebacks. (default)z--no-traceback tracebackzdSpecify the encoding and optionally the error handler of input text. Default: :strict.z--input-encodingz-iz)rrzlSpecify the error handler for undecodable characters. Choices: "strict" (default), "ignore", and "replace".z--input-encoding-error-handlerstrict)rrz^Specify the text encoding and optionally the error handler for output. Default: utf-8:strict.z--output-encodingz-outf-8)rrrzSpecify error handler for unencodable output characters; "strict" (default), "ignore", "replace", "xmlcharrefreplace", "backslashreplace".z--output-encoding-error-handlerzUSpecify text encoding and optionally error handler for error output. Default: %s:%s.z--error-encodingz-ezSSpecify the error handler for unencodable characters in error output. Default: %s.z--error-encoding-error-handlerz)rrrz)Write output file dependencies to .z--record-dependencies)rrrz6Read configuration settings from , if it exists.z--configstring)rtyperrz,Show this program's version number and exit.z --versionz-Vrversionz Show this help message and exit.z--helpz-hhelpz --id-prefixrrz--auto-id-prefix%z--dump-settingsz--dump-internalsz--dump-transformsz--dump-pseudo-xmlz--expose-internal-attributeZexpose_internals)rrrz--strict-visitor)_disable_config_source _destination _config_filesgeneralz(%%prog (Docutils %s%s, Python %s, on %s)z [%s]rrc si|_ g|_ dg|_tjdtddtj|tdt j ddd||j s,|j |_ |g|R|_ ||j |j|p?i|ro|jd sqz|}Wntye}z ||WYd}~nd}~ww|j|jdSdSdS) zSet up OptionParser instance. `components` is a list of Docutils components each containing a ``.settings_spec`` attribute. `defaults` is a mapping of setting default overrides. rztThe frontend.OptionParser class will be replaced by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.rcrqNN)width)Z option_classZadd_help_option formatterr)r config_filesrelative_path_settingsrtrurvrwrxrrZTitledHelpFormatterrversion_template componentspopulate_from_componentsrrget_standard_config_settingsrrr~)r{rrZread_config_filesr r Zconfig_settingsrr|rrrxs:    zOptionParser.__init__c Cs|D]a}|dur q|j}|j|jtdt|dD]G}|||d\}}}|r7t|||}||n|}|D]\} } } |j| d| i| } | ddkrWd|j | j <q;|j rb|j |j qq|D]}|rt|jrt|j |jqfdS)aoCollect settings specification from components. For each component, populate from the `SettingsSpec.settings_spec` structure, then from the `SettingsSpec.settings_defaults` dictionary. After all components have been processed, check for and populate from each component's `SettingsSpec.settings_default_overrides` dictionary. NrrdrrrRT)rkrr9rirTrZ OptionGroupZadd_option_group add_optiongetrrsettings_defaultsrrZsettings_default_overrides) r{r componentrkr=title descriptionZ option_specgroupZ help_textZoption_stringsr rrrrrs:    z%OptionParser.populate_from_componentscCs2dtjvrtjdtj}n|j}dd|DS)z:Return list of config files, from environment or standard.ZDOCUTILSCONFIGcSs g|] }|rtj|qSr)r-r]rZ expanduser)r<frrrr>r?z:OptionParser.get_standard_config_files..)r]environr%pathsepstandard_config_files)rKrrrrget_standard_config_filess z&OptionParser.get_standard_config_filescCs`ttjdtdt}Wdn1swY|D] }||||q"|S)Nrr)rtrrrvrprrr)r{rmfilenamerrrrs  z)OptionParser.get_standard_config_settingscCst}t}ttjdtd|j|||7_t}Wdn1s*wY|j D]*}|s7q2t |j pD I L OTW]` b dg inrw|    "'$ rcsXeZdZdZddddZ dZdZdfd d Zd d Zd dZ ddZ ddZ Z S)raZParser for Docutils configuration files. See https://docutils.sourceforge.io/docs/user/config.html. Option key normalization includes conversion of '-' to '_'. Config file encoding is "utf-8". Encoding errors are reported and the affected file(s) skipped. This class is provisional and will change in future versions. )pep_html writerZ stylesheet)rZstylesheet_path)rtemplate)Zpep_stylesheetZpep_stylesheet_pathZ pep_templatea The "[option]" section is deprecated. Support for old-format configuration files will be removed in Docutils 0.21 or later. Please revise your configuration files. See , section "Old-Format Configuration Files".zhUnable to read configuration file "%s": content not encoded as UTF-8. Skipping "%s" configuration file. Nc s|dur tjdtddg}t|tr|g}|D]6}z |tj|dd7}Wnty:tj |j ||fYqwd|vrD| ||durN| ||q|S)Nzbfrontend.ConfigParser.read(): parameter "option_parser" will be removed in Docutils 0.21 or later.rcrqr)r'options)rtrurvr*strrwrUnicodeDecodeErrorrrwritenot_utf8_errorhandle_old_configvalidate_settings)r{ filenamesrread_okrr|rrrHs(    zConfigParser.readcCst|jt|d|d}|ds|d|D],\}}||jvr7|j|\}}||s6||nd}|}| ||sH| |||q| ddS)Nrrr) rt warn_explicit old_warningConfigDeprecationWarning get_sectionr add_sectionr old_settings has_optionr&remove_section)r{rrrr rrrrrr`s$        zConfigParser.handle_old_configc Cs|D]e}||D]]}z||}Wn tyYq w|jr]|||}z |j|||||d}Wn"tyU}ztd|d|dt |d|d| d}~ww| ||||j rh| ||j dq qdS)zi Call the validator function and implement overrides on all applicable settings. )rr zError in config file "z ", section "[z]": z z = N) sectionsrrr/rrrrrrr&r) r{rrrrrr rrrrrrrs@     zConfigParser.validate_settingscCs|ddS)z Lowercase and transform '-' to '_'. So the cmdline form of option names can be used in config files. rerf)r.rh)r{ optionstrrrr optionxformszConfigParser.optionxformcCs6tjdtddzt||WStyiYSw)z Return a given section as a dictionary. Return empty dictionary if the section doesn't exist. Deprecated. Use the configparser "Mapping Protocol Access" and catch KeyError. zNfrontend.OptionParser.get_section() will be removed in Docutils 0.21 or later.rcrq)rtrurvrr/)r{rrrrrs  zConfigParser.get_sectionrE) rrrrrrrrrrrrrrrr|rr's rc@seZdZdZdS)rz3Warning for deprecated configuration file features.N)rrrrrrrrrsrcGsFttjdtdt|WdS1swYdS)a|Return default runtime settings for `components`. Return a `frontend.Values` instance with defaults for generic Docutils settings and settings from the `components` (`SettingsSpec` instances). This corresponds to steps 1 and 2 in the `runtime settings priority`__. __ https://docutils.sourceforge.io/docs/api/runtime-settings.html #settings-priority rrN)rtrrrvrr)rrrrget_default_settingss  $r)NNrE)(rZ __docformat__r configparserrrr]os.pathrrtrIrrrrr!r#r)r0r1r3r6r;rArDrHrMrXr`rYrorprrZ SettingsSpecRawConfigParserr FutureWarningrrrrrrsh0               $,%