
    k7i                       S r SSKJr  SrSSKrSSKrSSKrSSKrSSKrSSK	r	SSK
r
SSKJr  SSKJr  SSKrSSKJrJr  Sr\(       a1  SS	KJrJrJr  SS
KJrJrJrJr  SSKJrJrJr  SSKJr   " S S\5      r             S-S jr!        S.S jr"    S/         S0S jjr#    S/           S1S jjr$    S/           S1S jjr%    S/         S2S jjr&    S/         S3S jjr'    S/         S4S jjr(    S/         S4S jjr)    S/           S5S jjr*    S/           S5S jjr+    S/         S6S jjr,    S/         S7S jjr-    S/         S8S jjr.    S/         S9S jjr/    S/           S:S jjr0 S;     S<S  jjr1S=S! jr2      S>S" jr3 " S# S$\Rh                  5      r4 " S% S&\Rj                  5      r5 " S' S\Rl                  \R6                  5      r6 " S( S)\Rn                  5      r8 " S* S+\95      r:S?S, jr;g)@a*  
Command-line and common processing for Docutils front-end tools.

This module is provisional.
Major changes will happen with the transition from the
"optparse" module to "arparse" in Docutils 2.0 or later.

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. To be removed.

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.
    )annotationsreStructuredTextN)SUPPRESS_HELP)Path)ioutilsF)IterableMappingSequence)AnyClassVarLiteralProtocol)SettingsSpec_OptionTuple_SettingsSpecTuple)StrPathc                  <    \ rS rSr  S           SS jjrSrg)_OptionValidatorO   Nc                   g N )selfsettingvalueoption_parserconfig_parserconfig_sections         K/home/james-whalen/.local/lib/python3.13/site-packages/docutils/frontend.py__call___OptionValidator.__call__P   s         r   )NN)r   ConfigParser | Noner   
str | Noner   strr   r%   r   OptionParserreturnr   )__name__
__module____qualname____firstlineno__r!   __static_attributes__r   r#   r    r   r   O   sN     26)-		 /		 '				 		 (			 		 		r#   r   r'   c                    U H  n[        UR                  US5        M     UR                  5        H  u  pr[        UR                  Xr5        M     g)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`.

Deprecated. Will be removed with the switch to from optparse to argparse.
N)setattrvaluesitems)optionoptr   parserargskwargs	attributekeys           r    store_multipler9   \   s>     	y$/ lln
s* %r#   c                     UR                  U5      nUR                  R	                  WU5        g! [         a  nUR                  U5         SnAN=SnAff = f)z
Read a configuration file during option processing.  (Option callback.)

Deprecated. Will be removed with the switch to from optparse to argparse.
N)get_config_file_settings
ValueErrorerrorr0   update)r2   r3   r   r4   new_settingserrs         r    read_config_filerA   q   sN    66u= MMv.  Ss   0 
AAAc                    Uc  U nUS:X  a  [         R                  " S[        SS9  g  [        R                  " U5        U$ ! [
         a!    U (       a  SU  S3OSn[        U SU S35      ef = f)	N ztInput encoding detection will be removed and the special encoding values None and "" become invalid in Docutils 1.0.   
stacklevelz	setting "z":z unknown encoding: "")warningswarnFutureWarningcodecslookupLookupError)r   r   r   r   r   prefixs         r    validate_encodingrO      s     }{ )*7A	G Ce L  C,39WIR(VH$8qABBCs   A   +A+c                v    Uc  U n [         R                  " U5        U$ ! [         a    [        SU-  5      ef = f)Nzunknown encoding error handler: "%s" (choices: "strict", "ignore", "replace", "backslashreplace", "xmlcharrefreplace", and possibly others; see documentation for the Python ``codecs`` module))rK   lookup_errorrM   r   r   r   r   r   s        r    validate_encoding_error_handlerrS      sU     }5E" L  5, /445 	55s    8c                    SU;   aV  UR                  S5      u  pV[        U5        U(       a  UR                  X@S-   U5        O[        UR                  U S-   U5        OUn[        U5      $ )aT  Check/normalize encoding settings

Side-effect: if an error handler is included in the value, it is inserted
into the appropriate place as if it were a separate setting/option.

All arguments except `value` are ignored
(kept for compatibility with "optparse" module).
If there is only one positional argument, it is interpreted as `value`.
:_error_handler)splitrS   setr/   r0   rO   )r   r   r   r   r   encodinghandlers          r    #validate_encoding_and_error_handlerr[      sj      e|!KK,'0n8H.H%' M(('4D*DgNX&&r#   c                    Uc  U n[        U[        5      (       a  U$  [        R                  UR	                  5       R                  5          $ ! [         a    [        SU-  5      ef = f)a  Check/normalize boolean settings:

:True:  '1', 'on', 'yes', 'true'
:False: '0', 'off', 'no','false', ''

All arguments except `value` are ignored
(kept for compatibility with "optparse" module).
If there is only one positional argument, it is interpreted as `value`.
zunknown boolean value: "%s")
isinstanceboolr'   booleansstriplowerKeyErrorrM   rR   s        r    validate_booleanrc      sh     }%A$$U[[]%8%8%:;; A7%?@@As   .A A&c                    Uc  U n[        U[        5      (       d  Uc  U$  [        R                  UR	                  5       R                  5          $ ! [         a    Us $ f = f)a2  Check/normalize three-value settings:

:True:  '1', 'on', 'yes', 'true'
:False: '0', 'off', 'no','false', ''
:any other value: returned as-is.

All arguments except `value` are ignored
(kept for compatibility with "optparse" module).
If there is only one positional argument, it is interpreted as `value`.
)r]   r^   r'   r_   r`   ra   rb   rR   s        r    validate_ternaryre      s]      }%%-$$U[[]%8%8%:;; s   .A AAc                H    Uc  U n[        U5      nUS:  a  [        S5      eU$ )Nr   z(negative value; must be positive or zero)intr<   rR   s        r    validate_nonnegative_intrh     s/     }JEqyCDDLr#   c                    Uc  U n [        U5      $ ! [         aG     [        R                  UR	                  5          s $ ! [
        [        4 a    [        SU-  5      ef = ff = f)Nzunknown threshold: %r.)rg   r<   r'   
