o ix@sUdZddlmZdZddlZddlZddlZddlZddlZddl Z ddl Z ddl m Z m Z ddlmZmZddlmZmZddlmZd Zer}dd lmZmZmZdd lmZmZmZmZdd lm Z dd lm!Z!ddl"m#Z#eej$gdfZ%de&d<GdddeZ'GdddeZ(GdddZ)GdddeZ*Gddde*Z+Gddde*Z,Gddde*Z-d{d%d&Z.d|d(d)Z/d}d+d,Z0Gd-d.d.eZ1d~d2d3Z2d4d5Z3dd:d;Z4ddd>d?Z5ddEdFZ6ddJdKZ7 dddMdNZ8ddPdQZ9ddTdUZ:ddWdXZ;ddZd[ZddadbZ?ddddeZ@ddfdgZAdhdhdididididjZB ddldmZCddpdqZDddsdtZEdddwdxZFGdydzdzZGdS)z: Miscellaneous utilities for the documentation utilities. ) annotationsreStructuredTextN)PurePathPath)ApplicationError DataError)ionodes)unescapeF)CallableSequenceIterable)AnyFinalLiteralTextIO) TypeAlias)StrPath)Valuesr _ObserverFuncc@seZdZd ddZd S) SystemMessagesystem_messagenodes.system_messagelevelintreturnNonecCst||||_dSN) Exception__init__astextr)selfrrr"]/var/www/html/karishye-ai-python/venv/lib/python3.10/site-packages/docutils/utils/__init__.pyr*s zSystemMessage.__init__N)rrrrrr)__name__ __module__ __qualname__rr"r"r"r#r(src@ eZdZdS)SystemMessagePropagationNr$r%r&r"r"r"r#r(0sr(c@seZdZUdZded<dZded< dZded <d Zded <d Zded <dZ ded<dZ ded<    d?d@d$d%Z dAd(d)Z dAd*d+Z dBd.d/ZdCd3d4ZdDd5d6ZdDd7d8ZdDd9d:ZdDd;d<ZdDd=d>ZdS)EReporteraq Info/warning/error reporter and ``system_message`` element generator. Five levels of system messages are defined, along with corresponding methods: `debug()`, `info()`, `warning()`, `error()`, and `severe()`. There is typically one Reporter object per process. A Reporter object is instantiated with thresholds for reporting (generating warnings) and halting processing (raising exceptions), a switch to turn debug output on or off, and an I/O stream for warnings. These are stored as instance attributes. When a system message is generated, its level is compared to the stored thresholds, and a warning or error is generated as appropriate. Debug messages are produced if the stored debug switch is on, independently of other thresholds. Message output is sent to the stored warning stream if not set to ''. The Reporter class also employs a modified form of the "Observer" pattern [GoF95]_ to track system messages generated. The `attach_observer` method should be called before parsing, with a bound method or function which accepts system messages. The observer can be removed with `detach_observer`, and another added in its place. .. [GoF95] Gamma, Helm, Johnson, Vlissides. *Design Patterns: Elements of Reusable Object-Oriented Software*. Addison-Wesley, Reading, MA, USA, 1995. z9Callable[[int | None], tuple[StrPath | None, int | None]]get_source_and_line)DEBUGINFOWARNINGERRORSEVEREzFinal[Sequence[str]]levelsrr DEBUG_LEVEL INFO_LEVEL WARNING_LEVEL ERROR_LEVEL SEVERE_LEVELNFbackslashreplacesourcer report_levelr halt_levelstream5io.ErrorOutput | TextIO | str | Literal[False] | Nonedebugboolencoding str | None error_handlerstrrrcCsp||_ ||_ ||_ ||_ ||_ t|tjs!t|||}||_ |p,t |dd|_ g|_ d|_ dS)alLow level instantiating. See also `new_reporter().`. :Parameters: - `source`: The path to or description of the source data. - `report_level`: The level at or above which warning output will be sent to `stream`. - `halt_level`: The level at or above which `SystemMessage` exceptions will be raised, halting execution. - `debug`: Show debug (level=0) system messages? - `stream`: Where warning output is sent. Can be file-like (has a ``.write`` method), a string (file name, opened for writing), '' (empty string) or `False` (for discarding all stream messages) or `None` (implies `sys.stderr`; default). - `encoding`: The output encoding. - `error_handler`: The error handler for stderr output encoding. rCasciiN) r<rE debug_flagr=r> isinstancer ErrorOutputr?getattrrC observers max_level)r!r<r=r>r?rArCrEr"r"r#ras( zReporter.__init__observerrcCs|j|dS)z The `observer` parameter is a function or bound method which takes one argument, a `nodes.system_message` instance. N)rMappendr!rOr"r"r#attach_observerszReporter.attach_observercCs|j|dSr)rMremoverQr"r"r#detach_observerszReporter.detach_observermessagercCs|jD]}||qdSr)rM)r!rUrOr"r"r#notify_observerss  zReporter.notify_observersrkwargsrc Oslt|tr t|}|}d|vr0t|d\}}|d=|dur&|d||dur0|d|d|vr^z ||d\}}Wn tyMd\}}Ynw|durV||d<|dur^||d<|d|j t j |g|R||j |d|}|j r||jks|jr||jks||jkr|j |d||jkrt||||jks|jr||t||j|_|S)zs Return a system_message object. Raise an exception or generate a warning if appropriate. base_nodeNr<lineNN)rtype )rJrrFcopyget_source_line setdefaultr+getAttributeErrorr<r rr1r?r=rIr2r>writer rrVmaxrN) r!rrUchildrenrW attributesr<rYmsgr"r"r#rsP          zReporter.system_messagecOs$|jr|j|jg|Ri|SdS)z Level-0, "DEBUG": an internal reporting issue. Typically, there is no effect on the processing. Level-0 system messages are handled separately from the others. N)rIrr2r!argsrWr"r"r#rAszReporter.debugcO|j|jg|Ri|S)z Level-1, "INFO": a minor issue that can be ignored. Typically, there is no effect on processing and level-1 system messages are not reported. )rr4rgr"r"r#infoz Reporter.infocOri)z Level-2, "WARNING": an issue that should be addressed. If ignored, there may be unpredictable problems with the output. )rr6rgr"r"r#warningzReporter.warningcOri)z{ Level-3, "ERROR": an error that should be addressed. If ignored, the output will contain errors. )rr8rgr"r"r#errorrmzReporter.errorcOri)z Level-4, "SEVERE": a severe error that must be addressed. If ignored, the output will contain severe errors. Typically level-4 system messages are turned into exceptions which halt processing. )rr:rgr"r"r#severerkzReporter.severe)NFNr;)r<rr=rr>rr?r@rArBrCrDrErFrr)rOrrr)rUrrr)rrrUrFrWrrr)rWrrr)r$r%r&__doc____annotations__r1r2r4r6r8r:rrRrTrVrrArjrlrnror"r"r"r#r*4s0        <    4 r*c@r')ExtensionOptionErrorNr)r"r"r"r#rr  rrc@r')BadOptionErrorNr)r"r"r"r#rt rsrtc@r')BadOptionDataErrorNr)r"r"r"r#rursruc@r')DuplicateOptionErrorNr)r"r"r"r#rvrsrv field_listnodes.field_list options_spec dict[str, Callable[object], Any]rdict[str, Any]cCst|}t||S)aC Return a dictionary mapping extension option names to converted values. :Parameters: - `field_list`: A flat field list without field arguments, where each field body consists of a single paragraph only. - `options_spec`: Dictionary mapping known option names to a conversion function such as `int` or `float`. :Exceptions: - `KeyError` for unknown option names. - `ValueError` for invalid option values (raised by the conversion function). - `TypeError` for invalid option value types (raised by conversion function). - `DuplicateOptionError` for duplicate options. - `BadOptionError` for invalid fields. - `BadOptionDataError` for invalid option data (missing name, missing data, bad quotes, etc.). )extract_optionsassemble_option_dict)rwry option_listr"r"r#extract_extension_optionss rlist[tuple[str, str | None]]cCsg}|D]^}t|ddkrtdt|d}|d}t|dkr-d}n.t|dksMt|dtjrMt|ddksMt|ddtj sSt d||dd}| ||fq|S)a Return a list of option (name, value) pairs from field names & bodies. :Parameter: `field_list`: A flat field list, where each field name is a single word and each field body consists of a single paragraph only. :Exceptions: - `BadOptionError` for invalid fields. - `BadOptionDataError` for invalid option data (missing name, missing data, bad quotes, etc.). rr3z:extension option field name may not contain multiple wordsNzMextension option field body may contain a single paragraph only (option "%s")) lenr splitrtrFlowerrJr paragraphTextrurP)rwr~fieldnamebodydatar"r"r#r|-s0  r|r~c Csi}|D]>\}}||}|durt|||vrtd|z||||<WqttfyB}z|d||d|jfd}~ww|S)aa 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: "%s"; value: %r) %s )KeyErrorrv ValueError TypeError __class__joinrh)r~ryoptionsrvalue convertordetailr"r"r#r}Qs   r}c@r')NameValueErrorNr)r"r"r"r#rtrsrpathstr | bytes | NonerFc Cst|tr|S|dur dSz |td}W|Sty&td|tyHz |dd}WY|StyG|dd}YY|Sww)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. Nstrictz/`path` value must be a String or ``None``, not utf-8rGreplace)rJrFdecodesysgetfilesystemencodingrarUnicodeDecodeError)rr"r"r# decode_pathws(    rcCs^g}|r|d}|dkrtd|d|}|dks|s#td||dd}|s7td|d |dd vr||dd}|dkrVtd |d |dd t||dkrs||drstd |d|dd|d|}||dd}n|d}|dkr|}d}n|d|}||dd}|||f|s|S)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.). =rHz missing "="Nrz!missing attribute name before "="r3zmissing value after "z="z'"z attribute "z" missing end quote ()z " end quote (z) not followed by whitespacerr)findrstriplstriprrPr)rYattlist equals_indexattnameendquote_indexr space_indexr"r"r#extract_name_valuesD       r source_pathrsettingsrc Cs&t||j|j|j|j|j|jd}|S)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. )r?rArCrE)r*r=r>warning_streamrAerror_encodingerror_encoding_error_handler)rrreporterr"r"r# new_reporters r Values | Nonenodes.documentcCsFddlm}|dur|}t||}tj|||d}||d|S)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() r)frontendN)r<rH)docutilsrget_default_settingsrr document note_source)rrrrrr"r"r# new_documents   rrnodes.paragraphkeyword_substitutions'Sequence[tuple[re.Pattern[[str], str]]]rcCsht|dkr.t|dtjr0|d}|D]\}}||}|r-t||||d<dSqdSdSdS)Nr3r)rrJr rsearchsub)rrtextnodepattern substitutionmatchr"r"r#clean_rcs_keywordss  rr<StrPath | NonetargetcCstj|p t|dtj}tj|tj}|dd|ddkr+d|S|||rS|rS|d|dkrS|||rS|rS|d|dks?|dgt |d|}d|S)a 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_fileNr5/rHz..r3) osrabspathr[rseprreversepopr)r<r source_parts target_partspartsr"r"r# relative_paths"#  r relative_tocCsDtjdtdd|jr|jrJd|dur|j}t||jS|jS)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.r5) stacklevel6stylesheet and stylesheet_path are mutually exclusive.N)warningswarnDeprecationWarningstylesheet_path stylesheet output_pathr)rrr"r"r#get_stylesheet_reference5s  r list[str]cs^jr jr Jdjpjpg}t|ts!dd|dD}jr-fdd|D}|S)z@Retrieve list of stylesheet references from the settings object.rcSsg|]}|qSr")r.0rr"r"r# ^sz'get_stylesheet_list..,csg|]}t|jqSr")find_file_in_dirsstylesheet_dirsrrr"r#ras)rrrJlistr)r stylesheetsr"rr#get_stylesheet_listWs  rdirsIterable[StrPath]cCsNt|}|r |S|D]}t||}|r"|Sq|S)z} Search for `path` in the list of directories `dirs`. Return the first expansion that matches an existing file. )r is_absoluteas_posix expanduserexists)rrdfr"r"r#rfs rrBcCs&|dddurt|dddkS|jS)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)r_rLrrr"r"r#get_trim_footnote_ref_spacevs r!tuple[StrPath | None, int | None]cCs*|r|js|jr|j|jfS|j}|sdS)zk Return the "source" and "line" attributes from the `node` given or from its closest ancestor. rZ)r<rYparent)noder"r"r#r^s   r^textcCsng}d} |d|}|dkr|||dd|S||||d||d|d f|d }q) z;Return a string with escape-backslashes converted to nulls.rT\rHNrr3r5)rrPrextend)rrstartbs_indexr"r"r# escape2nulls  rcCs&|d}dd|D}ttj|S)zh Split `text` on escaped whitespace (null+space or null+newline). Return a list of strings. z cSsg|]}|dqS)z )r)rstringr"r"r#rsz,split_escaped_whitespace..)rr itertoolschain)rstringsr"r"r#split_escaped_whitespaces rcCsddd|DS)Nrcss|] }t|s|VqdSr unicodedata combiningrcr"r"r# sz(strip_combining_chars..)rrr"r"r#strip_combining_charssr list[int]cCddt|DS)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] cSsg|] \}}t|r|qSr"rrirr"r"r#rz(find_combining_chars.. enumeraterr"r"r#find_combining_charssrcCr )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] cSsg|] \}}t|s|qSr"rr r"r"r#rr z"column_indices..rrr"r"r#column_indicess rr5r3)WFNaHNArcCs&tdd|D}|tt|8}|S)zqReturn the column width of text. Correct ``len(text)`` for wide East Asian and combining Unicode chars. css|] }tt|VqdSr)east_asian_widthsreast_asian_widthrr"r"r#rszcolumn_width..)sumrr)rwidthr"r"r# column_widths rLrcCs$g}|D] }||vr||q|Sr)rP)rritemr"r"r#uniqs  r tagcsd|dd}tdd|}t|ddffddttddD}|7}|S) aWReturn 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-rcs,g|]}t|D] }d|q qS)r")r combinationsr)rntagsbase_tagsubtagsr"r#rs  z*normalize_language_tag..rH) rrrerrrrranger)r!taglistr"r'r#normalize_language_tags   r-rCstr | Literal['unicode'] | NonecCs.|r|dkrd|d}nd}d|dS)z{Return an XML text declaration. Include an encoding declaration, if `encoding` is not 'unicode', '', or None. unicodez encoding=""rz )r)rCencoding_declarationr"r"r#xml_declarations r2c@sHeZdZdZ  ddd d Zdd d ZdddZdddZdddZdS)DependencyListz List of dependencies, with file recording support. Note that the output file is not automatically closed. You have to explicitly call the close() method. Nr" output_fileLiteral['-'] | StrPath | None dependenciesrrrcCs|||j|dS)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!r4r6r"r"r#rs zDependencyList.__init__cCs8|dkr tj|_n|rt|ddd|_nd|_g|_dS)a  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. r"wr)rCN)rstdoutfileopenrr!r4r"r"r#r7$s   zDependencyList.set_outputpathsrcGsP|D]#}t|tr |}||jvr%|j||jdur%|j|dqdS)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`. Nr\)rJrrrrPr;rb)r!r>rr"r"r#r86s    zDependencyList.addcCs |jtjur |jd|_dS)z( Close the output file. N)r;rr:close)r!r"r"r#r?Es   zDependencyList.closerFcCs8z|jj}Wn tyd}Ynwd|jj||jfS)Nz %s(%r, %s))r;rrarr$rr=r"r"r#__repr__Ms   zDependencyList.__repr__)Nr")r4r5r6rrr)r4r5rr)r>rrr)rr)rrF) r$r%r&rprr7r8r?r@r"r"r"r#r3 s   r3)rwrxryrzrr{)rwrxrr)r~rryrzrr{)rrrrF)rrrrrr*r)rrrrrr)rrrrrr)r<rrrrrF)rrrrrrF)rrrr)rrrrrrF)rrrrB)rr)rrFrrF)rrFrr)rrFrr )rrFrr)rrrr)r!rFrr)rCr.rrF)Hrp __future__r __docformat__rros.pathr*rrrpathlibrrrrrrr docutils.nodesr TYPE_CHECKINGcollections.abcr r r typingrrrrdocutils.utils._typingrrdocutils.frontendrrrrqrr(r*rrrtrurvrr|r}rrrrrrrrrrrr^rrrrrrrr r-r2r3r"r"r"r#s     Y   $#  *  % 8 "