Skip to content

Commit f828638

Browse files
jph00jph00
committed
fixes #736 
1 parent 97fa294 commit f828638

File tree

3 files changed

+344
-90
lines changed

3 files changed

+344
-90
lines changed

‎fastcore/_modidx.py‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -230,7 +230,11 @@
230230
'fastcore.basics.wrap_class': ('basics.html#wrap_class', 'fastcore/basics.py'),
231231
'fastcore.basics.zip_cycle': ('basics.html#zip_cycle', 'fastcore/basics.py')},
232232
'fastcore.dispatch': {},
233-
'fastcore.docments': { 'fastcore.docments.DocmentTbl': ('docments.html#docmenttbl', 'fastcore/docments.py'),
233+
'fastcore.docments': { 'fastcore.docments.DocmentList': ('docments.html#docmentlist', 'fastcore/docments.py'),
234+
'fastcore.docments.DocmentList._fmt': ('docments.html#docmentlist._fmt', 'fastcore/docments.py'),
235+
'fastcore.docments.DocmentList._repr_markdown_': ( 'docments.html#docmentlist._repr_markdown_',
236+
'fastcore/docments.py'),
237+
'fastcore.docments.DocmentTbl': ('docments.html#docmenttbl', 'fastcore/docments.py'),
234238
'fastcore.docments.DocmentTbl.__eq__': ('docments.html#docmenttbl.__eq__', 'fastcore/docments.py'),
235239
'fastcore.docments.DocmentTbl.__init__': ('docments.html#docmenttbl.__init__', 'fastcore/docments.py'),
236240
'fastcore.docments.DocmentTbl._columns': ('docments.html#docmenttbl._columns', 'fastcore/docments.py'),
@@ -248,12 +252,25 @@
248252
'fastcore/docments.py'),
249253
'fastcore.docments.DocmentTbl.return_str': ( 'docments.html#docmenttbl.return_str',
250254
'fastcore/docments.py'),
255+
'fastcore.docments.DocmentsText': ('docments.html#docmentstext', 'fastcore/docments.py'),
256+
'fastcore.docments.DocmentsText.__str__': ('docments.html#docmentstext.__str__', 'fastcore/docments.py'),
257+
'fastcore.docments.DocmentsText._fmt_param': ( 'docments.html#docmentstext._fmt_param',
258+
'fastcore/docments.py'),
259+
'fastcore.docments.DocmentsText._repr_markdown_': ( 'docments.html#docmentstext._repr_markdown_',
260+
'fastcore/docments.py'),
261+
'fastcore.docments.DocmentsText._ret_str': ( 'docments.html#docmentstext._ret_str',
262+
'fastcore/docments.py'),
251263
'fastcore.docments.MarkdownRenderer': ('docments.html#markdownrenderer', 'fastcore/docments.py'),
252264
'fastcore.docments.MarkdownRenderer._repr_markdown_': ( 'docments.html#markdownrenderer._repr_markdown_',
253265
'fastcore/docments.py'),
254266
'fastcore.docments.ShowDocRenderer': ('docments.html#showdocrenderer', 'fastcore/docments.py'),
255267
'fastcore.docments.ShowDocRenderer.__init__': ( 'docments.html#showdocrenderer.__init__',
256268
'fastcore/docments.py'),
269+
'fastcore.docments._DocmentBase': ('docments.html#_docmentbase', 'fastcore/docments.py'),
270+
'fastcore.docments._DocmentBase.__init__': ( 'docments.html#_docmentbase.__init__',
271+
'fastcore/docments.py'),
272+
'fastcore.docments._DocmentBase.has_docment': ( 'docments.html#_docmentbase.has_docment',
273+
'fastcore/docments.py'),
257274
'fastcore.docments._DocstringExtractor': ('docments.html#_docstringextractor', 'fastcore/docments.py'),
258275
'fastcore.docments._DocstringExtractor.__init__': ( 'docments.html#_docstringextractor.__init__',
259276
'fastcore/docments.py'),

‎fastcore/docments.py‎

Lines changed: 56 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@
2121

2222
# %% auto 0
2323
__all__ = ['empty', 'docstring', 'parse_docstring', 'isdataclass', 'get_dataclass_source', 'get_source', 'get_name', 'qual_name',
24-
'docments', 'sig2str', 'sig_source', 'extract_docstrings', 'DocmentTbl', 'ShowDocRenderer',
25-
'MarkdownRenderer']
24+
'docments', 'sig2str', 'sig_source', 'extract_docstrings', 'DocmentTbl', 'DocmentList', 'DocmentsText',
25+
'ShowDocRenderer', 'MarkdownRenderer']
2626

2727
# %% ../nbs/04_docments.ipynb
2828
def docstring(sym):
@@ -277,21 +277,26 @@ def _maybe_nm(o):
277277
def _list2row(l:list): return '| '+' | '.join([_maybe_nm(o) for o in l]) + ' |'
278278

279279
# %% ../nbs/04_docments.ipynb
280-
class DocmentTbl:
281-
# this is the column order we want these items to appear
280+
class _DocmentBase:
281+
def __init__(self, obj):
282+
self.obj,self.dm = obj, docments(obj, full=True)
283+
if 'self' in self.dm: del self.dm['self']
284+
285+
@property
286+
def has_docment(self): return any(v.get('docment') for v in self.dm.values())
287+
288+
# %% ../nbs/04_docments.ipynb
289+
class DocmentTbl(_DocmentBase):
282290
_map = {'anno':'Type', 'default':'Default', 'docment':'Details'}
283291

