
    Ki                    <   d Z ddlmZ dZddlZddlZddlZddlZddlZddl	Z	ddl
Z
ddlmZ ddlmZ ddlZddlmZmZ dZer1dd	lmZmZmZ dd
lmZmZmZmZ ddlmZmZmZ ddlmZ  G d de      Z 	 	 	 	 	 	 	 	 	 	 	 	 d-dZ!	 	 	 	 	 	 	 	 d.dZ"	 	 	 	 d/	 	 	 	 	 	 	 	 	 d0dZ#	 	 	 	 d/	 	 	 	 	 	 	 	 	 	 	 d1dZ$	 	 	 	 d/	 	 	 	 	 	 	 	 	 	 	 d1dZ%	 	 	 	 d/	 	 	 	 	 	 	 	 	 d2dZ&	 	 	 	 d/	 	 	 	 	 	 	 	 	 d3dZ'	 	 	 	 d/	 	 	 	 	 	 	 	 	 d4dZ(	 	 	 	 d/	 	 	 	 	 	 	 	 	 d4dZ)	 	 	 	 d/	 	 	 	 	 	 	 	 	 	 	 d5dZ*	 	 	 	 d/	 	 	 	 	 	 	 	 	 	 	 d5dZ+	 	 	 	 d/	 	 	 	 	 	 	 	 	 d6dZ,	 	 	 	 d/	 	 	 	 	 	 	 	 	 d7dZ-	 	 	 	 d/	 	 	 	 	 	 	 	 	 d8dZ.	 	 	 	 d/	 	 	 	 	 	 	 	 	 d9dZ/	 	 	 	 d/	 	 	 	 	 	 	 	 	 	 	 d:dZ0	 d;	 	 	 	 	 d<d Z1d=d!Z2	 	 	 	 	 	 d>d"Z3 G d# d$ejh                        Z4 G d% d&ejj                        Z5 G d' dejl                  ej6                        Z6 G d( d)ejn                        Z8 G d* d+e9      Z:d?d,Z;y)@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                  0    e Zd Z	 	 d	 	 	 	 	 	 	 	 	 	 	 ddZy)_OptionValidatorNc                    y N )selfsettingvalueoption_parserconfig_parserconfig_sections         ]/home/jay/workspace/scripts/.codegraph-venv/lib/python3.12/site-packages/docutils/frontend.py__call__z_OptionValidator.__call__P   s         )NN)r   ConfigParser | Noner   
str | Noner   strr   r#   r   OptionParserreturnr   )__name__
__module____qualname__r    r   r!   r   r   r   O   sI     26)-		 /		 '				 		 (			 		r!   r   r%   c                    |D ]  }t        |j                  |d        |j                         D ]  \  }}t        |j                  ||        y)a  
    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_multipler5   \   sL      0	y$/0lln +
UsE*+r!   c                    	 |j                  |      }|j                  j	                  |       y# t        $ r}|j                  |       Y d}~<d}~ww xY w)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errorr,   update)r.   r/   r   r0   new_settingserrs         r   read_config_filer=   q   sN    66u= MMv.  Ss   0 	AAAc                    || }|dk(  rt        j                  dt        d       y 	 t        j                  |       |S # t
        $ r | rd|  dnd}t        | d| d      w xY w)	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_encodingrK      s     }{ )*7A	G Ce L  C,39WIR(VH$8qABBCs	   ? %A$c                p    || }	 t        j                  |       |S # t        $ r t        d|z        w xY w)Nzunknown encoding error handler: "%s" (choices: "strict", "ignore", "replace", "backslashreplace", "xmlcharrefreplace", and possibly others; see documentation for the Python ``codecs`` module))rG   lookup_errorrI   r   r   r   r   r   s        r   validate_encoding_error_handlerrO      sU     }5E" L  5, /445 	55s    5c                    d|v rg|j                  d      \  }}t        |       |r!|j                  || dz   |       t        |      S t        |j                  | dz   |       t        |      S |}t        |      S )al  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)splitrO   setr+   r,   rK   )r   r   r   r   r   encodinghandlers          r   #validate_encoding_and_error_handlerrW      s      e|!KK,''0ng8H.H%' X&& M(('4D*DgN X&& X&&r!   c                    || }t        |t              r|S 	 t        j                  |j	                         j                            S # t        $ r t        d|z        w xY w)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KeyErrorrI   rN   s        r   validate_booleanr_      se     }%A$$U[[]%8%8%:;; A7%?@@As   .A Ac                    || }t        |t              s||S 	 t        j                  |j	                         j                            S # t        $ r |cY S w xY w)aN  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`.
    )rY   rZ   r%   r[   r\   r]   r^   rN   s        r   validate_ternaryra      sZ      }%%-$$U[[]%8%8%:;; s   .A	 	AAc                D    || }t        |      }|dk  rt        d      |S )Nr   z(negative value; must be positive or zero)intr8   rN   s        r   validate_nonnegative_intrd     s/     }JEqyCDDLr!   c                    || }	 t        |      S # t        $ rF 	 t        j                  |j	                            cY S # t
        t        f$ r t        d|z        w xY ww xY w)Nzunknown threshold: %r.)rc   r8   r%   
