lKj< dZddlZddlmZddlmZmZer ddlmZddl m Z ddl m Z ddl m Z mZd d d efd Zd d d efd Zd d ded efdZd d deed efdZ d2deedzdeedzd eeedzeedzffdZdedeedeedzdeedzdd d ef dZdedeedzdeedzd eeedzeedzffdZd3d d deedzd eeeeffdZdeedzdeded eefdZdeed edzd eefd!Zd"ed efd#Zdedd d$d d%ed ef d&Zd d d'd(d%ed eefd)Z d d d*ed edzfd+Z!d d d edzfd,Z"d4d-edeed.ed efd/Z#d5d d d%ed0efd1Z$y)6z,Base utilities for documentation generation.N)Sequence) TYPE_CHECKINGAny)App) HelpPanel) CommandSpec) format_doc format_usageapprreturncht|jjdk(}|ry|jduS)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 c/Users/ahmed/devFolder/Ultron/claude-voice/.venv/lib/python3.12/site-packages/cyclopts/docs/base.pyshould_show_usagers6,#--%%&!+G""$..c|jduS)aDetermine 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 **rnamect|jjdd}t|jjdd}||z}||vS)aCheck 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 rrr builtin_flagss r_is_builtin_flagr"CsUS]]**<"*EFJ --o-KLM.M =  rnamesc2|sytfd|DS)a4Check 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. Fc36K|]}t|ywN)r").0rr s r z'is_all_builtin_flags..is=utT*us)all)r r#s` ris_all_builtin_flagsr*Xs  =u= ==rcommands_filterexclude_commandscd}||Dchc]}|jdd}}d}|r|Dchc]}|jdd}}||fScc}wcc}w)aNormalize 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)r+r,normalized_includecmdnormalized_excludes rnormalize_command_filtersr4lss$"?NOckk#s3O?OP?Ockk#s3?OP 1 11 PQs A A parent_pathnormalized_commands_filternormalized_exclude_commandssubappc|rdj||gzn|}|r?||vs||vrytt|D]}dj|d|dz}||vsy|u||vs||vrytt|D]}dj|d|dz}||vsyt|dr)|jr|D]}|j |dzsyyy)a3Determine 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. .FNrT _commands)joinrangerhasattrr; startswith) rr5r6r7r8 full_pathiparent_segment filter_cmds rshould_include_commandrDs63>v-.4I" . .)?Z2Zs;'(A XXk'AE&:;N!<<) "- - ->X1Xs;'(A XXk'AE&:;N!;;) 6; 'F,<,<8 ((S99 rcd}|_g}|D]R}|j|dzr3|t|dzd}|j|jddJ||k(sPd}n||sg}d}|rqg}|D]j}|j|dzr3|t|dzd}|j|jddJ|j|jddl||fS)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). Nr:rr/r.)r?rappendr0) rr6r7sub_commands_filterrC sub_filtersub_exclude_commands exclude_cmd sub_excludes radjust_filters_for_subcommandrLs*!- 4J$$TCZ0'D A 8 #**:+=+=c3+GHt#&*# 5  *3F"$ "!6K%%dSj1)#d)a-/: $++K,?,?S,IJ$++K,?,?S,IJ 7  4 44r command_chainch|s|jd}|}|}n|d}dj|}|}|||fS)a8Get 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 )rr<)r rMapp_name full_commandtitles r get_app_inforSsH 88A;  #xx .  \5 ((r command_namerPc|r||gzS||gS)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)rMrTrPs rbuild_command_chainrV s" ~--,''r usage_namec8||S|dk(r|ddS|s|gS|g|ddS)aReturn a display command chain with the root replaced by ``usage_name``. When ``usage_name`` is ``None``, returns ``command_chain`` unchanged so callers can use this helper unconditionally. When ``usage_name`` is ``""``, the root token is dropped rather than substituted, so downstream formatters never see an empty element (which would render as stray leading/internal whitespace). When the chain is empty and ``usage_name`` is a non-empty string, returns a single-element list containing ``usage_name``. Parameters ---------- command_chain : list[str] The logical command chain (root app name first). usage_name : str | None Replacement for the chain's root element used in Usage: lines only. An empty string drops the root token entirely. Returns ------- list[str] A new list with the root replaced/dropped, or the original chain when ``usage_name`` is ``None``. Nrr)rMrWs rapply_usage_namerZ#sE0RQR  |  +qr* ++r command_pathct|jjdd}tjdd|}|S)afGenerate 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' rOr/z-+)lowerr0resub)r[anchors rgenerate_anchorraDs60   ! ) )#s 3F VVE3 'F Mr parent_appinclude_hiddencht||ryt|t|sy|s |jsyy)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)rTr8rbrcs rshould_skip_commandrhbs2& L1 fd:. / &++ rpanelrc|r |jS|jDcgc]'}|jrt||jr&|)c}Scc}w)aXFilter 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#r*)r rirces rfilter_help_entriesrmsD"}}}} ]}!QWW9McSTSZSZ9[A} ]] ]s 'A A  help_formatct||}|S)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 rn descriptions rextract_descriptionrqsS+.K rcj|j|jr |jSdSt|g}|S)zExtract usage string. Parameters ---------- app : App The App instance. Returns ------- Optional[Any] The extracted usage object, or None. N)usager )r rss r extract_usagerts4 yyIIsyy/4/ b !E Lr usage_textprefixc|syd|vr |jddj}|rdj|nd}|jdd}t |dkDr+|r)|r |d|d|dn |d|d}|jS|r|r|d|n|}|jS|r|d|n|}|jS)aEFormat 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. rYzUsage:rONr)r0stripr<splitr)rurMrvrQparts usage_lines rformat_usage_liner|s" :''"5;;= .;388M*L   T1 %E 5zA~->Dxqaaz:\NZ[\abc\d[eJf     39xq/|     28xq -Z    r resolve_lazyc#K|jsyt}|jjD]\}}t||rt |t r!|j s|s2|j|}n|}t |t|s\|s |jskt|}||vr{|j|||fyw)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) r;ritemsr"rer is_resolvedr rfrgidadd)r rcr}seenr app_or_specr8app_ids riterate_commandsrs. ==UD ]]002k C &  k; /**< ((-F F&$s), fkk F T>  Fl/3sCC )NNr&)rY)FT)%__doc__r^collections.abcrtypingrr cyclopts.corer cyclopts.helprcyclopts.command_specrr r boolrrstrr"r*listtuplerr4rDrLrSrVrZrarhrmrqrtr|rrrrrs2 $%!'-2/5/T/@+5+T+(!%!s!t!*>e>HSM>d>*)-)-2#Y%23i$&2 3s8d?CHtO +,2:5 5c5!$C45"%SD 5  5  5p-5 -5 #C4-5"%SD-5 49t T#Y- -. -5`)e)DI,<)cSVX[mH\)6(tCy4'7(s(VY(^bcf^g(.,DI,3:,$s),B##<c5e]afj>^U^;^^QUVYQZ^.Ut&ut(!#!d3i!!VY!H3%33T3r