thresholdsra   rb   AttributeErrorrM   rR   s        r    validate_thresholdrl     ss     }@5z @	@**5;;=99.) 	@6>??	@@s   
 
A# A A# AA#c                    Uc  U n[        U[        5      (       d  UR                  S5      nU$ UR                  5       nUR	                  UR                  S5      5        U$ )NrU   )r]   listrW   popextend)r   r   r   r   r   lasts         r    $validate_colon_separated_string_listrr   &  sV     }eT""C  L yy{TZZ_%Lr#   c                   Uc  U n[        U[        5      (       d  U/nUR                  5       nUR                  S5       Vs/ s H+  ofR	                  S5      (       d  M  UR	                  S5      PM-     nnUR                  U5        U$ s  snf )zCheck/normalize list arguments (split at "," and strip whitespace).

All arguments except `value` are ignored
(kept for compatibility with "optparse" module).
If there is only one positional argument, it is interpreted as `value`.
,z 	
)r]   rn   ro   rW   r`   rp   )r   r   r   r   r   rq   ir1   s           r    validate_comma_separated_listrv   :  sy     } eT"" 99;D'+zz#K!''':JQWWWEK	LLL Ls   BBc                *   Uc  U nSnSnU(       d  gUR                  SS9nUS   R                  5       n US   n	X;  a  [        SU S	U S
35      eUS:X  a)  U	R                  5       n
X;  a  [        SU	 SU S
35      eU
n	X4$ ! [         a    Sn	 NWf = f)a=  Check "math-output" setting, return list with "format" and "options".

See also https://docutils.sourceforge.io/docs/user/config.html#math-output

Argument list for compatibility with "optparse" module.
All arguments except `value` are ignored.
If there is only one positional argument, it is interpreted as `value`.
)htmllatexmathmlmathjax)rC   latexmlttm	blahtexmlpandocr      )maxsplitr   rC   zUnknown math output format: "z",
    choose from .rz   zMathML converter "z!" not supported,
    choose from )rW   ra   
IndexErrorrM   )r   r   r   r   r   formatstex2mathml_convertersr0   formatoptions	converters              r    validate_math_outputr   U  s     }4GI[[![$FAY__F) 9% A--4IQ8 9 	9MMO	1 27) <11F0GqJ K K?  s   B BBc                V    Uc  U nU(       d  gUR                  S5      (       a  U$ US-   $ )Nz.//)endswithrR   s        r    validate_url_trailing_slashr   }  s2     }			s{r#   c                    Uc  U n [         R                  " U5      $ ! [         a    [         R                  " S 5      s $ f = fr   )r   DependencyListOSErrorrR   s        r    validate_dependency_filer     sD     }*##E** *##D))*s     A A c                    Uc  U n[        U5      nU H;  n[        R                  R                  U5      nXV:w  d  M)  [	        SU< SU< S35      e   U$ )NzInvalid class value z
 (perhaps z?))rv   docutilsnodesmake_idr<   )r   r   r   r   r   cls
normalizeds          r    validate_strip_classr     sZ     })%0E^^++C0
 #Z1 2 2 
 Lr#   c           	        Uc  U n[        U5      n/ nU H  n UR                  SS5      u  pxUR                  5       nUR                  S5      n	[        U	5      S:X  a  U	nO-[        U5      S:w  a  [	        SUR                  SS5      -  5      eUR                  Xx45        M     U$ ! [         a    UR                  U5         M  [         a    [	        SUR                  SS5      -  5      ef = f)a  Check/normalize a comma separated list of smart quote definitions.

Return a list of (language-tag, quotes) string tuples.

All arguments except `value` are ignored
(kept for compatibility with "optparse" module).
If there is only one positional argument, it is interpreted as `value`.
rU   r   z4Invalid value "%s". Format is "<language>:<quotes>".asciibackslashreplace   z[Invalid value "%s". Please specify 4 quotes
    (primary open/close; secondary open/close).)rv   rW   rk   appendr<   encoder`   len)