thresholdsr]   r^   AttributeErrorrI   rN   s        r   validate_thresholdrh     ss     }@5z @	@**5;;=99.) 	@6>??	@@s   
 	A  >A AA c                    || }t        |t              s|j                  d      }|S |j                         }|j	                  |j                  d             |S )NrQ   )rY   listrS   popextend)r   r   r   r   r   lasts         r   $validate_colon_separated_string_listrn   &  sS     }eT"C  L yy{TZZ_%Lr!   c                    || }t        |t              s|g}|j                         }|j                  d      D cg c]%  }|j	                  d      s|j	                  d      ' }}|j                  |       |S c c}w )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 	
)rY   rj   rk   rS   r\   rl   )r   r   r   r   r   rm   ir-   s           r   validate_comma_separated_listrr   :  st     } eT" 99;D'+zz#K!!''':JQWWWKEK	LLL Ls   A:A:c                   || }d}d}|sy|j                  d      }|d   j                         }	 |d   }	||vrt        d| d	| d
      |dk(  r(|	j                         }
|
|vrt        d|	 d| d
      |
}	||	fS # t        $ r d}	Y Tw xY w)aQ  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)r?   latexmlttm	blahtexmlpandocr      )maxsplitr   r?   zUnknown math output format: "z",
    choose from .rv   zMathML converter "z!" not supported,
    choose from )rS   r]   
IndexErrorrI   )r   r   r   r   r   formatstex2mathml_convertersr,   formatoptions	converters              r   validate_math_outputr   U  s     }4GI[[![$FAY__F) W9% A--4IQ8 9 	9MMO	11 27) <11F0GqJ K K7?  s   A> >BBc                @    || }|sy|j                  d      r|S |dz   S )Nz.//)endswithrN   s        r   validate_url_trailing_slashr   }  s/     }		s{r!   c                ~    || }	 t        j                  |      S # t        $ r t        j                  d       cY S w xY wr   )r   DependencyListOSErrorrN   s        r   validate_dependency_filer     sD     }*##E** *##D))*s    <<c                    || }t        |      }|D ]8  }t        j                  j                  |      }||k7  s(t	        d|d|d       |S )NzInvalid class value z
 (perhaps z?))rr   docutilsnodesmake_idr8   )r   r   r   r   r   cls
normalizeds          r   validate_strip_classr     sa     })%0E 2^^++C0
* #Z1 2 22
 Lr!   c           	        || }t        |      }g }|D ]  }	 |j                  dd      \  }}|j                         }|j                  d      }	t        |	      dk(  r|	}n,t        |      dk7  rt	        d|j                  dd      z        |j                  ||f        |S # t        $ r |j                  |       Y t        $ r t	        d|j                  dd      z        w xY w)a2  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`.
    rQ   r|   z4Invalid value "%s". Format is "<language>:<quotes>".asciibackslashreplace   z[Invalid value "%s". Please specify 4 quotes
    (primary open/close; secondary open/close).)rr   rS   rg   appendr8   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                   |t        j                         }nDt        |      }t        j                  dk(  r&t        j                  dd dk  r|j                         }|D ]o  }|| v s| |   }t        |t        t        f      r*|D cg c]  }t        ||z  j                                 }}n|rt        ||z  j                               }|| |<   q yc c}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win32r@   )   	   )r   cwdsysplatformversion_infoabsoluterY   rj   tupler$   resolve)pathdictkeys	base_pathr4   r   paths         r   make_paths_absoluter     s     HHJ	O	<<7"s'7'7';v'E!**,I "(?SME%$/EJKTin5578KKYu_5578!HSM" Ls   #Cc                    t        j                  dt        d       t        j                  j                  t        j                  j                  | |            S )NzKfrontend.make_one_path_absolute() will be removed in Docutils 2.0 or later.r@   rA   )rD   rE   DeprecationWarningosr   abspathjoin)r   r   s     r   make_one_path_absoluter      s<    MM .$4 77??277<<	4899r!   c           	        t        |       }t        dt        |      d      D ]  }g }||   D ]y  }|d   D cg c](  }|j                  d      r|dd j	                  dd      * c}d   }||v rB||j                         v r|j                  ||          i|j                  |       { t        |      ||<    t        |      S c c}w )	aj  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.)
    r@   r   r|   z--N-_r   )rj   ranger   
