fastcore 2.2.22__tar.gz → 2.2.23__tar.gz

{fastcore-2.2.22/fastcore.egg-info → fastcore-2.2.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastcore
-Version: 2.2.22
+Version: 2.2.23
 Summary: Python supercharged for fastai development
 Author-email: Jeremy Howard and Sylvain Gugger <infos@fast.ai>
 License: Apache-2.0
@@ -54,7 +54,7 @@ Here are some tips on using fastcore:
 - **Advanced file operations**: Use the extended `Path` class, which adds methods like `ls()`, `read_json()`, and others to [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path).
 - **Flexible data structures**: Convert between dictionaries and attribute-access objects using [`dict2obj`](https://fastcore.fast.ai/xtras.html#dict2obj) and [`obj2dict`](https://fastcore.fast.ai/xtras.html#obj2dict) for more intuitive data handling.
 - **Functional programming paradigms**: Use tools like [`compose`](https://fastcore.fast.ai/basics.html#compose), [`maps`](https://fastcore.fast.ai/basics.html#maps), and [`filter_ex`](https://fastcore.fast.ai/basics.html#filter_ex) to write more functional-style Python code.
-- **Documentation**: Use [`docments`](https://fastcore.fast.ai/docments.html#docments) where possible to document parameters of functions and methods.
+- **Documentation**: Document parameters and return values with [`docments`](https://fastcore.fast.ai/docments.html#docments), using source comments or `Annotated` metadata for generated APIs. [`MarkdownRenderer`](https://fastcore.fast.ai/docments.html#markdownrenderer) shows the effective signature and retains usage sections such as Notes, Raises, and Examples.
 - **Time-aware caching**: Apply the [`timed_cache`](https://fastcore.fast.ai/xtras.html#timed_cache) decorator to add time-based expiration to the standard `lru_cache` functionality.
 - **Simplified CLI creation**: Use `fastcore.script` to easily transform Python functions into command-line interfaces.
 

{fastcore-2.2.22 → fastcore-2.2.23}/README.md

@@ -23,7 +23,7 @@ Here are some tips on using fastcore:
 - **Advanced file operations**: Use the extended `Path` class, which adds methods like `ls()`, `read_json()`, and others to [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path).
 - **Flexible data structures**: Convert between dictionaries and attribute-access objects using [`dict2obj`](https://fastcore.fast.ai/xtras.html#dict2obj) and [`obj2dict`](https://fastcore.fast.ai/xtras.html#obj2dict) for more intuitive data handling.
 - **Functional programming paradigms**: Use tools like [`compose`](https://fastcore.fast.ai/basics.html#compose), [`maps`](https://fastcore.fast.ai/basics.html#maps), and [`filter_ex`](https://fastcore.fast.ai/basics.html#filter_ex) to write more functional-style Python code.
-- **Documentation**: Use [`docments`](https://fastcore.fast.ai/docments.html#docments) where possible to document parameters of functions and methods.
+- **Documentation**: Document parameters and return values with [`docments`](https://fastcore.fast.ai/docments.html#docments), using source comments or `Annotated` metadata for generated APIs. [`MarkdownRenderer`](https://fastcore.fast.ai/docments.html#markdownrenderer) shows the effective signature and retains usage sections such as Notes, Raises, and Examples.
 - **Time-aware caching**: Apply the [`timed_cache`](https://fastcore.fast.ai/xtras.html#timed_cache) decorator to add time-based expiration to the standard `lru_cache` functionality.
 - **Simplified CLI creation**: Use `fastcore.script` to easily transform Python functions into command-line interfaces.
 

{fastcore-2.2.22 → fastcore-2.2.23}/fastcore/__init__.py

@@ -14,7 +14,7 @@ Here are some tips on using fastcore:
 - **Advanced file operations**: Use the extended `Path` class, which adds methods like `ls()`, `read_json()`, and others to `pathlib.Path`.
 - **Flexible data structures**: Convert between dictionaries and attribute-access objects using `dict2obj` and `obj2dict` for more intuitive data handling.
 - **Functional programming paradigms**: Use tools like `compose`, `maps`, and `filter_ex` to write more functional-style Python code.
-- **Documentation**: Use `docments` where possible to document parameters of functions and methods.
+- **Documentation**: Document parameters and return values with `docments`, using source comments or `Annotated` metadata for generated APIs. `MarkdownRenderer` shows the effective signature and retains usage sections such as Notes, Raises, and Examples.
 - **Time-aware caching**: Apply the `timed_cache` decorator to add time-based expiration to the standard `lru_cache` functionality.
 - **Simplified CLI creation**: Use `fastcore.script` to easily transform Python functions into command-line interfaces.
 
@@ -55,4 +55,4 @@ Modules:
 - `fastcore.xml`: Concise generation of XML.
 - `fastcore.xtras`: Utility functions used in the fastai library"""
 
-__version__ = "2.2.22"
+__version__ = "2.2.23"

{fastcore-2.2.22 → fastcore-2.2.23}/fastcore/_modidx.py

@@ -315,11 +315,8 @@ d = { 'settings': { 'branch': 'main',
                                    'fastcore.docments.DocmentTbl.__eq__': ('docments.html#docmenttbl.__eq__', 'fastcore/docments.py'),
                                    'fastcore.docments.DocmentTbl.__init__': ('docments.html#docmenttbl.__init__', 'fastcore/docments.py'),
                                    'fastcore.docments.DocmentTbl._columns': ('docments.html#docmenttbl._columns', 'fastcore/docments.py'),
-                                   'fastcore.docments.DocmentTbl._hdr_list': ('docments.html#docmenttbl._hdr_list', 'fastcore/docments.py'),
                                    'fastcore.docments.DocmentTbl._repr_markdown_': ( 'docments.html#docmenttbl._repr_markdown_',
                                                                                      'fastcore/docments.py'),
-                                   'fastcore.docments.DocmentTbl._row': ('docments.html#docmenttbl._row', 'fastcore/docments.py'),
-                                   'fastcore.docments.DocmentTbl._row_list': ('docments.html#docmenttbl._row_list', 'fastcore/docments.py'),
                                    'fastcore.docments.DocmentTbl.has_docment': ( 'docments.html#docmenttbl.has_docment',
                                                                                  'fastcore/docments.py'),
                                    'fastcore.docments.DocmentTbl.has_return': ( 'docments.html#docmenttbl.has_return',
@@ -361,12 +358,11 @@ d = { 'settings': { 'branch': 'main',
                                    'fastcore.docments._DocstringExtractor.visit_Module': ( 'docments.html#_docstringextractor.visit_module',
                                                                                            'fastcore/docments.py'),
                                    'fastcore.docments._bold': ('docments.html#_bold', 'fastcore/docments.py'),
+                                   'fastcore.docments._callable_instance': ('docments.html#_callable_instance', 'fastcore/docments.py'),
                                    'fastcore.docments._clean_comment': ('docments.html#_clean_comment', 'fastcore/docments.py'),
                                    'fastcore.docments._clean_text_sig': ('docments.html#_clean_text_sig', 'fastcore/docments.py'),
                                    'fastcore.docments._docstring': ('docments.html#_docstring', 'fastcore/docments.py'),
                                    'fastcore.docments._escape_markdown': ('docments.html#_escape_markdown', 'fastcore/docments.py'),
-                                   'fastcore.docments._f_name': ('docments.html#_f_name', 'fastcore/docments.py'),
-                                   'fastcore.docments._fmt_anno': ('docments.html#_fmt_anno', 'fastcore/docments.py'),
                                    'fastcore.docments._fmt_default': ('docments.html#_fmt_default', 'fastcore/docments.py'),
                                    'fastcore.docments._fmt_sig': ('docments.html#_fmt_sig', 'fastcore/docments.py'),
                                    'fastcore.docments._fullname': ('docments.html#_fullname', 'fastcore/docments.py'),
@@ -377,13 +373,11 @@ d = { 'settings': { 'branch': 'main',
                                    'fastcore.docments._ital_first': ('docments.html#_ital_first', 'fastcore/docments.py'),
                                    'fastcore.docments._list2row': ('docments.html#_list2row', 'fastcore/docments.py'),
                                    'fastcore.docments._maybe_nm': ('docments.html#_maybe_nm', 'fastcore/docments.py'),
-                                   'fastcore.docments._merge_doc': ('docments.html#_merge_doc', 'fastcore/docments.py'),
                                    'fastcore.docments._merge_docs': ('docments.html#_merge_docs', 'fastcore/docments.py'),
-                                   'fastcore.docments._non_empty_keys': ('docments.html#_non_empty_keys', 'fastcore/docments.py'),
                                    'fastcore.docments._param_locs': ('docments.html#_param_locs', 'fastcore/docments.py'),
                                    'fastcore.docments._parses': ('docments.html#_parses', 'fastcore/docments.py'),
-                                   'fastcore.docments._show_param': ('docments.html#_show_param', 'fastcore/docments.py'),
                                    'fastcore.docments._tokens': ('docments.html#_tokens', 'fastcore/docments.py'),
+                                   'fastcore.docments._type_str': ('docments.html#_type_str', 'fastcore/docments.py'),
                                    'fastcore.docments._unwrap_sym': ('docments.html#_unwrap_sym', 'fastcore/docments.py'),
                                    'fastcore.docments.ann_parts': ('docments.html#ann_parts', 'fastcore/docments.py'),
                                    'fastcore.docments.can_render': ('docments.html#can_render', 'fastcore/docments.py'),
@@ -650,6 +644,7 @@ d = { 'settings': { 'branch': 'main',
                                'fastcore.nbio.new_nb': ('nbio.html#new_nb', 'fastcore/nbio.py'),
                                'fastcore.nbio.preferred_msg_out': ('nbio.html#preferred_msg_out', 'fastcore/nbio.py'),
                                'fastcore.nbio.preferred_out': ('nbio.html#preferred_out', 'fastcore/nbio.py'),
+                               'fastcore.nbio.prev_line': ('nbio.html#prev_line', 'fastcore/nbio.py'),
                                'fastcore.nbio.read_nb': ('nbio.html#read_nb', 'fastcore/nbio.py'),
                                'fastcore.nbio.render_output': ('nbio.html#render_output', 'fastcore/nbio.py'),
                                'fastcore.nbio.render_outputs': ('nbio.html#render_outputs', 'fastcore/nbio.py'),

{fastcore-2.2.22 → fastcore-2.2.23}/fastcore/apisurface.py

@@ -12,12 +12,13 @@ Docs: https://fastcore.fast.ai/apisurface.html.md"""
 __all__ = ['snake', 'sanitize_param_name', 'sanitized_params', 'mk_sig', 'mk_doc', 'OpGroup', 'mk_groups', 'full_docs']
 
 # %% ../nbs/05a_apisurface.ipynb #b2797a42
-import keyword
+import keyword,inspect
 from inspect import Parameter, Signature
 from urllib.parse import urlparse, urljoin
 from .imports import *
 from .basics import *
 from .xtras import UNSET
+from .docments import ann_parts
 
 # %% ../nbs/05a_apisurface.ipynb #475598fa
 _pat_non_alnum = re.compile(r"[^a-zA-Z0-9]+")
@@ -32,13 +33,6 @@ def snake(s: str):
 # %% ../nbs/05a_apisurface.ipynb #3e19a6d0
 def sanitize_param_name(p): return snake(re.sub(r'\W', '_', p).strip('_'))
 
-# %% ../nbs/05a_apisurface.ipynb #f44a2c97
-def _mk_param(name, required, anno=None, default=None):
-    "Create a function signature parameter."
-    anno = Parameter.empty if anno is None else anno
-    if default is None: default = Parameter.empty if required else UNSET
-    return Parameter(name, kind=Parameter.POSITIONAL_OR_KEYWORD, default=default, annotation=anno)
-
 # %% ../nbs/05a_apisurface.ipynb #c10b6dcc
 def sanitized_params(ps):
     "Mapping from spec param names `ps` to valid Python identifiers; exact names win collisions."
@@ -55,21 +49,28 @@ def sanitized_params(ps):
         res[p] = name
     return res
 
-# %% ../nbs/05a_apisurface.ipynb #32fca522
+# %% ../nbs/05a_apisurface.ipynb #f44a2c97
+def _mk_param(name, required, anno=None, default=Parameter.empty):
+    "Create a function signature parameter."
+    anno = Parameter.empty if anno is None else anno
+    if default is Parameter.empty: default = Parameter.empty if required else UNSET
+    return Parameter(name, kind=Parameter.POSITIONAL_OR_KEYWORD, default=default, annotation=anno)
+
 def _sort_key(o):
     if o.default is Parameter.empty: return 0
     if o.default is UNSET: return 1
     return 2
 
-# %% ../nbs/05a_apisurface.ipynb #4f63ac5e
 def mk_sig(op, sparams=None, defaults=None):
-    "An `inspect.Signature` for operation record `op`; `defaults` values make their params optional."
+    "An operation signature with parameter descriptions in `Annotated`; `defaults` makes those params optional"
     if sparams is None: sparams = sanitized_params(op.params)
     defaults = defaults or {}
     params = []
     for pname, sname in sparams.items():
-        default = defaults.get(pname, op.param_defaults.get(pname))
-        params.append(_mk_param(sname, pname in op.required_params, op.param_types.get(pname), default))
+        default = defaults.get(pname, op.param_defaults.get(pname, Parameter.empty))
+        anno = op.param_types.get(pname)
+        if doc := op.param_docs.get(pname): anno = typing.Annotated[anno or typing.Any, doc]
+        params.append(_mk_param(sname, pname in op.required_params, anno, default))
     return Signature(sorted(params, key=_sort_key))
 
 # %% ../nbs/05a_apisurface.ipynb #940536d9
@@ -81,14 +82,6 @@ def _op_summary(op):
     base = f"{p.scheme}://{p.netloc}"
     return re.sub(r"\]\((/[^)]+)\)", lambda m: f"]({urljoin(base, m[1].strip())})", s)
 
-# %% ../nbs/05a_apisurface.ipynb #08067b8a
-def _op_line(op, sig):
-    head = f"{'.'.join(snake(g) for g in listify(op.group))}.{op.name}"
-    if op.docs_url: head = f"[{head}]({op.docs_url})" 
-    s = f"({', '.join(sig.parameters)})"
-    summ = _op_summary(op)
-    return f"{head}{s}: *{summ}*"
-
 # %% ../nbs/05a_apisurface.ipynb #ed62e194
 def mk_doc(op, sig, sparams):
     "Render operation docstring with summary, docs URL, and parameter hints."
@@ -102,11 +95,19 @@ def mk_doc(op, sig, sparams):
         for nm,p in sig.parameters.items():
             orig = rsparams.get(nm, nm)
             r = f"default: {p.default!r}" if p.default not in (Parameter.empty, UNSET) else "required" if orig in req else "optional"
-            ann = '' if p.annotation is Parameter.empty else p.annotation.__name__
+            ann = '' if p.annotation is Parameter.empty else inspect.formatannotation(ann_parts(p.annotation)[0]).removeprefix('typing.')
             desc = (op.param_docs or {}).get(orig, "")
             lines.append(f"- {nm} ({ann}, {r}){': ' + desc if desc else ''}")
     return "\n".join(lines)
 
+# %% ../nbs/05a_apisurface.ipynb #08067b8a
+def _op_line(op, sig):
+    head = f"{'.'.join(snake(g) for g in listify(op.group))}.{op.name}"
+    if op.docs_url: head = f"[{head}]({op.docs_url})"
+    s = f"({', '.join(sig.parameters)})"
+    summ = _op_summary(op)
+    return f"{head}{s}: *{summ}*"
+
 # %% ../nbs/05a_apisurface.ipynb #e4d35409
 class OpGroup:
     "Namespace for grouped operations: each op is an attribute, and the repr lists them all"
@@ -123,10 +124,9 @@ class OpGroup:
     def __dir__(self): return object.__dir__(self)
     def __allow__(self): return self.ops + list(self.subgroups.values())
 
-    def _repr_markdown_(self): return self.__doc__
+    def _repr_markdown_(self): return self.__doc__ + '\n\nOverview only. Read `doc(group.operation)` for parameter details and `doc(group.subgroup)` to descend.'
     __repr__ = _repr_markdown_
 
-
 # %% ../nbs/05a_apisurface.ipynb #62b12f6b
 def mk_groups(ops):
     "Nested tree of `OpGroup`s from ops, following each op's `group` path."
@@ -152,6 +152,6 @@ def _group_docs(name, g, lvl=2):
     return "\n\n".join(res)
 
 def full_docs(groups):
-    "Complete markdown API reference for a `mk_groups` tree: every group and operation."
+    "Markdown overview of every group and operation in a `mk_groups` tree."
     return "\n\n".join(_group_docs(nm, g) for nm,g in sorted(groups.items()))
 

{fastcore-2.2.22 → fastcore-2.2.23}/fastcore/docments.py

@@ -29,23 +29,27 @@ from tokenize import tokenize,COMMENT
 from ast import parse,FunctionDef,AsyncFunctionDef,AnnAssign
 from io import BytesIO
 from textwrap import dedent
-from types import SimpleNamespace
-from inspect import getsource,isfunction,ismethod,isclass,signature,Parameter,Signature
-from dataclasses import dataclass, is_dataclass
+from inspect import getsource,isfunction,ismethod,isclass,signature,Parameter
+from dataclasses import is_dataclass
 from .utils import *
-from .meta import delegates
 from . import docscrape
-from textwrap import fill
 from inspect import isclass,getdoc,signature
 
 # %% ../nbs/04_docments.ipynb #53e21187
+def _callable_instance(sym): return callable(sym) and not (inspect.isroutine(sym) or isclass(sym))
+
 def docstring(sym):
-    "Get docstring for `sym` for functions ad classes"
+    "Get documentation from an object, its constructor, or its callable implementation"
     if isinstance(sym, str): return sym
+    if isinstance(sym, partial): return docstring(sym.func)
+    if _callable_instance(sym):
+        own = inspect.getattr_static(sym, '__doc__', None)
+        if own is not getattr(type(sym), '__doc__', None): return getdoc(sym) or ''
+        return getdoc(sym.__call__) or getdoc(sym) or ''
     res = getdoc(sym)
-    if not res and isclass(sym): res = getdoc(sym.__init__)
-    if not res and callable(sym) and not isclass(sym): res = getdoc(sym.__call__)
-    return res or ""
+    if not getattr(sym, '__doc__', None) and res == object.__init__.__doc__: res = None
+    if not res and isclass(sym) and sym.__init__ is not object.__init__: res = docstring(sym.__init__)
+    return res or ''
 
 # %% ../nbs/04_docments.ipynb #1e0cf854
 def parse_docstring(sym):
@@ -57,17 +61,45 @@ def isdataclass(s):
     "Check if `s` is a dataclass but not a dataclass' instance"
     return is_dataclass(s) and isclass(s)
 
-# %% ../nbs/04_docments.ipynb #6549c4b2
 def get_dataclass_source(s):
     "Get source code for dataclass `s`"
     return getsource(s) if not getattr(s, "__module__") == '__main__' else ""
 
-# %% ../nbs/04_docments.ipynb #cac59989
 def get_source(s):
-    "Get source code for string, function object or dataclass `s`"
+    "Get source for a function, callable implementation, dataclass, or source string"
     if isinstance(s,str): return s
+    s = inspect.unwrap(s)
+    if isinstance(s, partial): s = s.func
+    if _callable_instance(s): s = s.__call__
     return getsource(s) if isfunction(s) or ismethod(s) else get_dataclass_source(s) if isdataclass(s) else None
 
+# %% ../nbs/04_docments.ipynb #40e3f274
+def _get_property_name(p):
+    "Get the name of property `p`"
+    if hasattr(p, 'fget'): return p.fget.func.__qualname__ if hasattr(p.fget, 'func') else p.fget.__qualname__
+    else: return next(iter(re.findall(r'\'(.*)\'', str(p)))).split('.')[-1]
+
+def get_name(obj):
+    "Get the name of `obj`"
+    if isinstance(obj, partial):
+        nm = get_name(obj.func)
+        args = [repr(a) for a in obj.args] + [f'{k}={repr(v)}' for k,v in obj.keywords.items()]
+        return f"{nm}[partial: {', '.join(args)}]"
+    if hasattr(obj, '__name__'):       return obj.__name__
+    elif getattr(obj, '_name', False): return obj._name
+    elif hasattr(obj,'__origin__'):    return str(obj.__origin__).split('.')[-1]
+    elif type(obj)==property:          return _get_property_name(obj)
+    elif callable(obj):                return type(obj).__name__
+    else:                              return str(obj).split('.')[-1]
+
+
+# %% ../nbs/04_docments.ipynb #5e273f22
+def qual_name(obj):
+    "Get the qualified name of `obj`"
+    if hasattr(obj,'__qualname__'): return obj.__qualname__
+    if ismethod(obj):       return f"{get_name(obj.__self__)}.{get_name(obj)}"
+    return get_name(obj)
+
 # %% ../nbs/04_docments.ipynb #91c0d15f
 def _parses(s):
     "Parse source of function, method, or dataclass `s`"
@@ -87,13 +119,14 @@ def _clean_comment(s):
     res = _clean_re.findall(s)
     return res[0] if res else None
 
+# %% ../nbs/04_docments.ipynb #448097bb
 def _param_locs(s, returns=True, args_kwargs=False):
     "`dict` of parameter line numbers to names"
     body = _parses(s).body
     if len(body)==1:
         defn = body[0]
         if isinstance(defn, (FunctionDef, AsyncFunctionDef)):
-            res = {arg.lineno:arg.arg for arg in defn.args.args}
+            res = {arg.lineno:arg.arg for arg in [*defn.args.posonlyargs, *defn.args.args]}
             # Add *args if present
             if defn.args.vararg: res[defn.args.vararg.lineno] = defn.args.vararg.arg
             # Add keyword-only args
@@ -127,49 +160,6 @@ def _get_full(p, docs, eval_str=False):
         elif eval_str: anno = None
     return AttrDict(docment=docs.get(p.name), anno=anno, default=p.default, kind=p.kind)
 
-# %% ../nbs/04_docments.ipynb #1b4d817c
-def _merge_doc(dm, npdoc):
-    if not npdoc: return dm
-    if not isinstance(dm, dict): return dm or '\n'.join(npdoc.desc)
-    # if not dm.anno or dm.anno==empty: dm.anno = npdoc.type
-    if not dm.docment: dm.docment = '\n'.join(npdoc.desc)
-    return dm
-
-def _merge_docs(dms, npdocs):
-    npparams = npdocs['Parameters']
-    params = {nm:_merge_doc(dm,npparams.get(nm,None)) for nm,dm in dms.items()}
-    if 'return' in dms: params['return'] = _merge_doc(dms['return'], npdocs['Returns'])
-    return params
-
-# %% ../nbs/04_docments.ipynb #40e3f274
-def _get_property_name(p):
-    "Get the name of property `p`"
-    if hasattr(p, 'fget'):
-        return p.fget.func.__qualname__ if hasattr(p.fget, 'func') else p.fget.__qualname__
-    else: return next(iter(re.findall(r'\'(.*)\'', str(p)))).split('.')[-1]
-
-# %% ../nbs/04_docments.ipynb #da0465e3
-def get_name(obj):
-    "Get the name of `obj`"
-    if isinstance(obj, partial):
-        nm = get_name(obj.func)
-        args = [repr(a) for a in obj.args] + [f'{k}={repr(v)}' for k,v in obj.keywords.items()]
-        return f"{nm}[partial: {', '.join(args)}]"
-    if hasattr(obj, '__name__'):       return obj.__name__
-    elif getattr(obj, '_name', False): return obj._name
-    elif hasattr(obj,'__origin__'):    return str(obj.__origin__).split('.')[-1]
-    elif type(obj)==property:          return _get_property_name(obj)
-    elif callable(obj):                return type(obj).__name__
-    else:                              return str(obj).split('.')[-1]
-
-
-# %% ../nbs/04_docments.ipynb #5e273f22
-def qual_name(obj):
-    "Get the qualified name of `obj`"
-    if hasattr(obj,'__qualname__'): return obj.__qualname__
-    if ismethod(obj):       return f"{get_name(obj.__self__)}.{get_name(fn)}"
-    return get_name(obj)
-
 # %% ../nbs/04_docments.ipynb #2e865627
 def ann_parts(anno):
     "The underlying type and metadata tuple of an `Annotated`, else `(anno, ())`"
@@ -178,9 +168,16 @@ def ann_parts(anno):
     t = None if args[0] is type(None) else args[0]
     return t, args[1:]
 
+# %% ../nbs/04_docments.ipynb #1b4d817c
+def _merge_docs(dms, npdocs):
+    for nm,dm in dms.items():
+        npdoc = npdocs['Returns'] if nm=='return' else npdocs['Parameters'].get(nm)
+        if npdoc and not dm.docment: dm.docment = '\n'.join(npdoc.desc)
+    return dms
+
 # %% ../nbs/04_docments.ipynb #9b62ab20
 def docments(s, full=False, eval_str=False, returns=True, args_kwargs=False):
-    "Get docments for `s`"
+    "Get parameter and return documentation from comments, `Annotated` metadata, and NumPy docstrings"
     if isclass(s) and not is_dataclass(s): s = s.__init__
     try: sig = signature_ex(s, eval_str=eval_str)
     except (ValueError, TypeError): return AttrDict()
@@ -192,18 +189,13 @@ def docments(s, full=False, eval_str=False, returns=True, args_kwargs=False):
         for k,v in p.items():
             if v not in docs: docs[v] = _get_comment(k, v, c, p)
         s = getattr(s, '__delwrap__', None)
-    
-    res = {k:_get_full(v, docs, eval_str=eval_str) if full else docs.get(k) for k,v in sig.parameters.items()}
-    if returns:
-        if full: res['return'] = AttrDict(docment=docs.get('return'), anno=sig.return_annotation, default=empty)
-        else: res['return'] = docs.get('return')
-    for k,p in sig.parameters.items():
-        if (res[k].docment if full else res[k]) is None:
-            am = first(o for o in ann_parts(p.annotation)[1] if isinstance(o,str))
-            if am is None: continue
-            if full: res[k].docment = am
-            else: res[k] = am
-    return AttrDict(_merge_docs(res, nps))
+
+    res = {k:_get_full(v, docs, eval_str=eval_str) for k,v in sig.parameters.items()}
+    if returns: res['return'] = AttrDict(docment=docs.get('return'), anno=sig.return_annotation, default=empty)
+    for dm in res.values():
+        if dm.docment is None: dm.docment = first(o for o in ann_parts(dm.anno)[1] if isinstance(o,str))
+    res = _merge_docs(res, nps)
+    return AttrDict(res if full else {k:v.docment for k,v in res.items()})
 
 # %% ../nbs/04_docments.ipynb #40cdbeb2
 def sig_source(obj):
@@ -221,7 +213,7 @@ def _get_params(node):
     if node.args.kwarg: params.append(f"**{node.args.kwarg.arg}")
     return ", ".join(params)
 
-# %% ../nbs/04_docments.ipynb #180b4c2d
+# %% ../nbs/04_docments.ipynb #5dc1b730
 class _DocstringExtractor(ast.NodeVisitor):
     def __init__(self): self.docstrings,self.cls,self.cls_init = {},None,None
 
@@ -252,7 +244,7 @@ class _DocstringExtractor(ast.NodeVisitor):
         if module_doc: self.docstrings['_module'] = (module_doc, "")
         self.generic_visit(node)
 
-# %% ../nbs/04_docments.ipynb #b1d612e9
+# %% ../nbs/04_docments.ipynb #ac56083a
 def extract_docstrings(code):
     "Create a dict from function/class/method names to tuples of docstrings and param lists"
     extractor = _DocstringExtractor()
@@ -260,21 +252,19 @@ def extract_docstrings(code):
     return extractor.docstrings
 
 # %% ../nbs/04_docments.ipynb #e4e1b815
-def _non_empty_keys(d:dict): return L([k for k,v in d.items() if v != inspect._empty])
 def _bold(s): return f'**{s}**' if s.strip() else s
 
+def _maybe_nm(o):
+    if (o == inspect._empty): return ''
+    else: return o.__name__ if hasattr(o, '__name__') else str(o)
+
 # %% ../nbs/04_docments.ipynb #ac070254
 def _escape_markdown(s):
     for c in '|^': s = re.sub(rf'\\?\{c}', rf'\{c}', s)
     return s.replace('\n', '<br>')
 
-# %% ../nbs/04_docments.ipynb #ced78f56
-def _maybe_nm(o):
-    if (o == inspect._empty): return ''
-    else: return o.__name__ if hasattr(o, '__name__') else str(o)
-
 # %% ../nbs/04_docments.ipynb #fe6d83f1
-def _list2row(l:list): return '| '+' | '.join([_maybe_nm(o) for o in l]) + ' |'
+def _list2row(l:list): return '| '+' | '.join(_escape_markdown(_maybe_nm(o)) for o in l) + ' |'
 
 # %% ../nbs/04_docments.ipynb #44ac2e4f
 class _DocmentBase:
@@ -285,49 +275,42 @@ class _DocmentBase:
     @property
     def has_docment(self): return any(v.get('docment') for v in self.dm.values())
 
-# %% ../nbs/04_docments.ipynb #b45f731d
+# %% ../nbs/04_docments.ipynb #f7c36bf3
 class DocmentTbl(_DocmentBase):
-    _map = {'anno':'Type', 'default':'Default', 'docment':'Details'}
+    _map = dict(anno='Type', default='Default', docment='Details')
 
     def __init__(self, obj, verbose=True, returns=True):
         "Compute the docment table string"
         super().__init__(obj)
         self.verbose = verbose
         self.returns = False if isdataclass(obj) else returns
-        try: self.params = L(signature(obj, eval_str=True).parameters.keys())
-        except (ValueError,TypeError): self.params=[]
+        self.params = L(k for k in self.dm if k!='return')
         for d in self.dm.values(): d['docment'] = ifnone(d['docment'], inspect._empty)
 
     @property
     def _columns(self):
-        "Compute the set of fields that have at least one non-empty value so we don't show tables empty columns"
-        cols = set(flatten(L(self.dm.values()).filter().map(_non_empty_keys)))
+        "Fields with at least one non-empty value"
         candidates = self._map if self.verbose else {'docment': 'Details'}
-        return {k:v for k,v in candidates.items() if k in cols}
+        return {k:v for k,v in candidates.items() if any(d[k] != empty for d in self.dm.values())}
 
     @property
-    def has_docment(self): return 'docment' in self._columns and self._row_list
+    def has_docment(self): return 'docment' in self._columns and bool(self.params)
 
     @property
-    def has_return(self): return self.returns and bool(_non_empty_keys(self.dm.get('return', {})))
-
-    def _row(self, nm, props): return [nm] + [props[c] for c in self._columns]
-
-    @property
-    def _row_list(self):
-        ordered_params = [(p, self.dm[p]) for p in self.params if p != 'self' and p in self.dm]
-        return L([self._row(nm, props) for nm,props in ordered_params])
-
-    @property
-    def _hdr_list(self): return ['  '] + [_bold(l) for l in L(self._columns.values())]
+    def has_return(self): return self.returns and any(v != empty for v in self.dm.get('return', {}).values())
 
     @property
     def hdr_str(self):
-        md = _list2row(self._hdr_list)
-        return md + '\n' + _list2row(['-' * len(l) for l in self._hdr_list])
+        hdr = ['  '] + [_bold(v) for v in self._columns.values()]
+        return _list2row(hdr) + '\n' + _list2row(['---'] * len(hdr))
 
     @property
-    def params_str(self): return '\n'.join(self._row_list.map(_list2row))
+    def params_str(self):
+        cols,rows = self._columns,[]
+        for nm in self.params:
+            row = [nm] + [self.dm[nm][c] for c in cols]
+            rows.append(_list2row(row))
+        return '\n'.join(rows)
 
     @property
     def return_str(self): return _list2row(['**Returns**']+[_bold(_maybe_nm(self.dm['return'][c])) for c in self._columns])
@@ -342,6 +325,7 @@ class DocmentTbl(_DocmentBase):
     __str__ = _repr_markdown_
     __repr__ = basic_repr()
 
+
 # %% ../nbs/04_docments.ipynb #5af61ab1
 class DocmentList(_DocmentBase):
     def _fmt(self, nm, p):
@@ -353,12 +337,6 @@ class DocmentList(_DocmentBase):
     def _repr_markdown_(self): return '\n'.join(self._fmt(k,v) for k,v in self.dm.items())
     __repr__=__str__=_repr_markdown_
 
-# %% ../nbs/04_docments.ipynb #6355b569
-def _clean_text_sig(obj):
-    if not (sig := getattr(obj, '__text_signature__', None)): return None
-    sig = re.sub(r'\$\w+,?\s*', '', sig)
-    return get_name(obj) + sig.replace('<unrepresentable>', '...')
-
 # %% ../nbs/04_docments.ipynb #cfcc46bf
 def _fmt_sig(name, params, ret_str, maxline, prefix='def'):
     "Format function signature with params and docment comments"
@@ -369,7 +347,9 @@ def _fmt_sig(name, params, ret_str, maxline, prefix='def'):
             lines.append(', '.join(curr) + ',')
             curr = []
         curr.append(fmt)
-        if doc: lines.append(', '.join(curr) + ',' + comment); curr = []
+        if doc:
+            lines.append(', '.join(curr) + ',' + comment)
+            curr = []
     if curr: lines.append(', '.join(curr))
     pstr = '\n    '.join(lines)
     if not pstr: return f"{prefix} {name}({ret_str}"
@@ -381,6 +361,11 @@ def _fmt_default(o):
     return o.__name__ if hasattr(o, '__name__') else repr(o)
 
 # %% ../nbs/04_docments.ipynb #7f5e5282
+def _type_str(anno):
+    anno = ann_parts(anno)[0]
+    return inspect.formatannotation(anno).removeprefix('typing.').strip("'")
+
+# %% ../nbs/04_docments.ipynb #4c78c84f
 class DocmentText(_DocmentBase):
     def __init__(self, obj, maxline=110, docstring=True):
         super().__init__(obj)
@@ -389,46 +374,79 @@ class DocmentText(_DocmentBase):
     def _fmt_param(self, nm, p):
         anno,default,kind = p.get('anno',empty), p.get('default',empty), p.get('kind')
         pre = '*' if kind==Parameter.VAR_POSITIONAL else '**' if kind==Parameter.VAR_KEYWORD else ''
-        return pre + nm + (f':{_maybe_nm(anno)}' if anno != empty else '') + (f'={_fmt_default(default)}' if default != empty else '')
-    
-    @property
-    def _ret_str(self):
-        ret = self.dm.get('return', {})
-        anno = f"->{_maybe_nm(ret.get('anno',empty))}" if ret.get('anno',empty) != empty else ''
-        doc = f" # {ret['docment']}" if ret.get('docment') else ''
-        return f"){anno}:{doc}"
-    
-    @property
-    def params(self): return [(self._fmt_param(k,v), v.get('docment','')) for k,v in self.dm.items() if k != 'return']
-
-    def __str__(self):
-        o = self.obj
-        if not callable(o):
-            doc = docstring(o)
-            docstr = f'\n    "{doc}"' if self.docstring and doc else ''
-            return f"{type(o).__name__} instance: {truncstr(repr(o), 80)}{docstr}"
-        is_inst = callable(o) and not (isfunction(o) or isclass(o) or inspect.isbuiltin(o) or ismethod(o))
-        prefix = 'async def' if inspect.iscoroutinefunction(o) else 'def'
-        nm = get_name(o) if hasattr(o, '__name__') else f'{type(o).__name__}.__call__' if is_inst else get_name(o)
-        if (sig := _clean_text_sig(o)) and not self.params: sig_str = f"{prefix} {sig}"
-        else: sig_str = _fmt_sig(nm, self.params, self._ret_str, self.maxline, prefix=prefix)
-        doc = getattr(o.__call__, '__doc__', None) if is_inst else o.__doc__
-        docstr = f'    "{doc}"' if self.docstring and doc else ''
-        return f"{sig_str}\n{docstr}" if docstr else sig_str
-    
-    __repr__ = __str__
+        anno = f':{_type_str(anno)}' if anno != empty else ''
+        default = f'={_fmt_default(default)}' if default != empty else ''
+        return pre + nm + anno + default
+
     def _repr_markdown_(self): return f"```python\n{self}\n```"
 
+# %% ../nbs/04_docments.ipynb #ae2624ea
+@patch(as_prop=True)
+def params(self:DocmentText):
+    res,prev,star = [],None,False
+    for k,v in self.dm.items():
+        if k=='return': continue
+        kind = v.get('kind')
+        if prev==Parameter.POSITIONAL_ONLY and kind!=prev: res.append(('/', None))
+        if kind==Parameter.KEYWORD_ONLY and not star:
+            res.append(('*', None))
+            star = True
+        if kind==Parameter.VAR_POSITIONAL: star = True
+        res.append((self._fmt_param(k,v), v.get('docment','')))
+        prev = kind
+    if prev==Parameter.POSITIONAL_ONLY: res.append(('/', None))
+    return res
+
+# %% ../nbs/04_docments.ipynb #35564516
+def _clean_text_sig(obj):
+    if not (sig := getattr(obj, '__text_signature__', None)): return None
+    sig = re.sub(r'\$\w+,?\s*', '', sig)
+    return get_name(obj) + sig.replace('<unrepresentable>', '...')
+
+@patch(as_prop=True)
+def _ret_str(self:DocmentText):
+    ret = self.dm.get('return', {})
+    anno = f"->{_type_str(ret['anno'])}" if ret.get('anno',empty) != empty else ''
+    doc = f" # {ret['docment']}" if ret.get('docment') else ''
+    return f"){anno}:{doc}"
+
+# %% ../nbs/04_docments.ipynb #2309edc7
+@patch
+def __str__(self:DocmentText):
+    o = self.obj
+    doc = docstring(o)
+    docstr = f'\n    "{doc}"' if self.docstring and doc else ''
+    if not callable(o): return f"{type(o).__name__} instance: {truncstr(repr(o), 80)}{docstr}"
+    is_inst = _callable_instance(o)
+    async_ = inspect.iscoroutinefunction(o) or (is_inst and inspect.iscoroutinefunction(o.__call__))
+    prefix = 'async def' if async_ else 'def'
+    nm = f'{type(o).__name__}.__call__' if is_inst and not hasattr(o, '__name__') else get_name(o)
+    if (sig := _clean_text_sig(o)) and not self.params: sig_str = f"{prefix} {sig}"
+    else: sig_str = _fmt_sig(nm, self.params, self._ret_str, self.maxline, prefix=prefix)
+    return sig_str + docstr
+
+DocmentText.__repr__ = DocmentText.__str__
+
 # %% ../nbs/04_docments.ipynb #d44a7fe3
 def sig2str(func, maxline=110):
     "Generate function signature with docments as comments"
     return DocmentText(func, maxline=maxline, docstring=False)
 
 # %% ../nbs/04_docments.ipynb #07287425
-def _docstring(sym):
-    npdoc = parse_docstring(sym)
-    return '\n\n'.join([npdoc['Summary'], npdoc['Extended']]).strip()
-
+def _docstring(sym, dm):
+    doc = docstring(sym)
+    parts = re.split(r'(?m)^([\w ][\w ]*)\n[-=]{3,}[ \t]*\n', doc)
+    res = [parts[0]]
+    for title,body in zip(parts[1::2], parts[2::2]):
+        headers = [s for s in body.splitlines() if s and not s[0].isspace()]
+        if title=='Parameters' and headers:
+            params = [s.partition(':') for s in headers]
+            if all(sep and _type_str(dm.get(n.strip(), {}).get('anno', empty))==t.strip() for n,sep,t in params): continue
+        if title=='Returns' and len(headers)==1 and headers[0].strip()==_type_str(dm.get('return', {}).get('anno', empty)): continue
+        res.append(f'{title}\n{"-"*len(title)}\n{body}')
+    return '\n\n'.join(s.strip() for s in res if s.strip())
+
+# %% ../nbs/04_docments.ipynb #21ebcfcb
 def _unwrap_sym(sym):
     if not hasattr(sym, '__signature__'): sym = getattr(sym, '__wrapped__', sym)
     return (sym.fget or sym.fset or sym) if isinstance(sym, property) else sym
@@ -436,7 +454,9 @@ def _unwrap_sym(sym):
 def can_render(sym):
     "Check if `sym` has a renderable signature"
     sym = _unwrap_sym(sym)
-    try: signature(sym, eval_str=True); return True
+    try:
+        signature(sym, eval_str=True)
+        return True
     except (ValueError, TypeError): return False
 
 # %% ../nbs/04_docments.ipynb #9de89cb6
@@ -453,34 +473,21 @@ class ShowDocRenderer:
         self.isfunc = inspect.isfunction(sym)
         try: self.sig = signature(sym, eval_str=True)
         except (ValueError,TypeError): self.sig = None
-        self.docs = _docstring(sym)
         try: self.dm = DocmentText(sym, maxline=maxline, docstring=False)
         except Exception as e:
             warnings.warn(f'docments unavailable for {self.nm}: {type(e).__name__}: {e}')
             self.dm = f'{self.nm}{self.sig or "(...)"}'
+        self.docs = _docstring(sym, self.dm.dm if isinstance(self.dm, DocmentText) else {})
         self.fn = _fullname(sym)
 
     __repr__ = basic_repr()
 
-# %% ../nbs/04_docments.ipynb #e569d885
-def _f_name(o): return f'<function {o.__name__}>' if isinstance(o, FunctionType) else None
-def _fmt_anno(o): return inspect.formatannotation(o).strip("'").replace(' ','')
-
-def _show_param(param):
-    "Like `Parameter.__str__` except removes: quotes in annos, spaces, ids in reprs"
-    kind,res,anno,default = param.kind,param._name,param._annotation,param._default
-    kind = '*' if kind==inspect._VAR_POSITIONAL else '**' if kind==inspect._VAR_KEYWORD else ''
-    res = kind+res
-    if anno is not inspect._empty: res += f':{_f_name(anno) or _fmt_anno(anno)}'
-    if default is not inspect._empty: res += f'={_f_name(default) or repr(default)}'
-    return res
-
 # %% ../nbs/04_docments.ipynb #59797eb7
 def _ital_first(s:str):
     "Surround first line with * for markdown italics, preserving leading spaces"
     return re.sub(r'^(\s*)(.+)', r'\1*\2*', s, count=1)
 
-# %% ../nbs/04_docments.ipynb #9184b175
+# %% ../nbs/04_docments.ipynb #c2aa24dd
 class MarkdownRenderer(ShowDocRenderer):
     "Markdown renderer for `show_doc`"
     def _repr_markdown_(self):

{fastcore-2.2.22 → fastcore-2.2.23}/fastcore/nbio.py

@@ -17,9 +17,9 @@ __all__ = ['langs', 'cell_insert_line', 'cell_str_replace', 'cell_strs_replace',
            'first_code_ln', 'dir_tag', 'nb2dict', 'nb2str', 'write_nb', 'find_id', 'cell_edit', 'view_cell',
            'diff_cells', 'validate_cell', 'validate_nb', 'repair_cell', 'repair_nb', 'preferred_out', 'join_out',
            'mk_stream', 'mk_result', 'mk_display', 'mk_error', 'concat_streams', 'preferred_msg_out', 'render_output',
-           'render_outputs', 'render_text', 'item2xml', 'cell2xml', 'cells2xml', 'Notebook', 'CellRow', 'CellRows',
-           'summary_nb', 'Found', 'FoundCells', 'find_cells', 'deep_merge', 'update_cell', 'fm_default_eval',
-           'does_cell_eval', 'select_cells', 'run_cell', 'msg2out', 'msgs2outs']
+           'render_outputs', 'render_text', 'item2xml', 'cell2xml', 'cells2xml', 'Notebook', 'prev_line', 'CellRow',
+           'CellRows', 'summary_nb', 'Found', 'FoundCells', 'find_cells', 'deep_merge', 'update_cell',
+           'fm_default_eval', 'does_cell_eval', 'select_cells', 'run_cell', 'msg2out', 'msgs2outs']
 
 # %% ../nbs/13_nbio.ipynb #954ca1aa
 from .basics import *
@@ -447,7 +447,7 @@ def validate_cell(cell, idx=None):
     ct = cell.get('cell_type')
     if ct not in ('code','markdown','raw'): raise ValueError(f"{where}: unknown cell_type {ct!r}")
     if not _is_text(cell.get('source', '')): raise ValueError(f"{where}: source must be str or list of str")
-    if not isinstance(cell.get('metadata', {}), dict): raise ValueError(f"{where}: metadata must be a dict")
+    if not isinstance(cell.get('metadata'), dict): raise ValueError(f"{where}: metadata must be a dict")
     if ct=='code':
         if not isinstance(cell.get('outputs'), list): raise ValueError(f"{where}: code cell requires an outputs list")
         if 'execution_count' not in cell: raise ValueError(f"{where}: code cell requires execution_count")
@@ -472,9 +472,9 @@ def repair_cell(cell, idx=None):
     if not _is_text(src):
         cell['source'] = ''.join(map(str, listify(src)))
         res.append(f"{where}: coerced source to text")
-    if not isinstance(cell.get('metadata', {}), dict):
+    if not isinstance(cell.get('metadata'), dict):
         cell['metadata'] = {}
-        res.append(f"{where}: reset non-dict metadata")
+        res.append(f"{where}: set metadata")
     if cell.get('cell_type')=='code':
         if not isinstance(cell.get('outputs'), list):
             cell['outputs'] = []
@@ -759,6 +759,14 @@ def view_cell(self:Notebook, id, nums=True, incl_out=False, trunc_out=True):
 # %% ../nbs/13_nbio.ipynb #4bf3dc2e
 MAXLEN = 180 # Most characters shown per displayed line
 
+# %% ../nbs/13_nbio.ipynb #80541be8
+def prev_line(txt, maxlen=MAXLEN, pre='', sep=''):
+    "One-line preview `pre`+`sep`+`txt` capped at `maxlen`, blank-line runs shown as `¶`; a cut line carries `txt`'s size before `sep` and ends with the count of characters missing"
+    n = len(txt)
+    txt = re.sub(r'\n(?:\s*\n)*', '¶', txt)
+    if len(pre)+len(sep)+len(txt)<=maxlen: return pre+sep+txt
+    return truncstr(f'{pre}[{humanize(n)}]{sep}{txt}', maxlen, suf=lambda n: f'…[{humanize(n)}]')
+
 # %% ../nbs/13_nbio.ipynb #804670bc
 class CellRow:
     "Snapshot of one cell, shown as `id:t[directives]:source` (t: c=code m=markdown r=raw); a context row from a find shows `-` in place of its final `:`"
@@ -766,10 +774,8 @@ class CellRow:
         self.id,self.cell_type,self.source,self.maxlen,self.kind = c.id,c.cell_type,c.source,maxlen,kind
         self.meta = copy.deepcopy(dict(c.get('metadata',{})))
     def __repr__(self):
-        src = re.sub(r'\n(?:\s*\n)*', '¶', self.source)
-        if len(src)>self.maxlen: src = src[:self.maxlen]+'…'
         sep = ':' if self.kind=='match' else '-'
-        return f"{self.id}:{self.cell_type[0]}{dir_tag(self.meta)}{sep}{src}"
+        return prev_line(self.source, self.maxlen, f"{self.id}:{self.cell_type[0]}{dir_tag(self.meta)}", sep)
 
 class CellRows(list):
     def __repr__(self): return '\n'.join(repr(o) for o in self)

{fastcore-2.2.22 → fastcore-2.2.23}/fastcore/xtras.py

@@ -296,7 +296,7 @@ def untar_dir(fname, dest, rename=False, overwrite=False, uid=-1, gid=-1):
         if uid>-1 or gid>-1:
             os.chown(dest, uid, gid)
             if dest.is_dir():
-                for p in dest.rglob('*'): os.chown(p, uid, gid)
+                for p in dest.rglob('*'): os.chown(p, uid, gid, follow_symlinks=False)
         return dest
 
 # %% ../nbs/03_xtras.ipynb #ab91ee87
@@ -978,10 +978,15 @@ def partial_format(s:str, **kwargs):
     return res,list(fmt.missing),fmt.xtra
 
 # %% ../nbs/03_xtras.ipynb #becf7a2d
-def truncstr(s:str, maxlen:int, suf:str='…', space='', sizevar:str=None)->str:
-    "Truncate `s` to length `maxlen`, adding suffix `suf` if truncated"
+def truncstr(s:str, maxlen:int, suf='…', space='', sizevar:str=None)->str:
+    "Truncate `s` to length `maxlen`, adding suffix `suf` if truncated; a callable `suf` gets the number of characters cut"
+    if len(s)+len(space)<=maxlen: return s+space
     if sizevar: suf = suf.format_map({sizevar: len(s)})
-    return s[:maxlen-len(suf)]+suf if len(s)+len(space)>maxlen else s+space
+    if callable(suf):
+        f,n = suf,0
+        for _ in range(3): n = len(s)-maxlen+len(f(n))  # the count's digits change the suffix length: iterate to a fixed point
+        suf = f(n)
+    return s[:maxlen-len(suf)]+suf
 
 # %% ../nbs/03_xtras.ipynb #a67b3fca
 def trunc_ctr(s:str, mx:int=1000)->str:

{fastcore-2.2.22 → fastcore-2.2.23/fastcore.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastcore
-Version: 2.2.22
+Version: 2.2.23
 Summary: Python supercharged for fastai development
 Author-email: Jeremy Howard and Sylvain Gugger <infos@fast.ai>
 License: Apache-2.0
@@ -54,7 +54,7 @@ Here are some tips on using fastcore:
 - **Advanced file operations**: Use the extended `Path` class, which adds methods like `ls()`, `read_json()`, and others to [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path).
 - **Flexible data structures**: Convert between dictionaries and attribute-access objects using [`dict2obj`](https://fastcore.fast.ai/xtras.html#dict2obj) and [`obj2dict`](https://fastcore.fast.ai/xtras.html#obj2dict) for more intuitive data handling.
 - **Functional programming paradigms**: Use tools like [`compose`](https://fastcore.fast.ai/basics.html#compose), [`maps`](https://fastcore.fast.ai/basics.html#maps), and [`filter_ex`](https://fastcore.fast.ai/basics.html#filter_ex) to write more functional-style Python code.
-- **Documentation**: Use [`docments`](https://fastcore.fast.ai/docments.html#docments) where possible to document parameters of functions and methods.
+- **Documentation**: Document parameters and return values with [`docments`](https://fastcore.fast.ai/docments.html#docments), using source comments or `Annotated` metadata for generated APIs. [`MarkdownRenderer`](https://fastcore.fast.ai/docments.html#markdownrenderer) shows the effective signature and retains usage sections such as Notes, Raises, and Examples.
 - **Time-aware caching**: Apply the [`timed_cache`](https://fastcore.fast.ai/xtras.html#timed_cache) decorator to add time-based expiration to the standard `lru_cache` functionality.
 - **Simplified CLI creation**: Use `fastcore.script` to easily transform Python functions into command-line interfaces.