r   r   r   r   r   	lc_quotesitemlangquotesmultichar_quotess
             r    validate_smartquotes_localesr     s    })%0EI
	I::c1-LD !<<, A%%F[A O#{{74FGH I I 	$(+ , '  	 T" 	I A#{{74FGH I I	Is   B%%C+(C+c                   Uc  [         R                  " 5       nOF[        U5      n[        R                  S:X  a'  [        R                  SS S::  a  UR                  5       nU H{  nX0;   d  M
  X   n[        U[        [        45      (       a,  U Vs/ s H  n[        X%-  R                  5       5      PM      nnO"U(       a  [        X$-  R                  5       5      nX@U'   M}     gs  snf )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win32rD   )   	   )r   cwdsysplatformversion_infoabsoluter]   rn   tupler&   resolve)pathdictkeys	base_pathr8   r   paths         r    make_paths_absoluter     s     HHJ	O	<<7"s'7'7';v'E!**,I?ME%$//EJKUTin5578UKY_5578!SM  Ls   %C"c                    [         R                  " S[        SS9  [        R                  R                  [        R                  R                  X5      5      $ )NzKfrontend.make_one_path_absolute() will be removed in Docutils 2.0 or later.rD   rE   )rH   rI   DeprecationWarningosr   abspathjoin)r   r   s     r    make_one_path_absoluter      s:    MM .$4 77??277<<	899r#   c           	        [        U 5      n[        S[        U5      S5       H  n/ nX4    H  nUS    Vs/ s H0  nUR                  S5      (       d  M  USS R	                  SS5      PM2     snS   nX;   a  MN  XR                  5       ;   a  UR                  X(   5        Mv  UR                  U5        M     [        U5      X4'   M     [        U5      $ s  snf )	aR  Return 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.)
rD   r   r   z--N-_r   )rn   ranger   
startswithreplacer   r   r   )	settings_specexcluder   settingsru   newoptsopt_spec
opt_stringopt_names	            r    filter_settings_specr     s     M"H1c(mQ'&( H +31+8*5J%006 9
12..sC8*5889;H "<<>)w01x( $ Gn ( ?8s   CCc                  ^   ^  \ rS rSrSrSS	U 4S jjjr      S
S jrSS jrSS jrSr	U =r
$ )Valuesi(  zStorage 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 when switching to the "argparse" module.
c                   > [         R                  " S[        SS9  [        TU ]  US9  [        U SS 5      c  [        R                  " 5       U l        g g )Nz?frontend.Values class will be removed in Docutils 2.0 or later.rD   rE   defaultsrecord_dependencies)	rH   rI   r   super__init__getattrr   r   r   )r   r   	__class__s     r    r   Values.__init__1  sQ     2(Q	8 	(+4.5=',';';'=D$ >r#   c                ,   [        U[        5      (       a  UR                  n[        U5      nUR                  R                  5        H9  n[        X5      (       d  M  X1;   d  M  [        X5      nU(       d  M0  XAU   -  nX	 M;     U R                  U5        g r   )	r]   r   __dict__dictlistsr   hasattrr   _update_loose)r   
other_dictr   r   r   s        r    r>   Values.update:  s     j&))#,,J*%
$**//1Gt%%'*?.500E"+ 2 	:&r#   c                    [         R                  " 5          [         R                  " S[        S9  U R	                  U R
                  S9sSSS5        $ ! , (       d  f       g= f)z Return a shallow copy of `self`.ignorecategoryr   N)rH   catch_warningsfilterwarningsr   r   r   )r   s    r    copyValues.copyI  s=    $$&##H7IJ>>4==>9 '&&   2A
A c                J    [        XS5      c  [        XU5        [        X5      $ )z^Return ``self.name`` or ``default``.

If ``self.name`` is unset, set ``self.name = default``.
N)r   r/   )r   namedefaults      r    
setdefaultValues.setdefaultO  s&    
 4t$,D(t""r#   )r   r   )r   zdict[str, Any] | Noner(   None)r   zValues | Mapping[str, Any]r   r'   r(   r   r(   r   )r   r&   r   r   r(   r   )r)   r*   r+   r,   __doc__r   r>   r   r   r-   __classcell__r   s   @r    r   r   (  s@    > >'5'*' ':# #r#   r   c                     ^  \ rS rSr% Sr\R                  R                  SS/-   rS\S'   S\S'   S
U 4S jjr	          SU 4S jjr
S	rU =r$ )OptioniY  zXAdd validation and override support to `optparse.Option`.