startswithreplacer   r   r   )	settings_specexcluder   settingsrq   newoptsopt_spec
opt_stringopt_names	            r   filter_settings_specr     s     M"H1c(mQ' %&(  
	)H +31+8&%006 #12..sC8 889;H 7"7<<>)wx01x(
	) Gn% ?8s   -Cc                  J     e Zd ZdZdd fdZ	 	 	 	 	 	 ddZd	dZd
dZ xZS )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 when switching to the "argparse" module.
    c                    t        j                  dt        d       t        |   |       t        | dd       t        j                         | _        y y )Nz?frontend.Values class will be removed in Docutils 2.0 or later.r@   rA   defaultsrecord_dependencies)	rD   rE   r   super__init__getattrr   r   r   )r   r   	__class__s     r   r   zValues.__init__1  sQ     2(Q	8 	(+4.5=',';';'=D$ >r!   c                
   t        |t              r|j                  }t        |      }|j                  j                         D ].  }t        | |      s||v st        | |      }|s$|||   z  }||= 0 | j                  |       y r   )	rY   r   __dict__dictlistsr   hasattrr   _update_loose)r   
other_dictr   r   r   s        r   r:   zValues.update:  s     j&)#,,J*%
$**//1 	,GtW%'Z*?g.Z00E"7+	, 	:&r!   c                    t        j                         5  t        j                  dt               | j	                  | j
                        cddd       S # 1 sw Y   yxY w)z Return a shallow copy of `self`.ignorecategoryr   N)rD   catch_warningsfilterwarningsr   r   r   )r   s    r   copyzValues.copyI  sF    $$& 	:##H7IJ>>4==>9	: 	: 	:s   7AAc                N    t        | |d      t        | ||       t        | |      S )znReturn ``self.name`` or ``default``.

        If ``self.name`` is unset, set ``self.name = default``.
        N)r   r+   )r   namedefaults      r   
