>WBȇLdZdZddlZddlZddlZddlZddlZddlZddlmZejdk\r ddl m Z ddlm Z n ddl m Z ddlmZ ddlZddlZddlZdd lmZmZmZmZejdk\reZd Zd Z d&d Z d&d Z d&dZ d&dZ d&dZ d&dZ d&dZ! d&dZ" d&dZ# d&dZ$ d&dZ% d&dZ& d&dZ'd'dZ(dZ)dZ*GddejVZ+GddejXZ,Gd d!ejZej\Z-Gd"d#e Z Gd$d%e/Z0y)(au Command-line and common processing for Docutils front-end tools. Exports the following classes: * `OptionParser`: Standard Docutils command-line processing. * `Option`: Customized version of `optparse.Option`; validation support. * `Values`: Runtime settings; objects are simple structs (``object.attribute``). Supports cumulative list settings (attributes). * `ConfigParser`: Standard Docutils config file processing. Also exports the following functions: * Option callbacks: `store_multiple`, `read_config_file`. * Setting validators: `validate_encoding`, `validate_encoding_error_handler`, `validate_encoding_and_error_handler`, `validate_boolean`, `validate_ternary`, `validate_threshold`, `validate_colon_separated_list`, `validate_comma_separated_list`, `validate_dependency_file`. * `make_paths_absolute`. * SettingSpec manipulation: `filter_settings_spec`. reStructuredTextN) SUPPRESS_HELPr)RawConfigParser)getcwd)getcwdu)locale_encoding SafeString ErrorOutput ErrorStringc|D]}t|j|d|jD]\}}t|j||y)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 attributekeys 1lib/python3.12/site-packages/docutils/frontend.pystore_multipler8sL0  y$/0lln+ U sE*+c |j|}|jj |y#t$r}|j|Yd}~ +    ng8H.H% ' M(('4D*Dg Ngx#^5 Orct|tr|S |j|jj S#t $rt d|zwxYw)z|Check/normalize boolean settings: True: '1', 'on', 'yes', 'true' False: '0', 'off', 'no','false', '' zunknown boolean value: "%s") isinstanceboolbooleansstriplowerKeyErrorr(r)s rvalidate_booleanrAys[ % A%%ekkm&9&9&;<< A7%?@@As *?Act|ts||S |j|jj S#t $r|cYSwxYw)zCheck/normalize three-value settings: True: '1', 'on', 'yes', 'true' False: '0', 'off', 'no','false', '' any other value: returned as-is. )r;r<r=r>r?r@r)s rvalidate_ternaryrCsP%%- %%ekkm&9&9&;<<  s*A AAc<t|}|dkr td|S)Nrz(negative value; must be positive or zero)intrr)s rvalidate_nonnegative_intrFs# JE qyCDD Lrc t|S#t$rB |j|jcYS#tt f$rt d|zwxYwwxYw)Nzunknown threshold: %r.)rEr thresholdsr?r@AttributeErrorr(r)s rvalidate_thresholdrJsg@5z @ @ ++EKKM: :.) @6>? ? @@s A6AAAct|ts|jd}|S|j}|j |jd|S)Nr3)r;listr5popextend)r*rr+r,r-lasts r$validate_colon_separated_string_listrPsG eT " C  Lyy{ TZZ_% Lrct|ts|g}|j}|jdDcgc]%}|j ds|j d'}}|j ||Scc}w)zHCheck/normalize list arguments (split at "," and strip whitespace). ,z )r;rLrMr5r>rN)r*rr+r,r-rOirs rvalidate_comma_separated_listrTsi eT " 99;D(, 4(8 N1AGGH:".asciibackslashreplacez[Invalid value "%s". Please specify 4 quotes (primary open/close; secondary open/close).)rTr5rIappendrencoder>len) r*rr+r,r- lc_quotesitemlangquotesmultichar_quotess rvalidate_smartquotes_localesrss# *'5-*7 IEI) I::c1-LD&!<<,  A %%F [A B#{{74FGHI I $(+), '    T "  IA#{{74FGHI I IsB""C%>'C%c| t}|D]I}||vs||}t|tr|Dcgc]}t||}}n|r t||}|||<Kycc}w)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`. N)rr;rLmake_one_path_absolute)pathdictkeys base_pathrrpaths rmake_paths_absoluterzs{H " (?SME%&%*,!0 4@,,.y%@!HSM",sAc|tjjtjj||SrZ)osryabspathjoin)rxrys rrurus$ 77??277<< 48 99rc t|}tdt|dD]}g}||D]y}|dDcgc](}|jdr|ddj dd*c}d}||vrB||j vr|j ||i|j |{t|||<t|Scc}w) aReturn a copy of `settings_spec` excluding/replacing some settings. `settings_spec` is a tuple of configuration settings with a structure described for 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.) rrgz--N-_r)rLrangerm startswithreplacerwrktuple) settings_specexcludersettingsrSnewoptsopt_spec opt_stringopt_names rfilter_settings_specrsM"H 1c(mQ '%  )H+31+&)44T:#12..sC8H7"7<<>)wx01x( )Gn % ?s-Cc(eZdZdZdZdZdZdZy)Valuesz Updates list attributes by extension rather than by replacement. Works in conjunction with the `OptionParser.lists` instance attribute. ctjj|g|i|t|dr |j$t j j|_yy)Nrecord_dependencies)optparser__init__hasattrrr[r\r]selfrrs rrzValues.__init__9sO  77734''/'/~~'D'D'FD $0rct|tr |j}|j}|jj D].}t ||s||vst||}|s$|||z }||=0|j|yrZ) r;r__dict__copylistsrwrgetattr _update_loose)r other_dictr+r*rs rr!z Values.update@s j& )#,,J__& $**//1 ,Gg&7j+@g.Z00E"7+  , :&rc:|j|jS)z Return a shallow copy of `self`.)defaults) __class__r)rs rrz Values.copyLs~~t}}~55rcNt||d t|||t||S)zUV.setdefault(n[,d]) -> getattr(V,n,d), also set D.n=d if n not in D or None. N)rr)rnamedefaults r setdefaultzValues.setdefaultPs, 4t $ , D$ (tT""rN)__name__ __module__ __qualname____doc__rr!rrrrrr2s G '6#rrcHeZdZejj ddgzZdZy)Option validator overridesc tjj|||||}|j}|r\|jr-t ||} |j |||}t||||jrt||jd|S#t $r)}tjd|dt|d}~wwxYw)z Call the validator function on applicable settings and evaluate the 'overrides' option. Extends `optparse.Option.process`. zError in option "z": N) rrprocessdestrr ExceptionOptionValueErrorr rr) rrrrrresultr* new_valuer s rrzOption.process\s ((sE66J)) ~~05 $wv FI 3~~5 !5"33 E 24555s B C$B==CN)rrrrrATTRSrrrrrrXs OO ! ![+$> >Errc eZdZdZgdZ dj Z dddddd Z d d d d d d d d d d Z e e jd dxse xsdZ dZddgddgifdddgdedfddgdddfddd 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~dgdddBfdddgdedfddgdedfdddgddedfddgdedfde dedddgde edfdezdgeedfdddgddddfddgdzeddfddgdzdd4edfdddgddifdddgddifedgddifedgddifedgddifedgddifedgddifedgddifedgdVdedfedgddiffZ dddddZ dZdZdej<ej>xrdej>zxsdde j@j dde jBdĝZ" ddńZ#dƄZ$dDŽZ%dȄZ&dɄZ'dʄZ(d˄Z)d̄Z*d̈́Z+d΄Z,y) OptionParsera Parser for command-line and library use. The `settings_spec` specification here and in other Docutils components are merged to build the set of command-line options and runtime settings for this process. Common settings (defined below) and component-specific settings must not conflict. Short options are reserved for common settings, and components are restrict to using long options. )z/etc/docutils.confz./docutils.confz ~/.docutilsz(info 1 warning 2 error 3 severe 4 none 5rgrrrj)infowarningr severenoneTF) 1onyestrue0offnofalser7NrhrizGeneral Docutils Optionsz'Specify the document title as metadata.z--titlez2Include a "Generated by Docutils" credit and link.z --generatorz-g store_true)actionrz"Do not include a generator credit.z--no-generator store_false generator)rrz2Include the date at the end of the document (UTC).z--datez-d store_constz%Y-%m-%d datestamp)rconstrzInclude the time & date (UTC).z--timez-tz%Y-%m-%d %H:%M UTCz'Do not include a datestamp of any kind.z--no-datestampz&Include a "View document source" link.z --source-linkz-sz3Use for a source link; implies --source-link.z --source-urlmetavarzz-Do not include a "View document source" link.z--no-source-linkcallback) source_link source_url)rr callback_argsz4Link from section headers to TOC entries. (default)z--toc-entry-backlinks 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-backlinksfootnote_backlinksz0Enable section numbering by Docutils. (default)z--section-numbering 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-classrkstrip_elements_with_classesz)rrrrzRemove all classes="" attributes from elements in the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.)z --strip-class strip_classeszReport system messages at or higher than : "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5"z--reportz-r 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--halt 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-statusexit_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 tracebackziSpecify 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-handlerzDSpecify text encoding and error handler for error output. Default: r3.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-attributeexpose_internals)rrrz--strict-visitor)_disable_config_source _destination _config_files)rgeneralz%prog (Docutils z [%s]z , Python rz, on )cvi|_ g|_ tjj|g|t dtj dd||js|j|_t|j|_ |ft|z|_ |j|j|j|xsi|r=|jds- |j!}|jj(yyy#t"$r$}|j%t'|Yd}~Fd}~wwxYw)z `components` is a list of Docutils components each containing a ``.settings_spec`` attribute. `defaults` is a mapping of setting default overrides. NN)width) option_classadd_help_option formatterr)r config_filesrrrrTitledHelpFormatterrversion_templaterLrelative_path_settingsr componentspopulate_from_componentsset_defaults_from_dictrget_standard_config_settingsrr r r)rrrread_config_filesrrconfig_settingsr s rrzOptionParser.__init__Os# (;&&   %t22<  ||00DL&*4+F+F&G#'E*$55 %%doo6 ##HN3 T]]3D%E ."&"C"C"E  ' '(@(@ A &F  . :e,-- .sD D8D33D8c|D] }||j}|jj|jtdt |dD]}|||dz\}}}|r)t j |||}|j|n|}|D]H\} } } |j| d| i| } | jddk(s0d|j| j<J|js|jj|j |D]7}|s|js|jj|j9y)aE For each component, first 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. NrrrrrkT)rrrNrrmr OptionGroupadd_option_group add_optiongetrrsettings_defaultsrr!settings_default_overrides) rr componentrrStitle description option_specgroup help_textoption_stringsrrs rrz%OptionParser.populate_from_componentsos[$ FI %33M  ' ' . .00 21c-0!4 F2?!A#2F/{K$00ukJE))%0 E;F77Y-U--~898068Fzz(+x726 6;;/ 7 ..MM(()D)DE F  F($ KIYAA $$Y%I%IJ Krcx tjdjtj}tj j}dtjvr ddl}|Dcgc]}|js||c}S#t$r|j }YowxYw#t$rd}YPwxYwcc}w)z:Return list of config files, from environment or standard.DOCUTILSCONFIGHOMErNc|SrZr)xs rz8OptionParser.get_standard_config_files..s1r) r|environr5pathsepr@standard_config_filesry expanduserpwd ImportErrorr>)rrexpandrfs rget_standard_config_filesz&OptionParser.get_standard_config_filess 6::&67==bjjIL##  # %$0=a1779q == 655L 6 %$ %=s/0B B%'B7= B7 B"!B"% B43B4ct}|jD]#}|j|j||%|SrZ)rrr!r)rrfilenames rrz)OptionParser.get_standard_config_settingssA8668 KH OOD99(CT J Krc2t}|j|||jj|jt j j|}t}t}|jD]h}|st|jxsd|jfzD]9}||vr|j||j|j!||;jt#|j$|j&||j$S)zAReturns a dictionary containing appropriate config file settings.r) ConfigParserreadrrN_filesr|rydirnamer6rrrconfig_section_dependenciesr-addr! get_sectionrzrr)r config_filerrxappliedrr sections rrz%OptionParser.get_config_file_settingss K&   /GGOOK0 %8 CI!)"G"G"M2N(779: Cg% G$ 2 27 ;TB  C C    t::I G   rc|j|\|_|_t|j|j |j |_|S)z/Store positional arguments as runtime settings.) check_argsrrrzrrrr)rrrs r check_valueszOptionParser.check_valuessA.2ood.C++FOOT-H-HI#00 rcdx}}|r|jd}|dk(rd}|r|jd}|dk(rd}|r|jd|r||k(r|jd||fS)NrrzMaximum 2 arguments allowed.z_Do not specify the same file for both source and destination. It will clobber the source file.)rMr )rrsource destinations rr.zOptionParser.check_argss}## XXa[F} ((1+Kc!"  JJ5 6 f + JJH I{""rc:|jj|yrZ)rr!rrs rrz#OptionParser.set_defaults_from_dicts X&rcRt|j}|j|_|S)z(Needed to get custom `Values` instances.)rrrrr4s rget_default_valueszOptionParser.get_default_valuess#$--(!%!2!2rc|j|gzD](}|jD]}|j|k(s|ccS*td|z)a Get an option by its dest. If you're supplying a dest which is shared by several options, it is undefined which option of those is returned. A KeyError is raised if there is no option with the supplied dest. zNo option with dest == %r.) option_groups option_listrr@)rrrrs rget_option_by_destzOptionParser.get_option_by_destsY''4&0 "E++ ";;$&!M " "3d:;;r)rNN)-rrrrrr5threshold_choicesrHr=rsysstderrr default_error_encoding$default_error_encoding_error_handlerrArrerJr9r1r_r#rrPrrrr-r[ __version____version_details__rplatformrrrrrrr/r.rr6r:rrrrrssQICHHJGAANJ@tD$eePH?$SZZ%)+I.=IAH,>( # a 3 +r a > $ L/?"A Ba /   L N a  ? T }z%02 3a  + T }&:%02 3a  4  '24 5a " 3 D !l1A$C D#a ( @  Y0 2)a , :  ^9 ; <-a 4 A " #"mg  5a < = !"me L N=a B 8  "m < >Ca H C ! "!a( * +Ia P < $ %'= A CQa V = !!?&6 8 9Wa ^ 3 # $"O < >_a d <  !0@ A Cea j C  ",< = ?ka p # ) )'D.B D  Eqa | #  .B D  E}a H K t *;'5),>@ AIa R A  -!(6 8 9Sa X @ d  &46 7Ya ^ 9 *"3\"# $68 9_a h C ,=1!-/ 0ia n 6  ):&9)*y+=? @oa z @ +,=MN P{a ~ - .]GD Fa B : .#3I KCa F > /lt)9; Qa Z B + ,-L M O[a b ,  %(W; = >ca l 5 - --L M  Oma z$%I K t $(5K; =  >wa B ( 0 1 , ,:7 9  :Ca N I  T,4!6 7Oa T 6 " #-E  Ua \ C ,Hh#-;KM N]a b 9  )4 6ca f - T Xv. 0ga l -9b/ :ma n ,- 3/? @oa r +,x.F Gsa t ,-,/G Hua v -.<0H Iwa x -.<0H Iya z 78'9< > ?{a @ ,-,/G HAa d MJ0-1$()-*.0Q0N$//#77@"8#?#??FCEF;;,,.q13<< A #B@K>>( !*#"' , section "Old-Format Configuration Files". zhUnable to read configuration file "%s": content not encoded as UTF-8. Skipping "%s" configuration file. cdtj|g|i|g|_ t|_yrZ)rrr%r _stderrrs rrzConfigParser.__init__s0  777 8"} Drclt|ttfvr|g}|D]} tj|dd} t jdkrtj|||ntj||||j|j j#||j%dr|j'||j)||y#t $rYwxYw#t$r>|jj|j||fz|jYwxYw)Nrrroptions)rstrunicoder&openr^r< version_inforreadfp read_fileUnicodeDecodeErrorrLwritenot_utf8_errorcloser%rk has_sectionhandle_old_configvalidate_settings)r filenamesr+r!fps rr$zConfigParser.read s  ?sGn ," I! #--dBA HHJ KK  x ( *&&x0  " "8] ;' <  &  ""4#6#6(H9M#MN  s$CAC, C)(C),AD32D3ctj|jt|d|j d}|j ds|j d|jD]r\}}||jvr5|j|\}}|j |s|j |nd}|}|j||r`|j|||t|jdy)NrrOr) warnings warn_explicit old_warningConfigDeprecationWarningr)rZ add_sectionr old_settings has_optionr6remove_section)rr!rOrrr,r*s rr[zConfigParser.handle_old_config%st//1I' ,""9- *   Y '!--/ 2JCd'''#'#4#4S#9 ''0$$W-#??7G4'51 2 I&rc|jD]}|j|D]} |j|}|jr<|j ||} |j |||||}|j||||jsj|j||jdy#t$rYwxYw#t $r(}td|d|dt|d|d| d}~wwxYw)zi Call the validator function and implement overrides on all applicable settings. )r,r-zError in config file "z ", section "[z]": z z = N) sectionsrOr:r@rrrrr r6r) rr!r+r,r*rrrr s rr\zConfigParser.validate_settings7s }} >G<<0 >*==gFF## HHWg6E 0$*$4$4#UM*.w%5%H HHWgy9##HHWf&6&6=) > > %0( (+e2D& /000s)B1C1 B=<B= C1 #C,,C1cB|jjddS)zW Transform '-' to '_' so the cmdline form of option names can be used. rr)r?r)r optionstrs r optionxformzConfigParser.optionxformSs ((c22rci}|j|r+|j|D]}|j||||<|S)zf Return a given section as a dictionary (empty if the section doesn't exist). )rZrOr)rr, section_dictrs rr)zConfigParser.get_sectionYsL    G $,,w/ A'+xx'@ V$ ArN) rrrrerbrXrr$r[r\rlr)rrrr#r#sG<E79LPKN E<0'$>83 rr#ceZdZdZy)rcz3Warning for deprecated configuration file features.N)rrrrrrrrcrces=rrc)NNrZ)1r __docformat__r|os.pathr<r`r&rrrS configparserrrr#r r[docutils.utilsdocutils.nodesdocutils.utils.error_reportingr r r r rPrQrr#r.r1r9rArCrFrJrPrTrXr_rersrzrurrrr SettingsSpec FutureWarningrcrrrrxsq 2#   "v,,$FFvG +/:>HL GK.9= A9= AE;?@GKHL  GKAE3=A =A!F"(:<##X__##LX__6y<8(((*?*?y}>r