Deprecated. Will be removed.
	validator	overridesr   r%   c                Z   > [         R                  " S[        SS9  [        TU ]  " U0 UD6  g )NzCThe frontend.Option class will be removed in Docutils 2.0 or later.rD   rE   )rH   rI   r   r   r   )r   r5   r6   r   s      r    r   Option.__init__d  s-     2(Q	8 	$)&)r#   c           	       > [         T	U ]  XX45      nU R                  nU(       ab  U R                  (       a*  [	        X65      n U R                  XbU5      n[        X6U5        U R                  (       a  [        X0R                  S5        U$ ! [
         a7  n[        R                  " SU< S[        R                  " U5      < 35      eSnAff = f)z|
Call the validator function on applicable settings and
evaluate the 'overrides' option.
Extends `optparse.Option.process`.
zError in option "z":
    N)r   processdestr   r   	ExceptionoptparseOptionValueErrorr   error_stringr/   r   )
r   r3   r   r0   r4   resultr   	new_valuer@   r   s
            r    r   Option.processj  s     V<))~~07 $wv FI
 3~~5 ! 7"33 467 77s   B	 	
C
2CC
r   )r5   r%   r6   r   r(   r   )
r3   r&   r   r   r0   r   r4   r'   r(   rg   )r)   r*   r+   r,   r   r   r   ATTRS__annotations__r   r   r-   r   r   s   @r    r   r   Y  sl    
 OO!![+$>>E*  %	
  r#   r   c                  |  ^  \ rS rSr% Sr/ SQrS\S'    SrS\S'    S	S
SSSS.rS\S'    SSSSSSSSSS.	r	S\S'    \
" \R                  SS5      =(       d    \R                  =(       d    SrS\S'   SrS\S'   SS/ SSS /S!S"04PS#S$/S!S%04PS&S'S(/S)\S*.4PS+S,/S-S.S/.4PS0S1S2/S3S4S5S6.4PS7S8S9/S3S:S5S6.4PS;S</S3SS5S6.4PS=S>/S?S@SA.4PSBSCSD/S)\S*.4PSESF/S!SG04PSHSI/SJ\SKSL.4PSMSN/SOS3SPSPSQ.4PSRSS/SOS3STSU.4PSVSW/SOS-SX.4PSYSZ/S)S\S[.4PS\S]/S^S-SX.4PS_S`/S)SaS\Sb.4PScSd/S-SaS/.4PSeSf/S)\S*.4PSgSh/S-SiS/.4PSjSk/SlSmSn\So.4PSpSq/SlSrSn\So.4PSsStSu/\S
SvSw\Sx.4PSySzS{/S3S	SvS6.4PS|S}S~/S3SSvS6.4PSS/\SSSw\S.4PSS/S3S	SS6.4PSS/\SSSw\S.4PSS/S)\S*.4PSS/S-SS/.4PSS/SSS.4PSS/S)S\S[.4PSS/SS-SX.4PSS/SS\S.4P\S/S\S.4PSS/SS\S.4P\S/S\S.4PS\ S3SS/S\\S.4P\S/\\S.4PSSS/SSSS.4PSS/S\SS.4PSS/SSSJ\S.4PSSS/SS04PSSS/SS04P\S/SS?04P\S/SS04P\S/SS)04P\S/SS)04P\S/SS)04P\S/SS)04P\S/SlS\S.4P\S/SS)04P74r SSSSS.r SrS\S'   SrS\R@                  < \RB                  =r"=(       a    S\" S3=(       d    S?< S\RF                  RI                  5       S   < S\RJ                  < S3r&S\S'       S       SU 4S jjjr'  SS jr(\)SS j5       r*SS jr+SS jr,SS jr-SS jr.SS jr/SS jr0Sr1U =r2$ )r'   i  a  
Settings 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 restricted to using long options.