setdefaultzValues.setdefaultO  s,    
 4t$,D$(tT""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)   __doc__r   r:   r   r   __classcell__r   s   @r   r   r   (  s6    >'5'*' ':#r!   r   c                       e Zd ZU dZej
                  j                  ddgz   Zded<   ded<   d fdZ	 	 	 	 	 	 	 	 	 	 d	 fdZ	 xZ
S )
Optionz`Add validation and override support to `optparse.Option`.

    Deprecated. Will be removed.
    	validator	overridesr   r#   c                \    t        j                  dt        d       t        |   |i | y )NzCThe frontend.Option class will be removed in Docutils 2.0 or later.r@   rA   )rD   rE   r   r   r   )r   r1   r2   r   s      r   r   zOption.__init__d  s-     2(Q	8 	$)&)r!   c           	     ~   t         	|   ||||      }| j                  }|r\| j                  r-t	        ||      }	 | j                  |||      }t        |||       | j                  rt        || j                  d       |S # t
        $ r3}t        j                  d|dt        j                  |            d}~ww xY w)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   r/   r   r,   r0   resultr   	new_valuer<   r   s
            r   r   zOption.processj  s     eVV<))~~07 $wv FI
 3~~5 ! 7"33 467 77s   B   	B<	.B77B<)r1   r#   r2   r   r&   r   )
r/   r$   r   r   r,   r   r0   r%   r&   rc   )r'   r(   r)   r   r   r   ATTRS__annotations__r   r   r   r   s   @r   r   r   Y  sl    
 OO!![+$>>E*  %	
  r!   r   c                  .    e Zd ZU dZg dZded<   	 dZded<   	 dd	d
dddZded<   	 dddddddddd	Zded<   	  e	e
j                  dd      xs ej                  xs dZded<   dZded<   ddg dddgd d!ifd"d#gd d$ifd%d&d'gd(ed)fd*d+gd,d-d.fd/d0d1gd2d3d4d5fd6d7d8gd2d9d4d5fd:d;gd2dd4d5fd<d=gd>d?d@fdAdBdCgd(ed)fdDdEgd dFifdGdHgdIedJdKfdLdMgdNd2dOdOdPfdQdRgdNd2dSdTfdUdVgdNd,dWfdXdYgd(dedZfd[d\gd]d,dWfd^d_gd(d`dedafdbdcgd,d`d.fdddegd(ed)fdfdggd,dhd.fdidjgdkdldmednfdodpgdkdqdmednfdrdsdtged	dudvedwfdxdydzgd2ddud5fd{d|d}gd2ddud5fd~dgedddvedfddgd2ddd5fddgedddvedfddgd(ed)fddgd,dd.fddgdddfddgd(dedZfddgdd,dWfddgddedfedgdedfddgddedfedgdedfde dddgdeedfedgeedfdddgddddfddgdeddfddgdddIedfdddgddifdddgddifedgdd>ifedgddifedgdd(ifedgdd(ifedgdd(ifedgdd(ifedgdkdedǜfedgdd(iffZ	 dddddɜZ	 dZded<   dZdej>                  ej@                  xZ!xr de! dНxs d>de
jD                  jG                         d   de
jH                  dԝZ%ded<   	 	 	 	 d	 	 	 	 	 	 	 d fdքZ&	 	 ddׄZ'e(dd؄       Z)ddلZ*ddڄZ+ddۄZ,dd܄Z-dd݄Z.ddބZ/ xZ0S )r%   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2r9   3severe4none5zClassVar[tuple[str]]threshold_choicesr|   r@   r   r      )r   r   r9   r   r   zClassVar[dict[str, int]]rf   TF)	r   onyestrue0offnofalser?   zClassVar[dict[str, bool]]r[   rU   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-prefixr?   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                x   i | _         	 g | _        	 d| _        t        j                  dt
        d       t        |   |t        dt        j                  d      d| | j                  s| j                  | _        | g|| _        | j                  | j                         | j                  j!                  |xs i        |rG| j                  d	   s7	 | j#                         }| j                  j!                  j*                         y
y
y
# t$        $ r$}| j'                  t)        |             Y d
}~Pd
}~ww xY w)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.
        )r'  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().r@   rA   FN   )width)option_classadd_help_option	formatterr3  N)r   config_filesr7  rD   rE   r   r   r   r   r   TitledHelpFormatterr/  r;  
componentspopulate_from_componentsr   r:   get_standard_config_settingsr8   r9   r$   r   )	r   rD  r   read_config_filesr1   r2   config_settingsr<   r   s	           r   r   z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 	D9D44D9c                   |D ]  }||j                   }| xj                  |j                  z  c_        t        dt        |      d      D ]  }|||dz    \  }}}|r)t	        j
                  | ||      }| j                  |       n| }|D ]H  \  }	}
} |j                  |
d|	i|}|j                  d      dk(  s0d| j                  |j                  <   J |j                  s| j                  j                  |j                           |D ]7  }|s|j                  s| j                  j                  |j                         9 y)ao  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   r0  r  r   T)r   r7  r   r   r   OptionGroupadd_option_group
add_optiongetr   r   settings_defaultsr   r:   settings_default_overrides)r   rD  	componentr   rq   titledescriptionoption_specgroup	help_textoption_stringsr2   r.   s                r   rE  z%OptionParser.populate_from_components  sU    $ 	FI %33M''9+K+KK'1c-0!4 F2?!A#2F/{K$00ukJE))%0 E;F 77Y-U--~ 89 8068Fzz(+x726

6;;/	7
 ..MM(()D)DEF	F& $ 	KIYAA$$Y%I%IJ	Kr!   c                &   dt         j                  v r1t         j                  d   j                  t         j                        }n| j                  }|D cg c]2  }|j                         st         j                  j                  |      4 c}S c c}w )z:Return list of config files, from environment or standard.DOCUTILSCONFIG)r   environrS   pathsepr   r\   r   
expanduser)r   rB  fs      r   get_standard_config_filesz&OptionParser.get_standard_config_files  sd     rzz)::&67==bjjIL44L/;I!qwwy""1%IIIs   B*!Bc                   t        j                         5  t        j                  dt               t	               }d d d        | j                         D ]#  }j                  | j                  |      |        % S # 1 sw Y   AxY w)Nr   r   )rD   r   r   r   r   r]  r:   r7   )r   r   filenames      r   rF  z)OptionParser.get_standard_config_settings  su    $$& 	 ##H7IJxH	  668 	KHOOD99(CTJ	K	  	 s   &A;;Bc                   t               }t               }t        j                         5  t        j                  dt
               | xj                  |j                  ||       z  c_        t               }ddd       | j                  D ]n  }|st        |j                  xs d      |j                  fz   D ]?  }||v r|j                  |       |j                  |      s+j                  ||   |        A p t!        j"                  | j$                  t&        j(                  j+                  |             |j"                  S # 1 sw Y   xY w)zAReturns a dictionary containing appropriate config file settings.r   r   Nr   )ConfigParserrT   rD   r   r   r   rB  readr   rD  r   config_section_dependenciesr   addhas_sectionr:   r   r   r7  r   r   dirname)r   config_filer   appliedr   rP  sections          r   r7   z%OptionParser.get_config_file_settings  s'   $%$$& 	 ##H7IJ!3!3K!FFxH	   		BI!)"G"G"M2N(779: Bg%G$ ,,W5OOM'$:DAB		B 	H-- 77GGOOK8	:    #	  	 s   AEEc                    | j                  |      \  |_        |_        t        |j                  | j
                         | j                  |_        |S )z/Store positional arguments as runtime settings.)
check_argsr4  r5  r   r   r7  rB  r6  )r   r,   r1   s      r   check_valueszOptionParser.check_values  sA    .2ood.C++FOOT-H-HI#00r!   c                    d x}}|r|j                  d      }|dk(  rd }|r|j                  d      }|dk(  rd }|r| j                  d       |r||k(  r| j                  d       ||fS )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.)rk   r9   )r   r1   sourcedestinations       r   rk  zOptionParser.check_args  s}    ##XXa[F}((1+Kc!"JJ56f+JJ H I{""r!   c                    t        j                         5  t        j                  dt               t	        | j
                        }ddd       | j                  _        |S # 1 sw Y   xY w)z(Needed to get custom `Values` instances.r   r   N)rD   r   r   r   r   r   rB  r6  )r   r   s     r   get_default_valueszOptionParser.get_default_values  sW    $$& 	-##H7IJdmm,H	- "&!2!2		- 	-s   1A!!A*c                    | j                   | gz   D ](  }|j                  D ]  }|j                  |k(  s|c c S  * t        d|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.
        zNo option with dest == %r.)option_groupsoption_listr   r^   )r   r   rT  r.   s       r   get_option_by_destzOptionParser.get_option_by_dest  sY     ''4&0 	"E++ ";;$&!M"	" 3d:;;r!   )r   NF)rD  Iterable[SettingsSpec]r   zMapping[str, Any] | NonerG  zbool | Noner&   r   )rD  rv  r&   r   )r&   zSequence[StrPath]r   )rg  r$   r&   zdict[str, Any])r,   r   r1   	list[str]r&   r   )r1   rw  r&   ztuple[str | None, str | None])r   r$   r&   r   )1r'   r(   r)   r   r   r   r  rf   r[   r   r   stderrr   _locale_encodingr  r  r_   r5   r   rh   rW   r   rO   r   r=   rn   r   rN  r7  r   r   __version____version_details__detailsr/  rS   r   r;  r   rE  classmethodr]  rF  r7   rl  rk  rq  ru  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                       e Zd ZU dZddddZded<   	 dZd	ed
<   dZd	ed<   	 d	 	 	 	 	 d fdZddZ		 	 ddZ
ddZ xZS )ra  aZ  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                t   |t        j                  dt        d       g }t        |t              r|g}|D ]A  }	 |t
        |   |d      z  }d| v r| j                  |       |0| j                  ||       C |S # t        $ r1 t        j                  j                  | j                  ||fz         Y w xY w)Nzafrontend.ConfigParser.read(): parameter "option_parser" will be removed in Docutils 2.0 or later.r@   rA   r)  )rU   r   )rD   rE   r   rY   r$   r   rb  UnicodeDecodeErrorr   rx  writer  handle_old_configvalidate_settings)r   	filenamesr   read_okr_  r   s        r   rb  zConfigParser.read5  s     $MM 6 -< i%"I! 
	@H57<7<CC D &&x0(&&x?
	@  & 

  !4!4(7K!KLs   A==7B76B7c                    t        j                  | j                  t        |d       	 t	        | d         }| j                  d      s| j                  d       |j                         D ]r  \  }}|| j                  v r5| j                  |   \  }}| j                  |      s| j                  |       nd}|}| j                  ||      r`| j                  |||       t | j                  d       y # t
        $ r i }Y w xY w)Nr   r   r8  )rD   warn_explicitr  ConfigDeprecationWarningr   r^   re  add_sectionr-   r  
