1
2
3
4
5
6
7
8
9 """
10 Parse docstrings and handle any fields it defines, such as C{@type}
11 and C{@author}. Fields are used to describe specific information
12 about an object. There are two classes of fields: X{simple fields}
13 and X{special fields}.
14
15 Simple fields are fields that get stored directly in an C{APIDoc}'s
16 metadata dictionary, without any special processing. The set of
17 simple fields is defined by the list L{STANDARD_FIELDS}, whose
18 elements are L{DocstringField}s.
19
20 Special fields are fields that perform some sort of processing on the
21 C{APIDoc}, or add information to attributes other than the metadata
22 dictionary. Special fields are are handled by field handler
23 functions, which are registered using L{register_field_handler}.
24 """
25 __docformat__ = 'epytext en'
26
27
28
29
30
31
32 import re, sys
33 from epydoc import markup
34 from epydoc.markup import epytext
35 from epydoc.apidoc import *
36 from epydoc.docintrospecter import introspect_docstring_lineno
37 from epydoc.util import py_src_filename
38 from epydoc import log
39 import epydoc.docparser
40 import __builtin__, exceptions
41
42
43
44
45
47 """
48 A simple docstring field, which can be used to describe specific
49 information about an object, such as its author or its version.
50 Simple docstring fields are fields that take no arguments, and
51 are displayed as simple sections.
52
53 @ivar tags: The set of tags that can be used to identify this
54 field.
55 @ivar singular: The label that should be used to identify this
56 field in the output, if the field contains one value.
57 @ivar plural: The label that should be used to identify this
58 field in the output, if the field contains multiple values.
59 @ivar short: If true, then multiple values should be combined
60 into a single comma-delimited list. If false, then
61 multiple values should be listed separately in a bulleted
62 list.
63 @ivar multivalue: If true, then multiple values may be given
64 for this field; if false, then this field can only take a
65 single value, and a warning should be issued if it is
66 redefined.
67 @ivar takes_arg: If true, then this field expects an argument;
68 and a separate field section will be constructed for each
69 argument value. The label (and plural label) should include
70 a '%s' to mark where the argument's string rep should be
71 added.
72 """
73 - def __init__(self, tags, label, plural=None,
74 short=0, multivalue=1, takes_arg=0,
75 varnames=None):
76 if type(tags) in (list, tuple):
77 self.tags = tuple(tags)
78 elif type(tags) is str:
79 self.tags = (tags,)
80 else: raise TypeError('Bad tags: %s' % tags)
81 self.singular = label
82 if plural is None: self.plural = label
83 else: self.plural = plural
84 self.multivalue = multivalue
85 self.short = short
86 self.takes_arg = takes_arg
87 self.varnames = varnames or []
88
90 if not isinstance(other, DocstringField): return -1
91 return cmp(self.tags, other.tags)
92
94 return hash(self.tags)
95
97 return '<Field: %s>' % self.tags[0]
98
99 STANDARD_FIELDS = [
100
101
102
103
104
105
106
107 DocstringField(['deprecated', 'depreciated'],
108 'Deprecated', multivalue=0, varnames=['__deprecated__']),
109
110
111 DocstringField(['version'], 'Version', multivalue=0,
112 varnames=['__version__']),
113 DocstringField(['date'], 'Date', multivalue=0,
114 varnames=['__date__']),
115 DocstringField(['status'], 'Status', multivalue=0),
116
117
118 DocstringField(['author', 'authors'], 'Author', 'Authors', short=1,
119 varnames=['__author__', '__authors__']),
120 DocstringField(['contact'], 'Contact', 'Contacts', short=1,
121 varnames=['__contact__']),
122 DocstringField(['organization', 'org'],
123 'Organization', 'Organizations'),
124 DocstringField(['copyright', '(c)'], 'Copyright', multivalue=0,
125 varnames=['__copyright__']),
126 DocstringField(['license'], 'License', multivalue=0,
127 varnames=['__license__']),
128
129
130 DocstringField(['bug'], 'Bug', 'Bugs'),
131 DocstringField(['warning', 'warn'], 'Warning', 'Warnings'),
132 DocstringField(['attention'], 'Attention'),
133 DocstringField(['note'], 'Note', 'Notes'),
134
135
136 DocstringField(['requires', 'require', 'requirement'], 'Requires'),
137 DocstringField(['precondition', 'precond'],
138 'Precondition', 'Preconditions'),
139 DocstringField(['postcondition', 'postcond'],
140 'Postcondition', 'Postconditions'),
141 DocstringField(['invariant'], 'Invariant'),
142
143
144 DocstringField(['since'], 'Since', multivalue=0),
145
146
147 DocstringField(['change', 'changed'], 'Change Log'),
148
149
150 DocstringField(['see', 'seealso'], 'See Also', short=1),
151
152
153 DocstringField(['todo'], 'To Do', takes_arg=True),
154
155
156 DocstringField(['permission', 'permissions'], 'Permission', 'Permissions')
157 ]
158
159
160
161
162
163 DEFAULT_DOCFORMAT = 'epytext'
164 """The name of the default markup languge used to process docstrings."""
165
166
167
168
169
171 """
172 Process the given C{APIDoc}'s docstring. In particular, populate
173 the C{APIDoc}'s C{descr} and C{summary} attributes, and add any
174 information provided by fields in the docstring.
175
176 @param docindex: A DocIndex, used to find the containing
177 module (to look up the docformat); and to find any
178 user docfields defined by containing objects.
179 @param suppress_warnings: A set of objects for which docstring
180 warnings should be suppressed.
181 """
182 if api_doc.metadata is not UNKNOWN:
183 if not (isinstance(api_doc, RoutineDoc)
184 and api_doc.canonical_name[-1] == '__init__'):
185 log.debug("%s's docstring processed twice" %
186 api_doc.canonical_name)
187 return
188
189 initialize_api_doc(api_doc)
190
191
192
193 if (api_doc.docstring in (None, UNKNOWN)):
194 if isinstance(api_doc, NamespaceDoc):
195 for field in STANDARD_FIELDS + user_docfields(api_doc, docindex):
196 add_metadata_from_var(api_doc, field)
197 return
198
199
200 api_doc.docstring = unindent_docstring(api_doc.docstring)
201
202
203 docformat = get_docformat(api_doc, docindex)
204
205
206 parse_errors = []
207
208
209
210 if isinstance(api_doc, RoutineDoc):
211 parse_function_signature(api_doc, None, docformat, parse_errors)
212
213
214
215 parsed_docstring = markup.parse(api_doc.docstring, docformat,
216 parse_errors)
217
218
219
220 descr, fields = parsed_docstring.split_fields(parse_errors)
221 api_doc.descr = descr
222
223 field_warnings = []
224
225
226
227
228 if isinstance(api_doc, ClassDoc):
229
230
231 initvar = api_doc.variables.get('__init__')
232 if initvar and isinstance(initvar.value, RoutineDoc):
233 init_api_doc = initvar.value
234 parse_docstring(init_api_doc, docindex, suppress_warnings)
235
236 parse_function_signature(init_api_doc, api_doc,
237 docformat, parse_errors)
238 init_fields = split_init_fields(fields, field_warnings)
239
240
241 for field in init_fields:
242 try:
243 process_field(init_api_doc, docindex, field.tag(),
244 field.arg(), field.body())
245 except ValueError, e: field_warnings.append(str(e))
246
247
248 for field in fields:
249 try:
250 process_field(api_doc, docindex, field.tag(),
251 field.arg(), field.body())
252 except ValueError, e: field_warnings.append(str(e))
253
254
255
256 check_type_fields(api_doc, field_warnings)
257
258
259 if isinstance(api_doc, NamespaceDoc):
260 for field in STANDARD_FIELDS + user_docfields(api_doc, docindex):
261 add_metadata_from_var(api_doc, field)
262
263
264 if api_doc.summary is None and api_doc.descr is not None:
265 api_doc.summary, api_doc.other_docs = api_doc.descr.summary()
266
267
268
269 if (isinstance(api_doc, RoutineDoc) and api_doc.summary is None and
270 api_doc.return_descr is not None):
271 s, o = api_doc.return_descr.summary()
272 api_doc.summary = RETURN_PDS + s
273 api_doc.other_docs = o
274
275
276
277
278
279 if api_doc in suppress_warnings:
280 if parse_errors or field_warnings:
281 log.info("Suppressing docstring warnings for %s, since it "
282 "is not included in the documented set." %
283 api_doc.canonical_name)
284 else:
285 report_errors(api_doc, docindex, parse_errors, field_warnings)
286
345
374
376 """
377 Remove the fields related to the constructor from a class docstring
378 fields list.
379
380 @param fields: The fields to process. The list will be modified in place
381 @type fields: C{list} of L{markup.Field}
382 @param warnings: A list to emit processing warnings
383 @type warnings: C{list}
384 @return: The C{fields} items to be applied to the C{__init__} method
385 @rtype: C{list} of L{markup.Field}
386 """
387 init_fields = []
388
389
390 arg_fields = {}
391 args_order = []
392 i = 0
393 while i < len(fields):
394 field = fields[i]
395
396
397 if field.arg() is not None:
398 arg_fields.setdefault(field.arg(), []).append(fields.pop(i))
399 args_order.append(field.arg())
400 else:
401 i += 1
402
403
404
405 for arg in args_order:
406 ff = arg_fields.pop(arg, None)
407 if ff is None:
408 continue
409
410 var = tvar = par = tpar = None
411 for field in ff:
412 if field.tag() in VARIABLE_TAGS:
413 if var is None:
414 var = field
415 fields.append(field)
416 else:
417 warnings.append(
418 "There is more than one variable named '%s'"
419 % arg)
420 elif field.tag() in PARAMETER_TAGS:
421 if par is None:
422 par = field
423 init_fields.append(field)
424 else:
425 warnings.append(
426 "There is more than one parameter named '%s'"
427 % arg)
428
429 elif field.tag() == 'type':
430 if var is None and par is None:
431
432 tvar = tpar = field
433 else:
434 if var is not None and tvar is None:
435 tvar = field
436 if par is not None and tpar is None:
437 tpar = field
438
439 elif field.tag() in EXCEPTION_TAGS:
440 init_fields.append(field)
441
442 else:
443 fields.append(field)
444
445
446 if tvar is not None:
447 if var is not None:
448 fields.append(tvar)
449 else:
450 pass
451
452 if tpar is not None:
453 if par is not None:
454 init_fields.append(tpar)
455 else:
456 pass
457
458 return init_fields
459
460 -def report_errors(api_doc, docindex, parse_errors, field_warnings):
461 """A helper function for L{parse_docstring()} that reports any
462 markup warnings and field warnings that we encountered while
463 processing C{api_doc}'s docstring."""
464 if not parse_errors and not field_warnings: return
465
466
467
468 name = api_doc.canonical_name
469 module = api_doc.defining_module
470 if module is not UNKNOWN and module.filename not in (None, UNKNOWN):
471 try: filename = py_src_filename(module.filename)
472 except: filename = module.filename
473 else:
474 filename = '??'
475
476
477
478
479
480 if isinstance(api_doc, ValueDoc) and api_doc != module:
481 if module not in (None, UNKNOWN) and module.pyval is exceptions:
482 return
483 for builtin_val in __builtin__.__dict__.values():
484 if builtin_val is api_doc.pyval:
485 return
486
487
488 startline = api_doc.docstring_lineno
489 if startline in (None, UNKNOWN):
490 startline = introspect_docstring_lineno(api_doc)
491 if startline in (None, UNKNOWN):
492 startline = None
493
494
495 header = 'File %s, ' % filename
496 if startline is not None:
497 header += 'line %d, ' % startline
498 header += 'in %s' % name
499 log.start_block(header)
500
501
502
503
504 if startline is None:
505
506 dups = {}
507 for error in parse_errors:
508 message = error.descr()
509 if message not in dups:
510 log.docstring_warning(message)
511 dups[message] = 1
512 else:
513
514 messages = {}
515 for error in parse_errors:
516 error.set_linenum_offset(startline)
517 message = error.descr()
518 messages.setdefault(message, []).append(error.linenum())
519 message_items = messages.items()
520 message_items.sort(lambda a,b:cmp(min(a[1]), min(b[1])))
521 for message, linenums in message_items:
522 linenums = [n for n in linenums if n is not None]
523 if len(linenums) == 0:
524 log.docstring_warning(message)
525 elif len(linenums) == 1:
526 log.docstring_warning("Line %s: %s" % (linenums[0], message))
527 else:
528 linenums = ', '.join(['%s' % l for l in linenums])
529 log.docstring_warning("Lines %s: %s" % (linenums, message))
530
531
532 for warning in field_warnings:
533 log.docstring_warning(warning)
534
535
536 log.end_block()
537
538 RETURN_PDS = markup.parse('Returns:', markup='epytext')
539 """A ParsedDocstring containing the text 'Returns'. This is used to
540 construct summary descriptions for routines that have empty C{descr},
541 but non-empty C{return_descr}."""
542 RETURN_PDS._tree.children[0].attribs['inline'] = True
543
544
545
546
547
548 UNEXPECTED_ARG = '%r did not expect an argument'
549 EXPECTED_ARG = '%r expected an argument'
550 EXPECTED_SINGLE_ARG = '%r expected a single argument'
551 BAD_CONTEXT = 'Invalid context for %r'
552 REDEFINED = 'Redefinition of %s'
553 UNKNOWN_TAG = 'Unknown field tag %r'
554 BAD_PARAM = '@%s for unknown parameter %s'
555
556
557
558
559
561 """
562 Process a single field, and use it to update C{api_doc}. If
563 C{tag} is the name of a special field, then call its handler
564 function. If C{tag} is the name of a simple field, then use
565 C{process_simple_field} to process it. Otherwise, check if it's a
566 user-defined field, defined in this docstring or the docstring of
567 a containing object; and if so, process it with
568 C{process_simple_field}.
569
570 @param tag: The field's tag, such as C{'author'}
571 @param arg: The field's optional argument
572 @param descr: The description following the field tag and
573 argument.
574 @raise ValueError: If a problem was encountered while processing
575 the field. The C{ValueError}'s string argument is an
576 explanation of the problem, which should be displayed as a
577 warning message.
578 """
579
580 if tag in _field_dispatch_table:
581 handler = _field_dispatch_table[tag]
582 handler(api_doc, docindex, tag, arg, descr)
583 return
584
585
586 for field in STANDARD_FIELDS + user_docfields(api_doc, docindex):
587 if tag in field.tags:
588
589 if not field.takes_arg:
590 _check(api_doc, tag, arg, expect_arg=False)
591 api_doc.metadata.append((field, arg, descr))
592 return
593
594
595 raise ValueError(UNKNOWN_TAG % tag)
596
598 """
599 Return a list of user defined fields that can be used for the
600 given object. This list is taken from the given C{api_doc}, and
601 any of its containing C{NamepaceDoc}s.
602
603 @note: We assume here that a parent's docstring will always be
604 parsed before its childrens'. This is indeed the case when we
605 are called via L{docbuilder.build_doc_index()}. If a child's
606 docstring is parsed before its parents, then its parent won't
607 yet have had its C{extra_docstring_fields} attribute
608 initialized.
609 """
610 docfields = []
611
612 if api_doc.extra_docstring_fields not in (None, UNKNOWN):
613 docfields += api_doc.extra_docstring_fields
614
615 for i in range(len(api_doc.canonical_name)-1, 0, -1):
616 ancestor = docindex.get_valdoc(api_doc.canonical_name[:i])
617 if ancestor is not None \
618 and ancestor.extra_docstring_fields not in (None, UNKNOWN):
619 docfields += ancestor.extra_docstring_fields
620 return docfields
621
622 _field_dispatch_table = {}
624 """
625 Register the given field handler function for processing any
626 of the given field tags. Field handler functions should
627 have the following signature:
628
629 >>> def field_handler(api_doc, docindex, tag, arg, descr):
630 ... '''update api_doc in response to the field.'''
631
632 Where C{api_doc} is the documentation object to update;
633 C{docindex} is a L{DocIndex} that can be used to look up the
634 documentation for related objects; C{tag} is the field tag that
635 was used; C{arg} is the optional argument; and C{descr} is the
636 description following the field tag and argument.
637 """
638 for field_tag in field_tags:
639 _field_dispatch_table[field_tag] = handler
640
641
642
643
644
651
653 """Copy the docstring contents from the object named in C{descr}"""
654 _check(api_doc, tag, arg, expect_arg=False)
655
656
657
658
659
660
661
662
663 raise ValueError('%s not implemented yet' % tag)
664
690
696
697
709
717
721
722
724
725 if isinstance(api_doc, NamespaceDoc):
726 _check(api_doc, tag, arg, expect_arg='single')
727 set_var_type(api_doc, arg, descr)
728
729
730 elif isinstance(api_doc, (VariableDoc, PropertyDoc)):
731 _check(api_doc, tag, arg, expect_arg=False)
732 if api_doc.type_descr is not None:
733 raise ValueError(REDEFINED % tag)
734 api_doc.type_descr = descr
735
736
737 elif isinstance(api_doc, RoutineDoc):
738 _check(api_doc, tag, arg, expect_arg='single')
739 if arg in api_doc.arg_types:
740 raise ValueError(REDEFINED % ('type for '+arg))
741 api_doc.arg_types[arg] = descr
742
743 else:
744 raise ValueError(BAD_CONTEXT % tag)
745
750
752
753
754 if (isinstance(api_doc, VariableDoc) and
755 isinstance(api_doc.container, ClassDoc)):
756 _check(api_doc, tag, arg, expect_arg=False)
757 api_doc.is_instvar = False
758 api_doc.descr = markup.ConcatenatedDocstring(api_doc.descr, descr)
759 api_doc.summary, api_doc.other_docs = descr.summary()
760
761
762 else:
763 _check(api_doc, tag, arg, context=ClassDoc, expect_arg=True)
764 for ident in re.split('[:;, ] *', arg):
765 set_var_descr(api_doc, ident, descr)
766 api_doc.variables[ident].is_instvar = False
767
769
770
771 if (isinstance(api_doc, VariableDoc) and
772 isinstance(api_doc.container, ClassDoc)):
773 _check(api_doc, tag, arg, expect_arg=False)
774
775 api_doc.is_instvar = True
776 api_doc.descr = markup.ConcatenatedDocstring(api_doc.descr, descr)
777 api_doc.summary, api_doc.other_docs = descr.summary()
778
779
780 else:
781 _check(api_doc, tag, arg, context=ClassDoc, expect_arg=True)
782 for ident in re.split('[:;, ] *', arg):
783 set_var_descr(api_doc, ident, descr)
784 api_doc.variables[ident].is_instvar = True
785
786
787
793
795 _check(api_doc, tag, arg,
796 context=(RoutineDoc, PropertyDoc), expect_arg=False)
797 if isinstance(api_doc, RoutineDoc):
798 if api_doc.return_type is not None:
799 raise ValueError(REDEFINED % 'return value type')
800 api_doc.return_type = descr
801
802 elif isinstance(api_doc, PropertyDoc):
803 _check(api_doc, tag, arg, expect_arg=False)
804 if api_doc.type_descr is not None:
805 raise ValueError(REDEFINED % tag)
806 api_doc.type_descr = descr
807
809 _check(api_doc, tag, arg, context=RoutineDoc, expect_arg=True)
810 idents = re.split('[:;, ] *', arg)
811 api_doc.arg_descrs.append( (idents, descr) )
812
813
814 all_args = api_doc.all_args()
815 if all_args not in (['...'], UNKNOWN):
816 bad_params = ['"%s"' % i for i in idents if i not in all_args]
817 if bad_params:
818 raise ValueError(BAD_PARAM % (tag, ', '.join(bad_params)))
819
826
827 register_field_handler(process_group_field, 'group')
828 register_field_handler(process_deffield_field, 'deffield', 'newfield')
829 register_field_handler(process_sort_field, 'sort')
830 register_field_handler(process_summary_field, 'summary')
831 register_field_handler(process_undocumented_field, 'undocumented')
832 register_field_handler(process_include_field, 'include')
833 register_field_handler(process_var_field, 'var', 'variable')
834 register_field_handler(process_type_field, 'type')
835 register_field_handler(process_cvar_field, 'cvar', 'cvariable')
836 register_field_handler(process_ivar_field, 'ivar', 'ivariable')
837 register_field_handler(process_return_field, 'return', 'returns')
838 register_field_handler(process_rtype_field, 'rtype', 'returntype')
839 register_field_handler(process_arg_field, 'arg', 'argument',
840 'parameter', 'param')
841 register_field_handler(process_kwarg_field, 'kwarg', 'keyword', 'kwparam')
842 register_field_handler(process_raise_field, 'raise', 'raises',
843 'except', 'exception')
844
845
846 PARAMETER_TAGS = ('arg', 'argument', 'parameter', 'param',
847 'kwarg', 'keyword', 'kwparam')
848
849
850 VARIABLE_TAGS = ('cvar', 'cvariable', 'ivar', 'ivariable')
851
852
853 EXCEPTION_TAGS = ('raise', 'raises', 'except', 'exception')
854
855
856
857
858
860 """Check to make sure that all type fields correspond to some
861 documented parameter; if not, append a warning to field_warnings."""
862 if isinstance(api_doc, RoutineDoc):
863 for arg in api_doc.arg_types:
864 if arg not in api_doc.all_args():
865 for args, descr in api_doc.arg_descrs:
866 if arg in args:
867 break
868 else:
869 field_warnings.append(BAD_PARAM % ('type', '"%s"' % arg))
870
883
894
895 -def _check(api_doc, tag, arg, context=None, expect_arg=None):
896 if context is not None:
897 if not isinstance(api_doc, context):
898 raise ValueError(BAD_CONTEXT % tag)
899 if expect_arg is not None:
900 if expect_arg == True:
901 if arg is None:
902 raise ValueError(EXPECTED_ARG % tag)
903 elif expect_arg == False:
904 if arg is not None:
905 raise ValueError(UNEXPECTED_ARG % tag)
906 elif expect_arg == 'single':
907 if (arg is None or ' ' in arg):
908 raise ValueError(EXPECTED_SINGLE_ARG % tag)
909 else:
910 assert 0, 'bad value for expect_arg'
911
927
929
930
931
932 if not docstring: return ''
933 lines = docstring.expandtabs().split('\n')
934
935
936 margin = sys.maxint
937 for line in lines[1:]:
938 content = len(line.lstrip())
939 if content:
940 indent = len(line) - content
941 margin = min(margin, indent)
942
943 if lines:
944 lines[0] = lines[0].lstrip()
945 if margin < sys.maxint:
946 for i in range(1, len(lines)): lines[i] = lines[i][margin:]
947
948 while lines and not lines[-1]:
949 lines.pop()
950
951
952 return '\n'.join(lines)
953
954 _IDENTIFIER_LIST_REGEXP = re.compile(r'^[\w.\*]+([\s,:;]\s*[\w.\*]+)*$')
956 """
957 Given a C{ParsedDocstring} that contains a list of identifiers,
958 return a list of those identifiers. This is used by fields such
959 as C{@group} and C{@sort}, which expect lists of identifiers as
960 their values. To extract the identifiers, the docstring is first
961 converted to plaintext, and then split. The plaintext content of
962 the docstring must be a a list of identifiers, separated by
963 spaces, commas, colons, or semicolons.
964
965 @rtype: C{list} of C{string}
966 @return: A list of the identifier names contained in C{descr}.
967 @type descr: L{markup.ParsedDocstring}
968 @param descr: A C{ParsedDocstring} containing a list of
969 identifiers.
970 @raise ValueError: If C{descr} does not contain a valid list of
971 identifiers.
972 """
973 idents = descr.to_plaintext(None).strip()
974 idents = re.sub(r'\s+', ' ', idents)
975 if not _IDENTIFIER_LIST_REGEXP.match(idents):
976 raise ValueError, 'Bad Identifier list: %r' % idents
977 rval = re.split('[:;, ] *', idents)
978 return rval
979
981 tags = [s.lower() for s in re.split('[:;, ] *', arg)]
982 descr = descr.to_plaintext(None).strip()
983 args = re.split('[:;,] *', descr)
984 if len(args) == 0 or len(args) > 3:
985 raise ValueError, 'Wrong number of arguments'
986 singular = args[0]
987 if len(args) >= 2: plural = args[1]
988 else: plural = None
989 short = 0
990 if len(args) >= 3:
991 if args[2] == 'short': short = 1
992 else: raise ValueError('Bad arg 2 (expected "short")')
993 return DocstringField(tags, singular, plural, short)
994
995
996
997
998
999
1000 _SIGNATURE_RE = re.compile(
1001
1002 r'^\s*((?P<self>\w+)\.)?' +
1003
1004 r'(?P<func>\w+)' +
1005
1006 r'\((?P<params>(\s*\[?\s*\*{0,2}[\w\-\.]+(\s*=.+?)?'+
1007 r'(\s*\[?\s*,\s*\]?\s*\*{0,2}[\w\-\.]+(\s*=.+?)?)*\]*)?)\s*\)' +
1008
1009 r'(\s*(->)\s*(?P<return>\S.*?))?'+
1010
1011 r'\s*(\n|\s+(--|<=+>)\s+|$|\.\s+|\.\n)')
1012 """A regular expression that is used to extract signatures from
1013 docstrings."""
1014
1016 """
1017 Construct the signature for a builtin function or method from
1018 its docstring. If the docstring uses the standard convention
1019 of including a signature in the first line of the docstring
1020 (and formats that signature according to standard
1021 conventions), then it will be used to extract a signature.
1022 Otherwise, the signature will be set to a single varargs
1023 variable named C{"..."}.
1024
1025 @param func_doc: The target object where to store parsed signature. Also
1026 container of the docstring to parse if doc_source is C{None}
1027 @type func_doc: L{RoutineDoc}
1028 @param doc_source: Contains the docstring to parse. If C{None}, parse
1029 L{func_doc} docstring instead
1030 @type doc_source: L{APIDoc}
1031 @rtype: C{None}
1032 """
1033 if doc_source is None:
1034 doc_source = func_doc
1035
1036
1037 if not doc_source.docstring: return False
1038
1039 m = _SIGNATURE_RE.match(doc_source.docstring)
1040 if m is None: return False
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052 params = m.group('params')
1053 rtype = m.group('return')
1054 selfparam = m.group('self')
1055
1056
1057 func_doc.posargs = []
1058 func_doc.vararg = None
1059 func_doc.kwarg = None
1060 if func_doc.posarg_defaults is UNKNOWN:
1061 func_doc.posarg_defaults = []
1062 if params:
1063
1064 while '[' in params or ']' in params:
1065 m2 = re.match(r'(.*)\[([^\[\]]+)\](.*)', params)
1066 if not m2: return False
1067 (start, mid, end) = m2.groups()
1068 mid = re.sub(r'((,|^)\s*[\w\-\.]+)', r'\1=...', mid)
1069 params = start+mid+end
1070
1071 params = re.sub(r'=...=' , r'=', params)
1072 for name in params.split(','):
1073 if '=' in name:
1074 (name, default_repr) = name.split('=',1)
1075 default = GenericValueDoc(parse_repr=default_repr)
1076 else:
1077 default = None
1078 name = name.strip()
1079 if name == '...':
1080 func_doc.vararg = '...'
1081 elif name.startswith('**'):
1082 func_doc.kwarg = name[2:]
1083 elif name.startswith('*'):
1084 func_doc.vararg = name[1:]
1085 else:
1086 func_doc.posargs.append(name)
1087 if len(func_doc.posarg_defaults) < len(func_doc.posargs):
1088 func_doc.posarg_defaults.append(default)
1089 elif default is not None:
1090 argnum = len(func_doc.posargs)-1
1091 func_doc.posarg_defaults[argnum] = default
1092
1093
1094 if rtype:
1095 func_doc.return_type = markup.parse(rtype, docformat, parse_errors,
1096 inline=True)
1097
1098
1099 if selfparam:
1100 func_doc.posargs.insert(0, selfparam)
1101 func_doc.posarg_defaults.insert(0, None)
1102
1103
1104 doc_source.docstring = doc_source.docstring[m.end():]
1105
1106
1107 return True
1108