Deprecated.
Will be replaced by a subclass of `argparse.ArgumentParser`.
)z/etc/docutils.confz./docutils.confz~/.docutilszClassVar[list[str]]standard_config_files)
info1warning2r=   3severe4none5zClassVar[tuple[str]]threshold_choicesr   rD   r   r      )r  r  r=   r	  r  zClassVar[dict[str, int]]rj   TF)	r  onyestrue0offnofalserC   zClassVar[dict[str, bool]]r_   rY   Nr   ClassVar[str]default_error_encodingr   $default_error_encoding_error_handlerzGeneral Docutils OptionszaOutput destination name. Obsoletes the <destination> positional argument. Default: None (stdout).z--output-pathz--outputmetavarz<destination>z'Specify the document title as metadata.z--titlez<title>z2Include a "Generated by Docutils" credit and link.z--generatorz-g
store_true)actionr   z"Do not include a generator credit.z--no-generatorstore_false	generator)r  r   z2Include the date at the end of the document (UTC).z--datez-dstore_constz%Y-%m-%d	datestamp)r  constr   zInclude the time & date (UTC).z--timez-tz%Y-%m-%d %H:%M UTCz'Do not include a datestamp of any kind.z--no-datestampzUBase directory for absolute paths when reading from the local filesystem. Default "".z--root-prefixrC   z<path>)r   r  z&Include a "View document source" link.z--source-linkz-sz3Use <URL> for a source link; implies --source-link.z--source-urlz<URL>z-Do not include a "View document source" link.z--no-source-linkcallback)source_link
source_url)r  r!  callback_argsz4Link from section headers to TOC entries.  (default)z--toc-entry-backlinkstoc_backlinksentry)r   r  r   r   z0Link from section headers to the top of the TOC.z--toc-top-backlinkstop)r   r  r   z+Disable backlinks to the table of contents.z--no-toc-backlinks)r   r  z6Link from footnotes/citations to references. (default)z--footnote-backlinks)r  r   r   z/Disable backlinks from footnotes and citations.z--no-footnote-backlinksfootnote_backlinksz0Enable section numbering by Docutils.  (default)z--section-numberingsectnum_xform)r  r   r   r   z&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-commentsstrip_commentszRemove all elements with classes="<class>" from the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.)z--strip-elements-with-classr   strip_elements_with_classesz<class>)r  r   r  r   zRemove all classes="<class>" attributes from elements in the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.)z--strip-classstrip_classeszReport system messages at or higher than <level>: "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5"z--reportz-rreport_levelz<level>)choicesr   r   r  r   z4Report 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 <level>.  Levels as in --report.  Default: 4 (severe).z--halt
halt_level)r.  r   r   r  r   z6Halt at the slightest problem.  Same as "--halt=info".z--strictzjEnable a non-zero exit status for non-halting system messages at or above <level>.  Default: 5 (disabled).z--exit-statusexit_status_levelz3Enable debug-level system messages and diagnostics.z--debugz Disable debug output.  (default)z
--no-debugdebugz-Send the output of system messages to <file>.z
--warningswarning_streamz<file>)r   r  z1Enable Python tracebacks when Docutils is halted.z--tracebackz%Disable Python tracebacks.  (default)z--no-traceback	tracebackzUSpecify the encoding and optionally the error handler of input text.  Default: utf-8.z--input-encodingz<name[:handler]>utf-8)r  r   r   z--input-encoding-error-handlerstrict)r   r   zWSpecify the text encoding and optionally the error handler for output.  Default: utf-8.z--output-encodingz--output-encoding-error-handlerzSSpecify text encoding and optionally the error handler for error output.  Default: r   z--error-encodingz-ez--error-encoding-error-handlerz<Specify the language (as BCP 47 language tag).  Default: en.z
--languagez-llanguage_codeenz<tag>)r   r   r  z)Write output file dependencies to <file>.z--record-dependencies)r  r   r   z6Read configuration settings from <file>, if it exists.z--configstring)r  typer  r!  z,Show this program's version number and exit.z	--versionz-Vr  versionz Show this help message and exit.z--helpz-hhelpz--id-prefixr   z--auto-id-prefix%z--dump-settingsz--dump-internalsz--dump-transformsz--dump-pseudo-xmlz--expose-internal-attributeexpose_internals)r  r   r   z--strict-visitor)_disable_config_source_destination_config_filesr   ztuple[str, ...]relative_path_settingsgeneralz%prog (Docutils z []z	, Python r   z, on )version_templatec           	       > 0 U l          / U l         SU l        [        R                  " S[
        SS9  [        TU ]  " U[        S[        R                  " SS9S.UD6  U R                  (       d  U R                  U l        U /UQ7U l        U R                  U R                  5        U R                  R!                  U=(       d    0 5        U(       aL  U R                  S	   (       d7   U R#                  5       nU R                  R!                  WR*                  5        g
g
g
! [$         a$  nU R'                  [)        U5      5         S
nANQS
nAff = f)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.
)r2  zThe frontend.OptionParser class will be replaced by a subclass of argparse.ArgumentParser in Docutils 2.0 or later.
  To get default settings, use frontend.get_default_settings().rD   rE   FN   )width)option_classadd_help_option	formatterr>  N)r   config_filesrB  rH   rI   r   r   r   r   r   TitledHelpFormatterr:  rF  
componentspopulate_from_componentsr   r>   get_standard_config_settingsr<   r=   r&   r   )	r   rO  r   read_config_filesr5   r6   config_settingsr@   r   s	           r    r   OptionParser.__init__o  s!    02
(');&9#L 1		.
 	 '-e#+#?#?b#I	*"(	* ||00DL594GJ4G%%doo6X^,T]]3D%E%"&"C"C"E MM  !9!9: &F  %

3s8$$%s   %D 
E'EEc                   U GH  nUc  M	  UR                   nU =R                  UR                  -  sl        [        S[        U5      S5       H  nX4US-    u  pVnU(       a)  [        R
                  " XU5      nU R                  U5        OU nU HJ  u  pnUR                  " U
SU	0UD6nUR                  S5      S:X  d  M1  SU R                  UR                  '   ML     UR                  (       d  M  U R                  R                  UR                  5        M     GM     U HD  nU(       d  M  UR                  (       d  M  U R                  R                  UR                  5        MF     g)aG  Collect 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.
Nr   r   r;  r  r   T)r   rB  r   r   r   OptionGroupadd_option_group
add_optiongetr   r   settings_defaultsr   r>   settings_default_overrides)r   rO  	componentr   ru   titledescriptionoption_specgroup	help_textoption_stringsr6   r2   s                r    rP  %OptionParser.populate_from_components  s:    $I %33M''9+K+KK'1c-0!42?!A#2F/K$00kJE))%0 E;F7Y"--~ 89 8068Fzz(+x726