has_optionrT   remove_section)r   r_  r   r4   r   ri  r   s          r   r  zConfigParser.handle_old_configP  s    t//1I'	,	4	?+G 	*Y'!--/ 		2JCd'''#'#4#4S#9 ''0$$W-#??7G4'51		2 	I&  	G	s   C/ /C=<C=c                   | j                         D ]  }| j                  |      D ]  }	 |j                  |      }|j                  r<| j                  ||      }	 |j	                  |||| |      }| j                  |||       |j                  sj| j                  ||j                  d         y# t        $ r Y w xY w# t        $ r2}t        d| d| dt        j                  |       d| d| 
      d}~ww xY w)zi
        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   ru  r^   r   rM  r   r8   r   r   rT   r   )	r   r_  r   ri  r   r.   r   r   r<   s	            r   r  zConfigParser.validate_settingse  s-    }} 	>G<<0 >*==gFF ## HHWg6EI$*$4$4#UM*.w %5 %H	 HHWgy9##HHWf&6&6=%>	>    % I(+A( L66=Y ?0020D/E F44;9Cw*H I IIs)   B1C 1	B=<B= 	C;	-C66C;c                B    |j                         j                  dd      S )z
        Lowercase and transform '-' to '_'.

        So the cmdline form of option names can be used in config files.
        r   r   )r]   r   )r   	optionstrs     r   optionxformzConfigParser.optionxform  s      ((c22r!   r   )r  zstr | Sequence[str]r   OptionParser | Noner&   rw  )r_  r$   r&   r   )r_  r$   r   r%   r&   r   )r  r$   r&   r$   )r'   r(   r)   r   r  r   r  r  rb  r  r  r  r   r   s   @r   ra  ra    s    
 <E7:9L6 9
	4  5%NM  37+/ 6'*>#>63r!   ra  c                      e Zd ZdZy)r  z3Warning for deprecated configuration file features.N)r'   r(   r)   r   r   r!   r   r  r    s    =r!   r  c                     t        j                         5  t        j                  dt               t	        |       j                         cddd       S # 1 sw Y   yxY w)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
    r   r   N)rD   r   r   r   r%   rq  )rD  s    r   get_default_settingsr    sG     
	 	 	" =3EFJ'::<= = =s   4AA)r.   optparse.Optionr/   r$   r   r   r0   r%   r1   r$   r2   r   r&   r   )
r.   r  r/   r$   r   r   r0   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&   rZ   )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&   rc   )r   zstr | list[str]r   r#   r   r  r   r"   r   r#   r&   rw  )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&   rw  )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   )rD  r   r&   r   )<r   
__future__r   __docformat__rG   configparserr   r   os.pathr   rD   r   pathlibr   r   r   r   TYPE_CHECKINGcollections.abcr	   r
   r   typingr   r   r   r   r   r   r   docutils.ior   r   r5   r=   rK   rO   rW   r_   ra   rd   rh   rn   rr   r   r   r   r   r   r   r   r   r   r   r%   RawConfigParserra  rF   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!   