+ VBix *a0t$Rt^RIHtRt^RIt^RIt^RIt^RIt^RI t ^RI t ^RI t ^RI H t Ht^RIHtHt^RIHtHt^RIHtRt]'dD^R IHtHtHt^R IHtHtHtHt^R I H!t!^R IH"t"^R I#H$t$]]PJ.R3,t&R]'R&!RR]4t(!RR]4t)!RR4t*!RR]4t+!RR]+4t,!RR]+4t-!RR]+4t.RRlt/R R!lt0R"R#lt1!R$R%]4t2R&R'lt3R(t4R)R*lt5RUR+R,llt6R-R.lt7R/R0lt8RUR1R2llt9R3R4lt:R5R6lt;R7R8ltR=R>lt?R?R@lt@RARBltARCRDltBRE^RF^RG^RH^RI^RJ^/tCRKRLltDRMRNltERORPltFRURQRRlltG!RSRT4tHR#)Vz: Miscellaneous utilities for the documentation utilities. ) annotationsreStructuredTextN)PurePathPath)ApplicationError DataError)ionodes)unescapeF)CallableSequenceIterable)AnyFinalLiteralTextIO) TypeAlias)StrPath)Valuesr _ObserverFuncc"]tRt^(tRRltRtR#) SystemMessagec$V^8dQhRRRRRR/#)system_messagenodes.system_messagelevelintreturnNone)formats"?LF;'!%%h7%%fd3 : % *#77 v8NO !'-8$%)6" h 4""7<$,<%<(, E(:<0:< ;;;E%6%66#5D$i!mQ99T!W"Q EJJ77$:<@AB B71:$$&DD<(#$ r%c$V^8dQhRRRRRR/#)rrrrrrrr )r!s"r"r#r#Qs$  &@ 'G , r%c 2/pVF?wr4W,pVf \V4hW29d\RV,4hV!V4W#&KA V# \\3d<pTP RT: RT: RRP TP 4: 24hRp?ii;i)a) Return a mapping of option names to values. :Parameters: - `option_list`: A list of (name, value) pairs (the output of `extract_options()`). - `options_spec`: Dictionary mapping known option names to a conversion function such as `int` or `float`. :Exceptions: - `KeyError` for unknown option names. - `DuplicateOptionError` for duplicate options. - `ValueError` for invalid option values (raised by conversion function). - `TypeError` for invalid option value types (raised by conversion function). Nzduplicate option "%s"z (option: "z "; value: z)  )KeyErrorr ValueError TypeError __class__joinr{)rroptionsrvalue convertordetails&& r"rrQs(G"  &  4. ?&'>'EF F K%e,GM# NI& K""&*E388FKK3H$JK K Ks A  B6BBc]tRtRtRtR#)NameValueErroritr Nr4r r%r"rrtsr%rc V^8dQhRRRR/#)rpathzstr | bytes | NonerrGr )r!s"r"r#r#wsnr%cT\V\4'dV#VfR#VP\P!4R4pV# \ d\ RT: 24h\d=TPRR4pT# \dTPRR4pT#i;ii;i)z Ensure `path` is Unicode. Return `str` instance. Decode file/path string in a failsafe manner if not already done. Deprecated. Will be removed in Docutils 1.0. strictz/`path` value must be a String or ``None``, not utf-8rJreplace)rMrGdecodesysgetfilesystemencodingrprUnicodeDecodeError)rs&r" decode_pathrws$  | 3{{3446A K * $x)* * 3 3;;w1D K" 3;;w 2D K 33s/%A"B'*B',BB#B'"B##B'cL.pV'EdVPR4pVR8Xd \R4hVRVP4pV^8Xg V'g \R4hW^,RP4pV'g\RV R24hV^,R9dVPV^,^4pVR8Xd\RV R V^, R 24h\ V4V^,8d=W^,,P4'd\RV R V^, R 24hV^VpW^,RP4pM;VPR 4pVR8XdTpRpMVRVpW^,RP4pVP VP 4V34EKV#)z Return a list of (name, value) from a line of the form "name=value ...". :Exception: `NameValueError` for invalid input (missing name, missing data, bad quotes, etc.). =z missing "="Nz!missing attribute name before "="zmissing value after "z="z'"z attribute "z" missing end quote ()z " end quote (z) not followed by whitespacerrrK)findrstriplstriprrWr)riattlist equals_indexattnameendquote_indexr space_indexs& r"extract_name_valuersG $yy~ 2  / /} %++- 1 G !DE ENO$++- #8 !DE E 7e !YYtAw2N#$#G9,A$q'!LNND NQ..!+,2244${7)<))-a 1M&OPP.)Dq()*113D))C.Kb L[)MN+224 ./ Nr%c$V^8dQhRRRRRR/#)r source_pathrsettingsrrr6r )r!s"r"r#r#s!gHr%c \WPVPVPVPVP VP R7pV#)z Return a new Reporter object. :Parameters: `source` : string The path to or description of the source text of the document. `settings` : optparse.Values object Runtime settings. )rBrCrErF)r6r@rAwarning_streamrCerror_encodingerror_encoding_error_handler)rrreporters&& r" new_reporterrsG**H,?,?&&hnn((;; =H Or%c$V^8dQhRRRRRR/#)rrrrz Values | Nonerznodes.documentr )r!s"r"r#r#s"""g""$"r%c^RIHpVfVP4p\W4p\P !WVR7pVP VR4V#)a_ Return a new empty document object. :Parameters: `source_path` : str or pathlib.Path The path to or description of the source text of the document. `settings` : optparse.Values object Runtime settings. If none are provided, a default core set will be used. If you will use the document object with any Docutils components, you must provide their default settings as well. For example, if parsing rST, at least provide the rst-parser settings, obtainable as follows: Defaults for parser component:: settings = docutils.frontend.get_default_settings( docutils.parsers.rst.Parser) Defaults and configuration file customizations:: settings = docutils.core.Publisher( parser=docutils.parsers.rst.Parser).get_settings() )frontend)r?rK)docutilsrget_default_settingsrr document note_source)rrrrrs&& r" new_documentrsJ8"002K2H~~hEH b) Or%c$V^8dQhRRRRRR/#)rrznodes.paragraphkeyword_substitutionsz'Sequence[tuple[re.Pattern[[str], str]]]rrr )r!s"r"r#r#s&   B   r%c,\V4^8Xd\V^,\P4'd[V^,pVFIwr4VP V4pV'gK \P!VP WB44V^&R# R#R#R#)N)rrMr rsearchsub)rrtextnodepattern substitutionmatchs&& r"clean_rcs_keywordsrst 9~z)A, CCQ<%: !GNN8,Eu$zz'++l*MN !  &; Dr%c$V^8dQhRRRRRR/#)rr?StrPath | NonetargetrrrGr )r!s"r"r#r#s!44,44C4r%c\PPT;'g\V4!R44P \P 4p\PPV4P \P 4pVR,VR,8wdRP V4#VP4VP4V'd@V'd8VR,VR,8Xd#VP4VP4KGVP4R.\V4^, ,V,pRP V4#)ag Build and return a path to `target`, relative to `source` (both files). The return value is a `str` suitable to be included in `source` as a reference to `target`. :Parameters: `source` : path-like object or None Path of a file in the start directory for the relative path (the file does not need to exist). The value ``None`` is replaced with "/dummy_file". `target` : path-like object End point of the returned relative path. Differences to `os.path.relpath()`: * Inverse argument order. * `source` is assumed to be a FILE in the start directory (add a "dummy" file name to obtain the path relative from a directory) while `os.path.relpath()` expects a DIRECTORY as `start` argument. * Always use Posix path separator ("/") for the output. * Use `os.sep` for parsing the input (changing the value of `os.sep` is ignored by `os.relpath()`). * If there is no common prefix, return the absolute path to `target`. Differences to `pathlib.PurePath.relative_to(other)`: * pathlib offers an object oriented interface. * `source` expects path to a FILE while `other` expects a DIRECTORY. * `target` defaults to the cwd, no default value for `other`. * `relative_path()` always returns a path (relative or absolute), while `PurePath.relative_to()` raises a ValueError if `target` is not a subpath of `other` (no ".." inserted). dummy_file:NrN/z..rK) osrabspathrjrseprreversepopr)r?r source_parts target_partspartss&& r" relative_pathrsF77??6#G#GT&\,-G%%*U266]77??6*008LB<++xx %% LB<#33 Fc,'!+ ,| ;E 88E?r%c$V^8dQhRRRRRR/#)rrr relative_torrrGr )r!s"r"r#r#5s###v#*6#"%#r%c\P!R\^R7VP'd?VP'dQR4hVf VP p\ WP4#VP#)u Retrieve a stylesheet reference from the settings object. Deprecated. Will be removed in Docutils 1.0. Use get_stylesheet_list() instead to enable specification of multiple stylesheets as a comma-separated list. zqutils.get_stylesheet_reference() is obsoleted by utils.get_stylesheet_list() and will be removed in Docutils 2.0.) stacklevel6stylesheet and stylesheet_path are mutually exclusive.)warningswarnDeprecationWarningstylesheet_path stylesheet output_pathr)rrs&&r"get_stylesheet_referencer5sv MM:%4&&& F D F&  "..K[*B*BCC"""r%c V^8dQhRRRR/#)rrrr list[str]r )r!s"r"r#r#Ws  & Y r%cVP'dVP'dQR4hVP;'gVP;'g.p\V\4'g.VP R4Uu.uFq"P 4NK ppVP'd%VUu.uFp\ W P4NK ppV#uupiuupi)z@Retrieve list of stylesheet references from the settings object.r ,)rr rMlistrrfind_file_in_dirsstylesheet_dirs)r stylesheetsrs& r"get_stylesheet_listrWs###(@(@(@F DF A**GGh.A.AGGRK k4 ( (0;0A0A#0FG0Fzz|0F G$/0#.4)/G/GH#. 0  H0s ?C/Cc$V^8dQhRRRRRR/#)rrrdirsIterable[StrPath]rrGr )r!s"r"r#r#fs"  G +<  r%c&\V4pVP4'dVP4#VFKp\V4P4V, pVP 4'gK;VP4u# VP4#)zq Search for `path` in the list of directories `dirs`. Return the first expansion that matches an existing file. )r is_absoluteas_posix expanduserexists)rrdfs&& r"rrfsn :D }}  G   4 ' 88::::<  ==?r%c V^8dQhRRRR/#)rrrrrDr )r!s"r"r#r#vs 6 6& 6T 6r%cbVPRR4f\VRR4R8H#VP#)z Return whether or not to trim footnote space. If trim_footnote_reference_space is not None, return it. If trim_footnote_reference_space is None, return False unless the footnote reference style is 'superscript'. trim_footnote_reference_spaceNfootnote_references superscript)rnrOr&)rs&r"get_trim_footnote_ref_spacer)vs9:DAIx!6=NN555r%cV^8dQhRR/#)rrz!tuple[StrPath | None, int | None]r )r!s"r"r#r#s  : r%cV'dKVP'gVP'dVPVP3#VPpKRR#)z_ Return the "source" and "line" attributes from the `node` given or from its closest ancestor. )NN)r?riparent)nodes&r"rmrms:  ;;;$)));; ) ){{ r%c V^8dQhRRRR/#rtextrGrr )r!s"r"r#r#s  c c r%c.p^pVPRV4pVR8Xd%VPWR4RPV4#VPWVRW^,V^,,34V^,pKu)z;Return a string with escape-backslashes converted to nulls.\NrrK)rrWrextend)r0rstartbs_indexs& r" escape2nullr7s| E E 99T5) r> LLf &775> ! d*tqLA>>@ A1 r%c V^8dQhRRRR/#)rr0rGrrr )r!s"r"r#r#s++3+9+r%cVPR4pVUu.uFq"PR4NK pp\\P!V!4#uupi)z\ Split `text` on escaped whitespace (null+space or null+newline). Return a list of strings. z z )rr itertoolschain)r0stringsstrings& r"split_escaped_whitespacer>sF jj!G4;(strip_combining_chars..sCd+*?*?*B11ds/ /)r)r0s&r"strip_combining_charsrIs 77CdC CCr%c V^8dQhRRRR/#rr0rGrz list[int]r )r!s"r"r#r#sGGsGyGr%c\V4UUu.uF%wr\P!V4'gK#VNK' upp#uuppi)uReturn indices of all combining chars in Unicode string `text`. >>> from docutils.utils import find_combining_chars >>> find_combining_chars('A t̆ab̆lĕ') [3, 6, 9]  enumeraterBrCr0irFs& r"find_combining_charsrQs1$D/ F/$![-B-B1-EAA/ FF F >>c V^8dQhRRRR/#rKr )r!s"r"r#r#s K K K Kr%c\V4UUu.uF%wr\P!V4'dK#VNK' upp#uuppi)uIndices of Unicode string `text` when skipping combining characters. >>> from docutils.utils import column_indices >>> column_indices('A t̆ab̆lĕ') [0, 1, 2, 4, 5, 7, 8] rMrOs& r"column_indicesrUs1$D/ J/$!1F1Fq1IAA/ JJ JrRWFNaHNAc V^8dQhRRRR/#)rr0rGrrr )r!s"r"r#r#s  s s r%c`\RV44pV\\V44,pV#)ziReturn the column width of text. Correct ``len(text)`` for wide East Asian and combining Unicode chars. c3d"TF&p\\P!V4,xK( R#5ir')east_asian_widthsrBeast_asian_widthrDs& r"rGcolumn_width..s*A"+">">q"ABBs.0)sumrrQ)r0widths& r" column_widthrds7  E S%d+ ,,E Lr%c V^8dQhRRRR/#)rLrrr )r!s"r"r#r#s  D T r%cN.pVFpW!9gK VPV4K V#r')rW)rfritems& r"uniqrjs( A = HHTN Hr%c V^8dQhRRRR/#)rtagrGrrr )r!s"r"r#r#s r%c VP4PRR4p\P!RRV4p\ VP R44pVP ^43p\\V4^R4UUu.uF7p\P!W4FpRPW$,4NK K9 pppWR, pV#uuppi)a;Return a list of normalized combinations for a `BCP 47` language tag. Example: >>> from docutils.utils import normalize_language_tag >>> normalize_language_tag('de_AT-1901') ['de-at-1901', 'de-at', 'de-1901', 'de'] >>> normalize_language_tag('de-CH-x_altquot') ['de-ch-x-altquot', 'de-ch', 'de-x-altquot', 'de'] -_z_([a-zA-Z0-9])_z_\1-rK) rrrerrrrrangerr: combinationsr)rlsubtagsbase_tagntagstaglists& r"normalize_language_tagrxs ))+  c3 'C &&#Wc 2C399S>"G A Hc'lAr221$11'=4xx(=)2  G N s>=Cc V^8dQhRRRR/#)rrEzstr | Literal['unicode'] | NonerrGr )r!s"r"r#r#s < <9  )r)rEencoding_declarations& r"xml_declarationr~s; HNN$ 1!,XJa8! !5 6d ;;r%cZ]tRtRtRtRRRlltRRltRR ltR R ltR R lt Rt R#)DependencyListi z List of dependencies, with file recording support. Note that the output file is not automatically closed. You have to explicitly call the close() method. Nc$V^8dQhRRRRRR/#)r output_fileLiteral['-'] | StrPath | None dependenciesrrrr )r!s"r"r#DependencyList.__annotate__s&   ;  0    r%c HVPV4VP!V!R#)z Initialize the dependency list, automatically setting the output file to `output_file` (see `set_output()`) and adding all supplied dependencies. If output_file is None, no file output is done when calling add(). N) set_outputadd)r+rrs&&&r"r)DependencyList.__init__s  $ ,r%c V^8dQhRRRR/#)rrrrrr )r!s"r"r#r$s&?Dr%c VR8Xd\PVnM#V'd\VRRR7VnMRVn.VnR#)z Set the output file and clear the list of already added dependencies. The specified file is immediately overwritten. If `output_file` is '-', the output will be written to stdout. The empty string or None stop output. rnwr)rEN)rstdoutfileopenrr+rs&&r"rDependencyList.set_output$s8 #  DI [#@DIDI r%c V^8dQhRRRR/#)rpathsrrrr )r!s"r"r#r6s / /' /d /r%c "VFp\V\4'dVP4pW P9gK;VPP V4VP fKfVP P VR,4K R#)z Append `path` to `self.list` unless it is already there. Also append to `self.file` unless it is already there or `self.file is `None`. Nrk)rMrrrrWrrq)r+rrs&* r"rDependencyList.add6s`D$))}}99$   &99(IIOODI. r%cV^8dQhRR/#)rrrr )r!s"r"r#rEstr%c VP\PJdVPP4RVnR#)z Close the output file. N)rrrclose)r+s&r"rDependencyList.closeEs) 99CJJ & IIOO  r%cV^8dQhRR/#)rrrGr )r!s"r"r#rMsPP#Pr%c VPPpVPP: RV: RVP : R2# \dRpL;i;i)N(z, r)rrrprr-rrs& r"__repr__DependencyList.__repr__MsG ))..K $~~66 TYYOO K sA AA)rr)Nr ) r-r.r/r0rr)rrrrr1r r%r"rr s'  $ /PPr%rr')I__conditional_annotations__r __future__r __docformat__r:ros.pathrprrBr pathlibrrrrrrr docutils.nodesr TYPE_CHECKINGcollections.abcr r r typingrrrrdocutils.utils._typingrrdocutils.frontendrrrrrr3r6rrrrrrrrrrrrrrrrrr)rmr7r>rIrQrUr_rdrjrxr~r)rs@r"rs #"   "0# <<220&(')=)=(>(DEM9E$ / UGUGp,9+0)04-46/6;6!H F&Y%2'T$"J 4n#D   6  +DG K!!1!!!   6 <EPEPr%