6;;/	 <G
 ...MM(()D)DE 5 $& $IyYAAA$$Y%I%IJ $r#   c                :   S[         R                  ;   a1  [         R                  S   R                  [         R                  5      nOU R                  nU Vs/ s H8  o"R                  5       (       d  M  [         R                  R                  U5      PM:     sn$ s  snf )z:Return list of config files, from environment or standard.DOCUTILSCONFIG)r   environrW   pathsepr  r`   r   
expanduser)r   rM  fs      r    get_standard_config_files&OptionParser.get_standard_config_files  si     rzz)::&67==bjjIL44L/;I|!wwy%""1%|IIIs   B2#Bc                   [         R                  " 5          [         R                  " S[        S9  [	        5       nS S S 5        U R                  5        H$  nWR                  U R                  U5      U 5        M&     W$ ! , (       d  f       NH= f)Nr   r   )rH   r   r   r   r   rj  r>   r;   )r   r   filenames      r    rQ  )OptionParser.get_standard_config_settings  sg    $$&##H7IJxH ' 668HOOD99(CTJ 9 '&s   $A<<
B
c                   [        5       n[        5       n[        R                  " 5          [        R                  " S[
        S9  U =R                  UR                  X5      -  sl        [        5       nSSS5        U R                   H  nU(       d  M  [        UR                  =(       d    S5      UR                  4-    HG  nXc;   a  M
  UR                  U5        UR                  U5      (       d  M3  WR                  X&   U 5        MI     M     [!        WR"                  U R$                  [&        R(                  R+                  U5      5        UR"                  $ ! , (       d  f       N= f)zAReturns a dictionary containing appropriate config file settings.r   r   Nr   )ConfigParserrX   rH   r   r   r   rM  readr   rO  r   config_section_dependenciesr   addhas_sectionr>   r   r   rB  r   r   dirname)r   config_filer   appliedr   r\  sections          r    r;   %OptionParser.get_config_file_settings  s   $%$$&##H7IJ!3!3K!FFxH ' I!)"G"G"M2N(779:%G$ ,,W55OOM$:DA: ) 	H-- 77GGOOK8	:    # '&s   AE
E%c                    U R                  U5      u  Ul        Ul        [        UR                  U R
                  5        U R                  Ul        U$ )z/Store positional arguments as runtime settings.)
check_argsr?  r@  r   r   rB  rM  rA  )r   r0   r5   s      r    check_valuesOptionParser.check_values  sA    .2ood.C++FOOT-H-HI#00r#   c                    S =p#U(       a  UR                  S5      nUS:X  a  S nU(       a  UR                  S5      nUS:X  a  S nU(       a  U R                  S5        U(       a  X#:X  a  U R                  S5        X#4$ )Nr   r   zMaximum 2 arguments allowed.z_Do not specify the same file for both source and destination.  It will clobber the source file.)ro   r=   )r   r5   sourcedestinations       r    r{  OptionParser.check_args  sw    ##XXa[F}((1+Kc!"JJ56f+JJ H I""r#   c                    [         R                  " 5          [         R                  " S[        S9  [	        U R
                  5      nSSS5        U R                  Wl        U$ ! , (       d  f       N!= f)z(Needed to get custom `Values` instances.r   r   N)rH   r   r   r   r   r   rM  rA  )r   r   s     r    get_default_valuesOptionParser.get_default_values  sP    $$&##H7IJdmm,H ' "&!2!2	 '&s   /A  
A.c                    U R                   U /-    H,  nUR                   H  nUR                  U:X  d  M  Us  s  $    M.     [        SU-  5      e)z
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.
zNo option with dest == %r.)option_groupsoption_listr   rb   )r   r   r`  r2   s       r    get_option_by_destOptionParser.get_option_by_dest  sO     ''4&0E++;;$&!M , 1 3d:;;r#   )rO  rM  r   rB  r:  )r   NF)rO  Iterable[SettingsSpec]r   zMapping[str, Any] | NonerR  zbool | Noner(   r   )rO  r  r(   r   )r(   zSequence[StrPath]r   )rv  r&   r(   zdict[str, Any])r0   r   r5   	list[str]r(   r   )r5   r  r(   ztuple[str | None, str | None])r   r&   r(   r   )3r)   r*   r+   r,   r   r  r  r  rj   r_   r   r   stderrr   _locale_encodingr  r  rc   r9   r   rl   r[   r   rS   r   rA   rr   r   rZ  rB  r   r   __version____version_details__detailsr:  rW   r   rF  r   rP  classmethodrj  rQ  r;   r|  r{  r  r  r-   r   r   s   @r    r'   r'     s	   2. 
/O+ OG a!q!,EJ( E@ dD55+JH' J @ 	

J- 		 M 
 ;M(-L 	#`	 9J
')_)E
G `	 4+	9-
/`	
 ?$
L/?"A
B`	 /
L
N`	 ?T
}z%02
3`	 +T
}&:%02
3`	" 4
'24
5#`	(3
X
.
0)`	0 3D
!l1A$C
D1`	6 @
Y0
27`	: :
^9;
<;`	B A"
#"mg
 C`	J = 
!"me
L
NK`	P 8
 "m
<
>Q`	V C!
"!d(*
+W`	^ <$
%'=
A
C_`	d = 
!!?)9;
<e`	l 3#
$"O
<
>m`	r <
!0@
A
Cs`	x C
",<
=
?y`	~# )
)'D.BD	
E`	J# 
.BD	
EK`	VKt
*;'5),>@
AW`	` A
-!(6 8
9a`	f @d
&46
7g`	l9*"3\"#	$68
9m`	v C,=1!-/
0w`	|6
):&9)*y+=?
@}`	H @+,%57
8I`	N -.]GD
FO`	R :.#3I
KS`	V >/lt)9;
<W`	\ 2
{mL
N]`	`:
(W;=
>a`	j :;-L
M
Ok`	n%
(W;=
>o`	x ;<-L
M
Oy`	|**@)ADt
$(5K;=
>}`	F :;:79
:G`	L I
T,3!5
6M`	R 6"
#-E
S`	Z C,Hh#-;KM
N[`	` 9
)4
6a`	d -T
Xv.
0e`	j -9b/	:k`	l ,-	3/?	@m`	p +,x.F	Gq`	r ,-,/G	Hs`	t -.<0H	Iu`	v -.<0H	Iw`	x 78'9<>
?y`	~ ,-,/G	H`	cMH0 -1$()-*.0
 /1O0N 	00	0E7)1oKKA	'm 
 # 796:27(;3(;3(; %0(; (; (;TK&*K@ J J!0#$< <r#   c                     ^  \ rS rSr% SrSSSS.rS\S'    S	rS
\S'   SrS
\S'    S     SU 4S jjjr	SS jr
  SS jrSS jrSrU =r$ )rp  i  aB  Parser 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 writer