284292
def __init__(self, obj, verbose=True, returns=True):
285293
"Compute the docment table string"
294+
super().__init__(obj)
286295
self.verbose = verbose
287296
self.returns = False if isdataclass(obj) else returns
288297
try: self.params = L(signature_ex(obj, eval_str=True).parameters.keys())
289298
except (ValueError,TypeError): self.params=[]
290-
try: _dm = docments(obj, full=True, returns=returns)
291-
except: _dm = {}
292-
if 'self' in _dm: del _dm['self']
293-
for d in _dm.values(): d['docment'] = ifnone(d['docment'], inspect._empty)
294-
self.dm = _dm
299+
for d in self.dm.values(): d['docment'] = ifnone(d['docment'], inspect._empty)
295300

296301
@property
297302
def _columns(self):
@@ -306,13 +311,10 @@ def has_docment(self): return 'docment' in self._columns and self._row_list
306311
@property
307312
def has_return(self): return self.returns and bool(_non_empty_keys(self.dm.get('return', {})))
308313

309-
def _row(self, nm, props):
310-
"unpack data for single row to correspond with column names."
311-
return [nm] + [props[c] for c in self._columns]
314+
def _row(self, nm, props): return [nm] + [props[c] for c in self._columns]
312315

313316
@property
314317
def _row_list(self):
315-
"unpack data for all rows."
316318
ordered_params = [(p, self.dm[p]) for p in self.params if p != 'self' and p in self.dm]
317319
return L([self._row(nm, props) for nm,props in ordered_params])
318320

@@ -321,19 +323,14 @@ def _hdr_list(self): return [' '] + [_bold(l) for l in L(self._columns.values()
321323

322324
@property
323325
def hdr_str(self):
324-
"The markdown string for the header portion of the table"
325326
md = _list2row(self._hdr_list)
326327
return md + '\n' + _list2row(['-' * len(l) for l in self._hdr_list])
327328

328329
@property
329-
def params_str(self):
330-
"The markdown string for the parameters portion of the table."
331-
return '\n'.join(self._row_list.map(_list2row))
330+
def params_str(self): return '\n'.join(self._row_list.map(_list2row))
332331

333332
@property
334-
def return_str(self):
335-
"The markdown string for the returns portion of the table."
336-
return _list2row(['**Returns**']+[_bold(_maybe_nm(self.dm['return'][c])) for c in self._columns])
333+
def return_str(self): return _list2row(['**Returns**']+[_bold(_maybe_nm(self.dm['return'][c])) for c in self._columns])
337334

338335
def _repr_markdown_(self):
339336
if not self.has_docment: return ''
@@ -342,10 +339,47 @@ def _repr_markdown_(self):
342339
return '\n'.join(_tbl)
343340

344341
def __eq__(self,other): return self.__str__() == str(other).strip()
345-
346342
__str__ = _repr_markdown_
347343
__repr__ = basic_repr()
348344

345+
# %% ../nbs/04_docments.ipynb
346+
class DocmentList(_DocmentBase):
347+
def _fmt(self, nm, p):
348+
anno,default,doc = _maybe_nm(p.get('anno','')), p.get('default',empty), p.get('docment','')
349+
s = f'`{nm}{":" + anno if anno else ""}{"=" + _maybe_nm(default) if default != empty else ""}`'
350+
br = '\xa0'*3
351+
return f'- {s}' + (f'{br}*{doc}*' if doc else '')
352+
353+
def _repr_markdown_(self): return '\n'.join(self._fmt(k,v) for k,v in self.dm.items())
354+
__repr__=__str__=_repr_markdown_
355+
356+
# %% ../nbs/04_docments.ipynb
357+
class DocmentsText(_DocmentBase):
358+
def _fmt_param(self, nm, p):
359+
anno,default = p.get('anno',empty), p.get('default',empty)
360+
return nm + (f':{_maybe_nm(anno)}' if anno != empty else '') + (f'={repr(default)}' if default != empty else '')
361+
362+
@property
363+
def _ret_str(self):
364+
ret = self.dm.get('return', {})
365+
anno = f"->{_maybe_nm(ret.get('anno',empty))}" if ret.get('anno',empty) != empty else ''
366+
doc = f" # {ret['docment']}" if ret.get('docment') else ''
367+
return f"){anno}:{doc}"
368+
369+
def __str__(self):
370+
params = [(self._fmt_param(k,v), v.get('docment','')) for k,v in self.dm.items() if k != 'return']
371+
lines,curr = [],[]
372+
for fmt,doc in params:
373+
curr.append(fmt)
374+
if doc: lines.append((', '.join(curr), doc)); curr = []
375+
if curr: lines.append((', '.join(curr), ''))
376+
body = [f"{line}{'' if i==len(lines)-1 else ','}{f' # {doc}' if doc else ''}" for i,(line,doc) in enumerate(lines)]
377+
docstr = f' "{self.obj.__doc__}"' if self.obj.__doc__ else ''
378+
return f"def {self.obj.__name__}(\n " + "\n ".join(body) + f"\n{self._ret_str}\n{docstr}"
379+
380+
__repr__ = __str__
381+
def _repr_markdown_(self): return f"```python\n{self}\n```"
382+
349383
# %% ../nbs/04_docments.ipynb
350384
def _docstring(sym):
351385
npdoc = parse_docstring(sym)
@@ -367,7 +401,7 @@ def __init__(self, sym, name:str|None=None, title_level:int=3):
367401
try: self.sig = signature_ex(sym, eval_str=True)
368402
except (ValueError,TypeError): self.sig = None
369403
self.docs = _docstring(sym)
370-
self.dm = DocmentTbl(sym)
404+
self.dm = DocmentList(sym)
371405
self.fn = _fullname(sym)
372406

373407
__repr__ = basic_repr()

0 commit comments

Comments
 (0)