+ Q(i7BRt^RIt^RIHt^RIHtHt]'d ^RIHt^RI H t ^RI H t ^RI H t HtRR ltR R ltR R ltRRltR(RRlltRRltRRltR)RRlltRRltRRltRRltRRltR R!ltR"R#ltR*R$R%lltR+R&R'lltR#),z,Base utilities for documentation generation.N)Sequence) TYPE_CHECKINGAny)App) HelpPanel) CommandSpec) format_doc format_usagec(V^8dQhRRR\/#apprreturnbool)formats"X/Users/agent/.openclaw/workspace/venv/lib/python3.14/site-packages/cyclopts/docs/base.py __annotate__rs//5/T/cv\VPP4^8HpV'dR#VPRJ#)a@Determine if usage should be shown for an app. Root apps always show usage (even without default_command, showing "app COMMAND"). Subcommands only show usage if they have a default_command. This skips usage for command groups that can't be invoked directly. The determination is made by checking the app_stack depth: - Stack length of 1 means root app (just the initial frame) - Stack length > 1 means we're in a subcommand context (frames were pushed) Parameters ---------- app : App The App instance to check. Returns ------- bool True if usage should be shown. TN)len app_stackstackdefault_command)r is_roots& rshould_show_usagers6,#--%%&!+G""$..rc(V^8dQhRRR\/#r r)rs"rrr/s++5+T+rcVPRJ#)ajDetermine if commands list should be shown for an app. Only show commands list for apps with a default_command. Command groups (apps without default_command) skip the list since their commands will be documented recursively anyway. Parameters ---------- app : App The App instance to check. Returns ------- bool True if commands list should be shown. N)r)r s&rshould_show_commands_listr/s"   d **rc4V^8dQhRRR\R\/#)r r rnamerstrr)rs"rrrCs!!!%!s!t!rc\VPPRRR74p\VPPRRR74pW#,pW9#)zCheck if a flag name is a built-in help or version flag. Parameters ---------- app : App The App instance to check against. name : str The flag name to check. Returns ------- bool True if this is a built-in help or version flag. help_flags)fallback version_flags)setrresolve)r r r$r& builtin_flagss&& r_is_builtin_flagr+CsQS]]**<"*EFJ --o-KLM.M   rcJV^8dQhRRR\\,R\/#)r r rnamesr)rr"r)rs"rrrXs%>>e>HSM>d>rcaV'gR#\;QJdV3RlV4F 'dK R# R#!V3RlV44#)aCheck if all names in the sequence are builtin help or version flags. Parameters ---------- app : App The App instance to check against. names : Sequence[str] Sequence of flag names to check. Returns ------- bool True if all names are builtin flags. Fc3<<"TFp\SV4xK R#5iN)r+).0r r s& r 'is_all_builtin_flags..is=utT**usT)all)r r-sf&ris_all_builtin_flagsr5Xs4  3=u=33=3=3=u= ==rc V^8dQhR\\,R,R\\,R,R\\\,R,\\,R,3,/#)r commands_filterNexclude_commandsr)listr"tupler()rs"rrrlsR22#Y%23i$&2 3s8d?CHtO +,2rcRpVe!VUu0uFq3PRR4kK ppRpV'd!VUu0uFq3PRR4kK ppW$3#uupiuupi)aVNormalize command filter lists by converting underscores to dashes. Parameters ---------- commands_filter : list[str] | None List of commands to include. exclude_commands : list[str] | None List of commands to exclude. Returns ------- tuple[set[str] | None, set[str] | None] Normalized include and exclude sets for O(1) lookup. N_-)replace)r7r8normalized_includecmdnormalized_excludes&& rnormalize_command_filtersrBlsl$"?NOkk#s3O?OP?Okk#s3?OP  11 PQs AAc V^8dQhR\R\\,R\\,R,R\\,R,RRR\/#) r r parent_pathnormalized_commands_filterNnormalized_exclude_commandssubapprr)r"r9r(r)rs"rrrsX55 5c5!$C45"%SD 5  5  5rc6V'dRPW.,4MTpV'dNW9gWS9dR#\\V44F'pRPVRV^,4pWs9gK&R# VeW9gWR9dR#\\V44F'pRPVRV^,4pWr9gK&R# \VR4'd=VP'd+VF$pVP VR,4'gK#R# R#R#)aDetermine if a command should be included based on filters. Parameters ---------- name : str The command name. parent_path : list[str] Path to parent commands. normalized_commands_filter : set[str] | None Set of commands to include (already normalized). normalized_exclude_commands : set[str] | None Set of commands to exclude (already normalized). subapp : App The subcommand App instance. Returns ------- bool True if the command should be included, False otherwise. .FNT _commands)joinrangerhasattrrJ startswith) r rDrErFrG full_pathiparent_segment filter_cmds &&&&& rshould_include_commandrSs63>v-.4I"  .)2Zs;'(A XXk'AE&:;N<) "-  -1Xs;'(A XXk'AE&:;N;) 6; ' 'F,<,<,<8 ((S999 rc V^8dQhR\R\\,R,R\\,R,R\\\,R,\\,R,3,/#)r r rENrFr)r"r(r:r9)rs"rrrs\-5-5 -5 #C4-5"%SD-5 49t T#Y- -. -5rcRpVez.pVFcpVPVR,4'd9V\V4^,RpVPVPRR44KYW@8XgKaRpM Ve V'g.pRpV'd.pVFzpVPVR,4'd9V\V4^,RpVPVPRR44KYVPVPRR44K| W63#)aAdjust filter lists for subcommand context. Parameters ---------- name : str The current command name. normalized_commands_filter : set[str] | None Set of commands to include (already normalized). normalized_exclude_commands : set[str] | None Set of commands to exclude (already normalized). Returns ------- tuple[list[str] | None, list[str] | None] Adjusted commands_filter and exclude_commands lists (denormalized). NrIr=r<)rNrappendr>) r rErFsub_commands_filterrR sub_filtersub_exclude_commands exclude_cmd sub_excludes &&& radjust_filters_for_subcommandr\s*!- 4J$$TCZ00'D A 8 #**:+=+=c3+GH#&*# 5  *3F"$ "!6K%%dSj11)#d)a-/: $++K,?,?S,IJ$++K,?,?S,IJ 7  44rc V^8dQhRRR\\,R,R\\\\3,/#)r r r command_chainNr)r9r"r:)rs"rrrs7))e)DI,<)cSVX[mH\)rcV'gVP^,pTpTpMV^,pRPV4pTpW#V3#)a Get app name, full command path, and title. Parameters ---------- app : App The cyclopts App instance. command_chain : Optional[List[str]] Chain of parent commands leading to this app. Returns ------- Tuple[str, str, str] (app_name, full_command, title)  )r rK)r r^app_name full_commandtitles&& r get_app_infordsF 88A;  #xx .  5 ((rc V^8dQhR\\,R,R\R\R\\,/#)r r^N command_namerar)r9r")rs"rrr s9((tCy4'7(s(VY(^bcf^g(rc*V'd W.,#W!.#)a Build command chain for a subcommand. Parameters ---------- command_chain : Optional[List[str]] Current command chain. command_name : str Name of the subcommand. app_name : str Name of the root app. Returns ------- List[str] Updated command chain. r')r^rfras&&&rbuild_command_chainrh s"~--''rc0V^8dQhR\R\/#)r command_pathr)r")rs"rrr#s##rcvVP4PRR4p\P!RRV4pV#)aGenerate a URL-friendly anchor from a command path. Converts spaces to hyphens and lowercases the string to match how markdown/HTML processors generate anchors from headings. Strips leading dashes to match markdown processor behavior. Parameters ---------- command_path : str Full command path (e.g., "myapp files cp"). Returns ------- str Anchor string (e.g., "myapp-files-cp"). Examples -------- >>> generate_anchor("myapp files cp") 'myapp-files-cp' >>> generate_anchor("myapp --install-completion") 'myapp-install-completion' r`r=z-+)lowerr>resub)rjanchors& rgenerate_anchorrp#s60   ! ) )#s 3F VVE3 'F Mrc DV^8dQhR\RRRRR\R\/#)r rfrGr parent_appinclude_hiddenrr!)rs"rrrAs1c5e]afjrc\W 4'dR#\V\V44'gR#V'gVP'gR#R#)a@Check if a command should be skipped. Parameters ---------- command_name : str Name of the command. subapp : App The subcommand App instance. parent_app : App The parent App instance. include_hidden : bool Whether to include hidden commands. Returns ------- bool True if command should be skipped. TF)r+ isinstancetypeshow)rfrGrrrss&&&&rshould_skip_commandrxAs8& 11 fd:. / / &+++ rc NV^8dQhRRRRR\R\\,/#)r r rpanelrrsr)rr9r)rs"rrr`s5^^U^;^^QUVYQZ^rcV'd VP#VPUu.uF3q3P'd\WP4'dK1VNK5 up#uupi)a$Filter help panel entries based on visibility settings. Parameters ---------- app : App The App instance to check against. panel : HelpPanel The help panel to filter. include_hidden : bool Whether to include hidden entries. Returns ------- List[Any] Filtered panel entries. )entriesr-r5)r rzrses&&& rfilter_help_entriesr~`sC"}}}} ]}!WWW9McSZSZ9[AA} ]] ]s .AAcBV^8dQhRRR\R\R,/#)r r r help_formatrN)r"r)rs"rrrws%Utrc\W4pV#)zExtract app description. Parameters ---------- app : App The App instance. help_format : str Help format type. Returns ------- Optional[Any] The extracted description object, or None. )r)r r descriptions&& rextract_descriptionrwsS.K rc6V^8dQhRRR\R,/#)r r rrN)r)rs"rrrsutrczVPe!VP'd VP#R#\V.4pV#)zExtract usage string. Parameters ---------- app : App The App instance. Returns ------- Optional[Any] The extracted usage object, or None. N)usager )r rs& r extract_usagers6 yyIIIsyy/4/ b !E Lrc^V^8dQhR\R\\,R\R\/#)r usage_textr^prefixr)r"r9)rs"rrrs-!!#!d3i!!VY!rcV'gR#RV9d!VPRR4P4pV'dRPV4MRpVPR^4p\ V4^8d@V'd8V'dV RV RV^, 2M V RV^, 2pVP4#V'd"V'dV RV 2MTpVP4#V'dV RV 2MTpVP4#)aFormat usage line with proper command path. Parameters ---------- usage_text : str Raw usage text. command_chain : List[str] Command chain for the app. prefix : str Optional prefix for the usage line (e.g., "$"). Returns ------- str Formatted usage line. zUsage:r`N)r>striprKsplitr)rr^rrbparts usage_lines&&& rformat_usage_liners" :''"5;;= .;388M*L   T1 %E 5zA~->Dxqaaz:\NZ[\abc\d[eJf     39xq/|     28xq -Z    rc4V^8dQhRRR\R\/#)r r rrs resolve_lazyr)rs"rrrs!33%33T3rc#"VP'gR#\4pVPP4FwrE\W4'dK\ V\ 4'd/VP 'g V'gKJVPV4pMTp\ V\V44'gK{V'gVP'gK\V4pWs9dKVPV4WF3xK R#5i)aIterate through app commands, yielding valid resolved subapps. Automatically resolves CommandSpec instances to App instances. Each unique subapp is yielded only once (first occurrence wins). Parameters ---------- app : App The App instance. include_hidden : bool Whether to include hidden commands. resolve_lazy : bool If ``True`` (default), resolve lazy commands (import their modules) to include them in the output. If ``False``, skip unresolved lazy commands. Set to ``True`` when generating static artifacts that need all commands, such as documentation or shell completion scripts. Yields ------ Tuple[str, App] (command_name, resolved_subapp) for each valid command. N) rJr(itemsr+rur is_resolvedr)rvrwidadd)r rsrseenr app_or_specrGapp_ids&&& riterate_commandsrs. ===UD ]]002 C & &  k; / /***< ((-F F&$s),, fkkk F >  l/3sA8D;D:D>D1D)NNr0)r)FT)__doc__rmcollections.abcrtypingrr cyclopts.corer cyclopts.helprcyclopts.command_specrrr rrr+r5rBrSr\rdrhrprxr~rrrrr'rrrsz2 $%!'-2/@+(!*>(2:5p-5`)6(.<>^.&(!H33r