stylesheet)r  stylesheet_path)r  template)pep_stylesheetpep_stylesheet_pathpep_templatez$ClassVar[dict[str, tuple[str, str]]]old_settingsu  The "[option]" section is deprecated.
Support for old-format configuration files will be removed in Docutils 2.0.  Please revise your configuration files.  See <https://docutils.sourceforge.io/docs/user/config.html>, section "Old-Format Configuration Files".r  old_warningzhUnable to read configuration file "%s": content not encoded as UTF-8.
Skipping "%s" configuration file.
not_utf8_errorc                  > Ub  [         R                  " S[        SS9  / n[        U[        5      (       a  U/nU HB  n U[
        TU ]  USS9-  nSU ;   a  U R                  U5        Uc  M1  U R                  XB5        MD     U$ ! [         a1    [        R                  R                  U R                  XD4-  5         M  f = f)Nzafrontend.ConfigParser.read(): parameter "option_parser" will be removed in Docutils 2.0 or later.rD   rE   r4  )rY   r   )rH   rI   r   r]   r&   r   rq  UnicodeDecodeErrorr   r  writer  handle_old_configvalidate_settings)r   	filenamesr   read_okrm  r   s        r    rq  ConfigParser.read5  s     $MM 6 -< i%%"I!H57<7<CC D &&x0(&&x? "  & 

  !4!47K!KLs   B7B>=B>c                "   [         R                  " U R                  [        US5         [	        U S   5      nU R                  S5      (       d  U R                  S5        UR                  5        H{  u  p4X0R                  ;   a9  U R                  U   u  pVU R                  U5      (       d  U R                  U5        OSnUnU R                  XV5      (       a  Mi  U R                  XVU5        M}     U R                  S5        g ! [
         a    0 n Nf = f)Nr   r   rC  )rH   warn_explicitr  ConfigDeprecationWarningr   rb   rt  add_sectionr1   r  
has_optionrX   remove_section)r   rm  r   r8   r   rx  r   s          r    r  ConfigParser.handle_old_configP  s    t//1I'	,	4	?+G 	**Y'!--/JC'''#'#4#4S#9 ''00$$W-#??74451 * 	I&  	G	s   C? ?DDc                   U R                  5        H  nU R                  U5       H  n UR                  U5      nUR                  (       a5  U R                  X45      n UR	                  XFUXS9nU R                  X4U5        UR                  (       d  Mn  U R                  X5R                  S5        M     M     g! [         a     M  f = f! [         a3  n[        SU SU S[        R                  " U5       SU SU 3
5      eSnAff = f)zQ
Call the validator function and implement overrides on all applicable
settings.
)r   r   zError in config file "z", section "[z]":
    z	
        z = N)sectionsr   r  rb   r   rY  r   r<   r   r   rX   r   )	r   rm  r   rx  r   r2   r   r   r@   s	            r    r  ConfigParser.validate_settingse  s    }}G<<0*==gFF ## HHW6EI$*$4$4#M*. %5 %H	 HHWy9###HHW&6&6=% 1 '    % I(+A( L66=Y ?0020D/E F44;9Cw*H I IIs)   B8C	8
