^jundZddlZddlZddlZddlZddlmZddlm Z ddl m Z m Z ddl mZmZmZmZmZmZddlmZmZmZmZmZmZmZded efd Zd d d eded dfdZded e efdZ!d.deded e efdZ"GddZ#dede eded e e efdZ$de%d efdZ&d/d ddede eded dfdZ' d0dddededede e ed e(f d Z) d1dddede ededede e ed e(f d!Z* d0dddededede e ed e(f d"Z+ d1dede ededed e(f d#Z, d2dddede eded$ed%ed&e ede e ed e(fd'Z-d(ed)e(fd ed*fd+Z.d3d,Z/d3d-Z0y)4uCLI entry point for pyDeprecate validation. Provides two entry points for scanning Python code for misconfigured ``@deprecated`` wrappers: - ``pydeprecate `` — console script installed via ``pip install 'pyDeprecate[cli]'`` - ``python -m deprecate `` — module invocation of the same CLI Subcommands: check — Validate wrapper configuration and flag misconfigured or chain-forming wrappers. expiry — Check for deprecated wrappers that have passed their scheduled ``remove_in`` deadline. chains — Detect deprecated wrappers whose ``target`` is itself a deprecated callable. all — Run all three checks in a single scan pass. status — Render a markdown deprecation table to stdout (and optionally save it to a file). N)Callable)Path)AnyOptional)_auto_detect_version_find_child_packages_is_package_dir_managed_sys_path_resolve_module_name_safe_module_name)DeprecationWrapperInfo TableStyle_check_expiry_for_callablesfind_deprecation_wrappersgenerate_deprecation_tablevalidate_deprecation_chainsvalidate_deprecation_expirynamereturncDtjj|duS)zBReturn True if *name* is importable without actually importing it.N) importlibutil find_specrs Y/var/www/ramen.bs-engineer-server.com/venv/lib/python3.12/site-packages/deprecate/_cli.py_is_package_availabler,s >> # #D ) 55Fstderrmsgrctjr(tj|j|ddy|rtj ntj }t||y)aNPrint a message, using Rich console when available. Routes output through :class:`~rich.console.Console` when the ``rich`` package is installed, falling back to built-in :func:`print` otherwise. Args: msg: The message to print. stderr: If ``True``, send the message to *stderr* instead of *stdout*. F)markup highlight)fileN) _Reporter _HAS_RICH_consoleprintsysrstdout)r rstd_s r_printr,1sH6"((Ue(L#szz crpathct|jg}tjdd}tjddt_ t j dD]f}|j r*|jdk(r|jjdr>|j} |jt|dh |t_t!fdj#dD}|r tdd |S#t$rtd |d d Yt$r}td |d|d Yd}~d}~wwxYw#|t_wxYw)aQScan a plain directory of top-level Python files. Nested Python files in subdirectories are skipped unless they are part of an importable package layout. Plain directories do not generally support dotted imports for nested modules, so this function only scans top-level modules and warns when deeper files are present. Nc|jSNr)ents rz!_scan_directory..Qs r)keyz.py__F recursivez Skipping z1: module-level code exited (not a library module)TrzCould not scan : c3vK|]0}|jk7s|jjd 2yw)r5N)parentr startswith).0fpyabs_paths r z"_scan_directory..^s4**-3::YaKaCHH   %%*s9!9z*.pyzSkipping nested Python files in plain directory scan. Use an importable package layout with '__init__.py' files, or scan an importable module/package path instead.)rresolver)argvsortediterdiris_filesuffixrr;stemextendr SystemExitr, Exceptionanyrglob)r-results original_argventry module_nameenested_python_files_foundr>s @r_scan_directoryrRCsK$Z'')H,.GHHQKMxx|CH !H,,.4HI JEMMO (=ejjF[F[\`Fa$zzK J8PUVW J!&)*191G*'! I N# p;-/`ajno J Rs;DII J!sC A&E4DEE,E.E6E EEE E#r7c|t|}|jrvt|r.tt|j j |St |}t|dk(rtt|d|St|S|jrtd|dt||S)zScan a directory or importable module/package name for deprecated wrappers. File paths are not accepted because ``find_deprecation_wrappers()`` expects an importable module or package name, not a filesystem path. r6r/rzFile paths are not supported: z@. Pass an importable module/package name or a directory instead.) ris_dirr rr@rrlen _scan_pathstrrRrD ValueError)r-r7pth child_pkgss rrVrVksT C zz| 3 ,T$Z-?-?-A-F-FR[\ \)#. z?a c*Q-0IF Ft$$ {{},TH4t u   %TY ??rceZdZUedZeed<dZeed<dZ eed<dZ eed<dZ eed< dd l m Zdd lmZdd lmZeZ eZ eZed Z ed(dedefdZedededededef dZedededededeeedfdeddfdZedeeddfdZedeeddfdZedeeddfdZ edddeed eddfd!Z!ed"eeddfd#Z"edd$d%eed&edefd'Z#y#e$rYwxYw))r%richr&N_out_err _rich_box _RichTabler)box)Console)TableTrFrrcF|rtjStjS)z7Return the Rich Console for stdout (default) or stderr.)r%r^r]rs rr'z_Reporter._consoles"(y~~;Y^^;rtitlecol title_style col_stylectj|tjj|}|j dd|j dd|j |||S)z6Build a three-column Module/Function/ Rich table.rerargModulecyanstyleFunctionmagenta)r%r`r_ROUNDED add_column)rerfrgrhtables r _make_tablez_Reporter._make_tablesf$$5i6I6I6Q6Q_j$k 0 95 I. rrows. plain_prefixc $tjrStj||||}|D]}|j|tj j |yt d||D]\}} } t d|d| d| y)zLRender a three-column Module/Function/Detail table (rich or plain fallback).)rgrh  - .r8N)r%r&rtadd_rowr'r(r,) rerfrgrhrurvrsrowmodfndetails r _render_tablez_Reporter._render_tables   ))%+Yb)cE $ s# $    & &u - R ~& '#' 4RcU!B4r&23 4ritemsctjdddd|Dcgc]4}|j|jdj |j f6c}dycc}w) z3Report wrappers with invalid ``args_mapping`` keys.zInvalid Argument Mappingsz Invalid Argsbold redred, z7[ERROR] Found functions with invalid argument mappings:rgrhrurvN)r%rmodulefunctionjoin invalid_argsrrs rrz_Reporter.invalid_argssV  ' "MRS188QZZ1>>)BCSR  T9Actjdddd|Dcgc]4}|j|jdj |j f6c}dycc}w) zBReport wrappers whose ``args_mapping`` maps an argument to itself.z'Identity Argument Mappings (arg -> arg)z Identity Args bold yellowyellowrzG[WARNING] Found functions with identity argument mappings (arg -> arg):rN)r%rrrridentity_args_mappingrs ridentity_args_mappingsz _Reporter.identity_args_mappingssY  5 %V[\QR188QZZ13J3J)KL\b  ]rcdtdtfd}tjdddd|Dcgc]!}|j|j ||f#c}d y cc}w) z:Report wrappers that have no observable effect on callers.rrcg}|jr|jd|jr|jd|jr|jddj |S)Nz Empty mappingzSelf referencezAll identity mappingsr)empty_args_mappingappendself_reference all_identityr)rpartss r_reasonsz%_Reporter.no_effect.._reasonssUE## _- -.~~ 4599U# #rz No-Effect Wrappers (zero impact)ReasonrrzA[WARNING] Found deprecated wrappers with NO EFFECT (zero impact):rN)r rWr%rrr)rrrs r no_effectz_Reporter.no_effectsa $. $3 $  . %?DE!188QZZ!5E\  Fs&Aerrorrc |rdnd}|rdnd}|rdnd}tjdd|||Dcgc]=}|j|j|j|jj nd f?c}|d  y cc}w) zQReport deprecated-to-deprecated forwarding chains; ``error=True`` renders in red.rrrrz[ERROR]z [WARNING]zDeprecation Chainsz Chain TypeNz6 Found deprecated wrappers forming deprecation chains:r)r%rrr chain_typevalue)rrrnrhprefixrs rchainsz_Reporter.chainss$ "E # jopef188QZZq||?W););]_`p"8#YZ  qsAA9expiredcbtjrtjdtjjd}|j dd|D]}|j |tjj|y td|D]}td|y ) zIReport deprecated wrappers that have passed their ``remove_in`` deadline.zExpired Deprecated WrappersrrjMessagerrmz+ [ERROR] Found expired deprecated wrappers:ryN) r%r&r`r_rqrrr{r'r(r,)rrsr s rexpiryz_Reporter.expirys   ((39L9L9T9Tbl)E   Ye  4 # c" #    & &u - A B %cU|$ %rerror_on_chainsrLrc|Dcgc]}|js|}}|Dcgc]}|js|}}|Dcgc]}|js|}}|Dcgc]}|j|}}|s|s|s|sy|rtj||rtj ||rtj||rtj ||ycc}wcc}wcc}wcc}w)zGPrint categorised diagnostics and return whether any issues were found.FrT)rrrrr%rr)rLrrrrrrs rissuesz_Reporter.issues s$+=aann= =-4!P8O8O!!P!P '711;;Q7 7$A (@!AA 6)v   " "< 0 !  , ,-C D     *    V?  ;#>!P7As+CCCCC#C#C(+C()F)$__name__ __module__ __qualname__rr&bool__annotations__r]rr^r_r`r\ra_rich_box_import rich.consolerb _RichConsole rich.tablerc_RichTable_import ImportError staticmethodr'rWrtlisttuplerr rrrrrrrrr%r%s7+F3It3D#D#IsJ  089$ & ~4(<<#<<3S##RU44 4 4  4 5c?# 44 44(  D!78  T      d+A&B  t     45 $  ,EJ  d12  d  t     %S %d % %QV34$[_k    s&DD D r%versionct|} t|||S#t$r3}t|rt ddnt d|dYd}~yd}~wwxYw)u[Run the expiry scan and return expired wrapper messages, or None when packaging is unavailable. Caller is responsible for setting up ``sys.path`` via :func:`_managed_sys_path` before calling. Args: path: Package directory path or importable module name string. version: Current package version for comparison, or None to auto-detect. recursive: Scan submodules recursively. Returns: List of expired wrapper message strings (may be empty), or None when the ``packaging`` library is unavailable (advisory — warning already printed to stderr). r6mThe 'expiry' subcommand requires the 'packaging' library. Install it with: `pip install 'pyDeprecate[audit]'`TrzCould not determine the current package version automatically. Pass --version explicitly, or ensure the package is installed and importable. Original error: N)r rr"_is_missing_packaging_import_errorr,)r-rr7rOexcs r _do_expiryr#sn't,K*;9UU  -c 2 F  ##&%)   s  A)AArc|t|ddfD];}|t|dd}t|ts$|dk(s|jds;ydt|vS)aReturn True when an ImportError was caused by a missing packaging dependency. Args: error: The ImportError raised while trying to inspect expiry information. Returns: True if the error indicates that the ``packaging`` library is unavailable. __cause__Nr packagingz packaging.TzNo module named 'packaging')getattr isinstancerWr;)rrrs rrrGsgwuk489 ; sFD) dC dk&9T__\=Z  )CJ 66r user_providedrc t|}td|||rdnd}td|d|d|dytd|y) zMPrint a consistent scan header: scanning location, package name, and version.z Scanning: Nz user-providedz auto-detectedz Package: z Version: z ())r r,)r-rrrsources r_print_scan_headerr_sV t $F Zv $16(+gYbBC6(#$r) _wrappers exit_zerorc"|,t|t|5t||}ddd|s tdytj |dr tdn tdt d |D}|s|rd SdS#1swY_xYw) aScan Python code for misconfigured ``@deprecated`` wrappers and deprecation chains. Reports invalid argument mappings (exit 1), identity mappings, no-effect wrappers, and deprecation chains (advisory warnings only, exit 0). Use the ``chains`` subcommand for a dedicated hard-error chain check. Args: path: Path to the module, package directory, or importable module name to scan. recursive: Scan submodules recursively (default True). Pass ``--norecursive`` to scan top-level only. exit_zero: Always exit 0 even if hard errors (invalid argument mappings) are found. Useful for advisory CI steps that should report but never block. _wrappers: Pre-scanned wrapper list. When provided, skips the scan step. Underscore prefix hides this parameter from the Fire CLI (internal use by ``cmd_all`` only). Returns: 0 on success or advisory-only issues; 1 when hard errors are found and ``exit_zero`` is False. Nr6zNo deprecated callables found.rFrz* Issues were found in deprecated wrappers.z& All deprecated wrappers look correct!c34K|]}|jywr1)r)r<rs rr?zcmd_check..s8ann8r/)rr rVr,r%rrJ)r-r7rr has_invalids r cmd_checkrjs24 t $ >"49=I > /0 59<=898i88K+1414 > >s BBc| t|}|Q||ntt||}t|||dut |5t |||}dddy|}n|t ddy t||}|s t d ytj|t d t|d |rdSd S#1swYmxYw#t$rt ddYywxYw) aCheck for deprecated wrappers that have passed their scheduled removal version. Requires the ``packaging`` library: ``pip install 'pyDeprecate[audit]'``. A missing ``packaging`` library is treated as advisory (returns 0 with a warning). Args: path: Path to the module, package directory, or importable module name to scan. version: Current package version for comparison (e.g. ``"2.0.0"``). Auto-detected from installed package metadata if not provided. recursive: Scan submodules recursively (default True). Pass ``--norecursive`` to scan top-level only. exit_zero: Always exit 0 even if expired wrappers are found. Useful for advisory CI steps that should report but never block. _wrappers: Pre-scanned wrapper list. When provided, skips the scan step and derives expired wrappers via ``_check_expiry_for_callables``. Requires *version* to be non-``None`` when set. Underscore prefix hides this parameter from the Fire CLI (internal use by ``cmd_all`` only). Returns: 0 on success or when the ``packaging`` library is unavailable; 1 when expired wrappers are found and ``exit_zero`` is False. Nr-rrzECannot check expiry: version not resolved. Pass --version explicitly.Trrz%No expired deprecated wrappers found.rxz expired wrapper(s) found.r/) rWrr rr rr,rrr%rrU)r-rr7rrresolved_versionrawrs r cmd_expiryrs>g,&-&97?STefjTkrv?w4!1PTATU t $ @T#3Y?C @ ; ? Zcg h 1)WEG 67 W RG ~7 891 q 1 @ @  F    sB?2 C ?C C$#C$cP|5t|t|5tt||}ddd|Dcgc]}|j|}}|s t dyt j|dt dt|d|rdSd S#1swYhxYwcc}w) aDetect deprecated wrappers whose ``target`` is itself a deprecated callable (chains). Two chain kinds are detected: ``target`` (forwarding chain to another deprecated callable) and ``stacked`` (composed argument mappings that should be collapsed). Args: path: Path to the module, package directory, or importable module name to scan. recursive: Scan submodules recursively (default True). Pass ``--norecursive`` to scan top-level only. exit_zero: Always exit 0 even if chains are found. Useful for advisory CI steps that should report but never block. _wrappers: Pre-scanned wrapper list. When provided, skips the scan step and filters for ``chain_type is not None`` internally. Underscore prefix hides this parameter from the Fire CLI (internal use by ``cmd_all`` only). Returns: 0 when no chains are found or ``exit_zero`` is True; 1 when chains are found. Nr6zNo deprecation chains found.rTrrxz deprecation chain(s) found.r/) rr rr rr,r%rrU)r-r7rrrrs r cmd_chainsrs24 t $ e34H4NZcdI e" ?Aall&>a ?F ? -. V4( RF }8 9:1 q  e e ?sBB#B#B c| t|}t|jr|nd}||ntt ||}t |||dut |5t||}dddt||d}t|||d|}t||d|} t||||t|xs|xs| } | r|rd Sd S#1swYaxYw) aRun all three checks then append a deprecation table. Performs a single scan pass and distributes the wrappers to ``cmd_check``, ``cmd_expiry``, and ``cmd_chains`` so the filesystem is only traversed once. After all three checks complete, ``cmd_status`` is always called to append a compact markdown deprecation table to the output. Version is auto-detected from installed package metadata when not provided. A missing ``packaging`` library skips the expiry check with a warning and does not count as a hard error. Args: path: Path to the module, package directory, or importable module name to scan. version: Current package version for expiry comparison (e.g. ``"2.0.0"``). Auto-detected from installed package metadata if not provided. recursive: Scan submodules recursively (default True). Pass ``--norecursive`` to scan top-level only. exit_zero: Always exit 0 even if issues are found. Useful for advisory CI steps that should report but never block. Returns: 0 when all checks pass or ``exit_zero`` is True; 1 when any hard error is found. The deprecation table is always appended regardless of pass/fail outcome. Nrrr6F)r7rr)rr7rr)rr7rrr/) rWrexistsrr rr rVrrr cmd_statusr) r-rr7r version_pathrwrappers check_code expiry_code chains_code has_errorss rcmd_allrs:g,:,,.4DL&,@ARSWAX_k,lt-WD=PQ 4 9di89 49QYZJT+;y\amuvKTY%S[\Kt-hWj>K>;?J)12299s CCrninclude_membersoutputc| t|} t|}t |} ||n t| | } |5t|| |du t|5t| | ||| } dddnt| | || } tjr0d dl m} tjj!|  n t  |Kt#|} | j$j'dd| j)| dt d| dy #t$rDdjdtD}t d|d|ddtj }YGwxYw#1swYxYw)u Print a markdown deprecation status table to stdout. Scans the target package for deprecated wrappers and renders their lifecycle status as a Markdown table. Standalone — runs no checks, always exits 0. When ``--output`` is given, the table is also written to that file. Args: path: Path to the module, package directory, or importable module name to scan. version: Current package version for lifecycle status (e.g. ``"2.0.0"``). Auto-detected from installed package metadata if not provided. recursive: Scan submodules recursively (default True). Pass ``--norecursive`` to scan top-level only. style: Table format — ``compact`` (default) or ``matrix``. include_members: Include deprecated class members such as methods and constructors (default True). output: Optional file path to write the markdown table. The table is always printed to stdout regardless of this flag. Returns: Always 0 — status table generation is not a pass/fail gate. Nrc34K|]}|jywr1)r)r<ss rr?zcmd_status..Qs6a!''6rzInvalid style z.; falling back to 'compact'. Expected one of: rzTrrr)current_versionr7rnr)rrnrr)Markdown)parentsexist_okutf-8encodingu→ Saved to: )rWrrXrr,COMPACTr rrr rr%r& rich.markdownrr'r(rr:mkdir write_text)r-rr7rnrrr table_stylevalidrOrmarkdownrout_paths rrr.s<g,) ' 't,K")"5w;OP[bf;g4!1PTATU t $ 1 0#! / H  . ,  *""8H#56x <dT:Hw7z*48 M ) 6:66y(VW\V]]^_hlm (( )  s DE%A E"!E"%E.r~.).Nc`tjdtdtddffd }|S)ajWrap a cmd_* function so its integer return value becomes a sys.exit() call. Acts as the single top-level exception handler for the CLI: unhandled exceptions are converted to a non-zero sys.exit with the exception message as the exit code string. SystemExit is re-raised unchanged so Fire's --help and normal exits pass through unmodified. argskwargsrNc tj|i|y#t$rt$r(}tjt |Yd}~yd}~wwxYwr1)r)exitrHrIrW)rrrr~s rwrapperz_wrap..wrappersL  HHR(( )    HHSX   sAAA) functoolswrapsobject)r~rs` r_wrapr~s<__RvD Nrc&tjtjfD]b}t|dst |ddj dk7s/t jt5|jdddddy#1swYoxYw)a Reconfigure stdout/stderr to UTF-8 on platforms where the default encoding may reject non-ASCII characters. On Windows the default console codec (``charmap``) cannot encode Unicode emoji used by :class:`~deprecate.audit.DeprecationStatus`. Calling ``reconfigure`` before any output is written ensures emoji reach the terminal (or CI log) without a :exc:`UnicodeEncodeError`. The call is a no-op when the streams are already UTF-8 or when they lack a ``reconfigure`` method (binary streams, pytest capture wrappers). reconfigurerrrN) r)r*rhasattrrlower contextlibsuppressrIr)streams r_ensure_utf8_streamsr s}::szz*5 6= )gfj'.R.X.X.Z^e.e$$Y/ 5""G"4 5 55 5 5s )BB c vt ddl}hd}tj dd}|r|d|vr |ddvrdg|}j ttttttttttd| y#t$rtjdYwxYw) z CLI entry point for pydeprecate.rNzbThe 'pydeprecate' CLI requires the 'fire' package. Install it with: pip install 'pyDeprecate[cli]'>allcheckrrstatusr/>-h--helpr )r rrr r)command) r firerr)rrAFirerrrrrr)r subcommandsrAs rclirsxAK 88ABN/N$II9%J'J'>J'    x vwxsBB87B8)Tr1)rzTF)rzNTF)rzNTcompactTN)rN)1__doc__rrimportlib.utilrr)collections.abcrpathlibrtypingrrdeprecate._pkgrrr r r r deprecate.auditr rrrrrrrWrrr,rrRrVr%rrrrintrrrrrrr rrrrrs4  $ 666 (-$%#%$'=">%P@S@T@T:P5Q@:XXv S 8C= T htTWyFY H7k7d70%Z_%S%8C=%SW%dh%(5 9= (5 (5(5(5 345 (5  (5X! =! 9= =! =! c]=!=! =! 345 =! =!B#! 9= #! #!#!#! 345 #!  #!N! 03 03 c]0303 03  03h!  H 9=H H c]H H   H  H SM H 345H  H `hsCx Xi%8,5"r