CC	
D.DDc                B    UR                  5       R                  SS5      $ )zg
Lowercase and transform '-' to '_'.

So the cmdline form of option names can be used in config files.
r   r   )ra   r   )r   	optionstrs     r    optionxformConfigParser.optionxform  s      ((c22r#   r   r   )r  zstr | Sequence[str]r   OptionParser | Noner(   r  )rm  r&   r(   r   )rm  r&   r   r'   r(   r   )r  r&   r(   r&   )r)   r*   r+   r,   r   r  r  r  r  rq  r  r  r  r-   r   r   s   @r    rp  rp    s    
 <E7:9L6 9
	4  5%NM  37+/  6'*>#>63 3r#   rp  c                      \ rS rSrSrSrg)r  i  z3Warning for deprecated configuration file features.r   N)r)   r*   r+   r,   r   r-   r   r#   r    r  r    s    =r#   r  c                     [         R                  " 5          [         R                  " S[        S9  [	        U 5      R                  5       sSSS5        $ ! , (       d  f       g= f)ad  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
r   r   N)rH   r   r   r   r'   r  )rO  s    r    get_default_settingsr    s>     
	 	 	"3EFJ'::< 
#	"	"r   )r2   optparse.Optionr3   r&   r   r   r4   r'   r5   r&   r6   r   r(   r   )
r2   r  r3   r&   r   r   r4   r'   r(   r   )NNNN)r   r&   r   r%   r   r  r   r$   r   r%   r(   r%   )r   r&   r   r%   r   r  r   r$   r   r%   r(   r&   )r   
str | boolr   r%   r   r  r   r$   r   r%   r(   r^   )r   r  r   r%   r   r  r   r$   r   r%   r(   zstr | bool | None)r   z	str | intr   r%   r   r  r   r$   r   r%   r(   rg   )r   zstr | list[str]r   r%   r   r  r   r$   r   r%   r(   r  )r   r&   r   r%   r   r  r   r$   r   r%   r(   ztuple[()] | tuple[str, str])r   r%   r   r%   r   r  r   r$   r   r%   r(   r&   )r   r%   r   r%   r   r  r   r$   r   r%   r(   zutils.DependencyList)r   r&   r   r%   r   r  r   r$   r   r%   r(   r  )r   z!str | list[str | tuple[str, str]]r   r%   r   r  r   r$   r   r%   r(   zlist[tuple[str, Sequence[str]]]r   )r   z"dict[str, list[StrPath] | StrPath]r   z
tuple[str]r   zStrPath | Noner(   r   )r   r   r   r   r(   r&   )r   r   r   r&   r   r   r(   r   )rO  r   r(   r   )<r   
__future__r   __docformat__rK   configparserr   r   os.pathr   rH   r   pathlibr   r   r   r   TYPE_CHECKINGcollections.abcr	   r
   r   typingr   r   r   r   r   r   r   docutils.ior   r   r9   rA   rO   rS   r[   rc   re   rh   rl   rr   rv   r   r   r   r   r   r   r   r   r   r   r'   RawConfigParserrp  rJ   r  r  r   r#   r    <module>r     sF  
.` #"    	  
  "   ;;77GG#
8 
+++ (+ 	+
 !+ +*/// */ 	/$ +/;?;?37	'%8 &9 '1	
 &4 !-1-1%) + +	
 # 2 !-1-1%)''' +' +	'
 #' '< *.:>:>26	A&A$7A %8A &0	A
 A4 *.:>:>26	&$7 %8 &0	
 ,6 26BFBF:>	$.,? -@ .8	
 #&$ ,0<@<@48	@(@&9@ ':@ (2	@
  @, !-1-1%)  + +	
 # , !-1-1%)  + +	
 # 8 .2>B>B6:	% *%(;% )<% *4	%
 :%R 59EIEI=A	'1/B 0C 1;	
 &)( 26BFBF:>	*$.*,?* -@* .8	*
 #7*& .2>B>B6:	 *(; )< *4	
 (0 !-1-1%)+2++ ++ +	+
 #+ -+` 59"("#1" ""4:#&$0 1@.#X__ .#b*X__ *ZK<8(((*?*? K<\r3<// r3j>} >=r#   