Python code coverage for Tools/clinic/clinic.py

#	count	content
1	n/a	#!/usr/bin/env python3
2	n/a	#
3	n/a	# Argument Clinic
4	n/a	# Copyright 2012-2013 by Larry Hastings.
5	n/a	# Licensed to the PSF under a contributor agreement.
6	n/a	#
7	n/a
8	n/a	import abc
9	n/a	import ast
10	n/a	import atexit
11	n/a	import collections
12	n/a	import contextlib
13	n/a	import copy
14	n/a	import cpp
15	n/a	import functools
16	n/a	import hashlib
17	n/a	import inspect
18	n/a	import io
19	n/a	import itertools
20	n/a	import os
21	n/a	import pprint
22	n/a	import re
23	n/a	import shlex
24	n/a	import string
25	n/a	import sys
26	n/a	import tempfile
27	n/a	import textwrap
28	n/a	import traceback
29	n/a	import types
30	n/a	import uuid
31	n/a
32	n/a	from types import *
33	n/a	NoneType = type(None)
34	n/a
35	n/a	# TODO:
36	n/a	#
37	n/a	# soon:
38	n/a	#
39	n/a	# * allow mixing any two of {positional-only, positional-or-keyword,
40	n/a	# keyword-only}
41	n/a	# * dict constructor uses positional-only and keyword-only
42	n/a	# * max and min use positional only with an optional group
43	n/a	# and keyword-only
44	n/a	#
45	n/a
46	n/a	version = '1'
47	n/a
48	n/a	_empty = inspect._empty
49	n/a	_void = inspect._void
50	n/a
51	n/a	NoneType = type(None)
52	n/a
53	n/a	class Unspecified:
54	n/a	def __repr__(self):
55	n/a	return '<Unspecified>'
56	n/a
57	n/a	unspecified = Unspecified()
58	n/a
59	n/a
60	n/a	class Null:
61	n/a	def __repr__(self):
62	n/a	return '<Null>'
63	n/a
64	n/a	NULL = Null()
65	n/a
66	n/a
67	n/a	class Unknown:
68	n/a	def __repr__(self):
69	n/a	return '<Unknown>'
70	n/a
71	n/a	unknown = Unknown()
72	n/a
73	n/a	sig_end_marker = '--'
74	n/a
75	n/a
76	n/a	_text_accumulator_nt = collections.namedtuple("_text_accumulator", "text append output")
77	n/a
78	n/a	def _text_accumulator():
79	n/a	text = []
80	n/a	def output():
81	n/a	s = ''.join(text)
82	n/a	text.clear()
83	n/a	return s
84	n/a	return _text_accumulator_nt(text, text.append, output)
85	n/a
86	n/a
87	n/a	text_accumulator_nt = collections.namedtuple("text_accumulator", "text append")
88	n/a
89	n/a	def text_accumulator():
90	n/a	"""
91	n/a	Creates a simple text accumulator / joiner.
92	n/a
93	n/a	Returns a pair of callables:
94	n/a	append, output
95	n/a	"append" appends a string to the accumulator.
96	n/a	"output" returns the contents of the accumulator
97	n/a	joined together (''.join(accumulator)) and
98	n/a	empties the accumulator.
99	n/a	"""
100	n/a	text, append, output = _text_accumulator()
101	n/a	return text_accumulator_nt(append, output)
102	n/a
103	n/a
104	n/a	def warn_or_fail(fail=False, *args, filename=None, line_number=None):
105	n/a	joined = " ".join([str(a) for a in args])
106	n/a	add, output = text_accumulator()
107	n/a	if fail:
108	n/a	add("Error")
109	n/a	else:
110	n/a	add("Warning")
111	n/a	if clinic:
112	n/a	if filename is None:
113	n/a	filename = clinic.filename
114	n/a	if getattr(clinic, 'block_parser', None) and (line_number is None):
115	n/a	line_number = clinic.block_parser.line_number
116	n/a	if filename is not None:
117	n/a	add(' in file "' + filename + '"')
118	n/a	if line_number is not None:
119	n/a	add(" on line " + str(line_number))
120	n/a	add(':\n')
121	n/a	add(joined)
122	n/a	print(output())
123	n/a	if fail:
124	n/a	sys.exit(-1)
125	n/a
126	n/a
127	n/a	def warn(*args, filename=None, line_number=None):
128	n/a	return warn_or_fail(False, *args, filename=filename, line_number=line_number)
129	n/a
130	n/a	def fail(*args, filename=None, line_number=None):
131	n/a	return warn_or_fail(True, *args, filename=filename, line_number=line_number)
132	n/a
133	n/a
134	n/a	def quoted_for_c_string(s):
135	n/a	for old, new in (
136	n/a	('\\', '\\\\'), # must be first!
137	n/a	('"', '\\"'),
138	n/a	("'", "\\'"),
139	n/a	):
140	n/a	s = s.replace(old, new)
141	n/a	return s
142	n/a
143	n/a	def c_repr(s):
144	n/a	return '"' + s + '"'
145	n/a
146	n/a
147	n/a	is_legal_c_identifier = re.compile('^[A-Za-z_][A-Za-z0-9_]*$').match
148	n/a
149	n/a	def is_legal_py_identifier(s):
150	n/a	return all(is_legal_c_identifier(field) for field in s.split('.'))
151	n/a
152	n/a	# identifiers that are okay in Python but aren't a good idea in C.
153	n/a	# so if they're used Argument Clinic will add "_value" to the end
154	n/a	# of the name in C.
155	n/a	c_keywords = set("""
156	n/a	asm auto break case char const continue default do double
157	n/a	else enum extern float for goto if inline int long
158	n/a	register return short signed sizeof static struct switch
159	n/a	typedef typeof union unsigned void volatile while
160	n/a	""".strip().split())
161	n/a
162	n/a	def ensure_legal_c_identifier(s):
163	n/a	# for now, just complain if what we're given isn't legal
164	n/a	if not is_legal_c_identifier(s):
165	n/a	fail("Illegal C identifier: {}".format(s))
166	n/a	# but if we picked a C keyword, pick something else
167	n/a	if s in c_keywords:
168	n/a	return s + "_value"
169	n/a	return s
170	n/a
171	n/a	def rstrip_lines(s):
172	n/a	text, add, output = _text_accumulator()
173	n/a	for line in s.split('\n'):
174	n/a	add(line.rstrip())
175	n/a	add('\n')
176	n/a	text.pop()
177	n/a	return output()
178	n/a
179	n/a	def format_escape(s):
180	n/a	# double up curly-braces, this string will be used
181	n/a	# as part of a format_map() template later
182	n/a	s = s.replace('{', '{{')
183	n/a	s = s.replace('}', '}}')
184	n/a	return s
185	n/a
186	n/a	def linear_format(s, **kwargs):
187	n/a	"""
188	n/a	Perform str.format-like substitution, except:
189	n/a	* The strings substituted must be on lines by
190	n/a	themselves. (This line is the "source line".)
191	n/a	* If the substitution text is empty, the source line
192	n/a	is removed in the output.
193	n/a	* If the field is not recognized, the original line
194	n/a	is passed unmodified through to the output.
195	n/a	* If the substitution text is not empty:
196	n/a	* Each line of the substituted text is indented
197	n/a	by the indent of the source line.
198	n/a	* A newline will be added to the end.
199	n/a	"""
200	n/a
201	n/a	add, output = text_accumulator()
202	n/a	for line in s.split('\n'):
203	n/a	indent, curly, trailing = line.partition('{')
204	n/a	if not curly:
205	n/a	add(line)
206	n/a	add('\n')
207	n/a	continue
208	n/a
209	n/a	name, curly, trailing = trailing.partition('}')
210	n/a	if not curly or name not in kwargs:
211	n/a	add(line)
212	n/a	add('\n')
213	n/a	continue
214	n/a
215	n/a	if trailing:
216	n/a	fail("Text found after {" + name + "} block marker! It must be on a line by itself.")
217	n/a	if indent.strip():
218	n/a	fail("Non-whitespace characters found before {" + name + "} block marker! It must be on a line by itself.")
219	n/a
220	n/a	value = kwargs[name]
221	n/a	if not value:
222	n/a	continue
223	n/a
224	n/a	value = textwrap.indent(rstrip_lines(value), indent)
225	n/a	add(value)
226	n/a	add('\n')
227	n/a
228	n/a	return output()[:-1]
229	n/a
230	n/a	def indent_all_lines(s, prefix):
231	n/a	"""
232	n/a	Returns 's', with 'prefix' prepended to all lines.
233	n/a
234	n/a	If the last line is empty, prefix is not prepended
235	n/a	to it. (If s is blank, returns s unchanged.)
236	n/a
237	n/a	(textwrap.indent only adds to non-blank lines.)
238	n/a	"""
239	n/a	split = s.split('\n')
240	n/a	last = split.pop()
241	n/a	final = []
242	n/a	for line in split:
243	n/a	final.append(prefix)
244	n/a	final.append(line)
245	n/a	final.append('\n')
246	n/a	if last:
247	n/a	final.append(prefix)
248	n/a	final.append(last)
249	n/a	return ''.join(final)
250	n/a
251	n/a	def suffix_all_lines(s, suffix):
252	n/a	"""
253	n/a	Returns 's', with 'suffix' appended to all lines.
254	n/a
255	n/a	If the last line is empty, suffix is not appended
256	n/a	to it. (If s is blank, returns s unchanged.)
257	n/a	"""
258	n/a	split = s.split('\n')
259	n/a	last = split.pop()
260	n/a	final = []
261	n/a	for line in split:
262	n/a	final.append(line)
263	n/a	final.append(suffix)
264	n/a	final.append('\n')
265	n/a	if last:
266	n/a	final.append(last)
267	n/a	final.append(suffix)
268	n/a	return ''.join(final)
269	n/a
270	n/a
271	n/a	def version_splitter(s):
272	n/a	"""Splits a version string into a tuple of integers.
273	n/a
274	n/a	The following ASCII characters are allowed, and employ
275	n/a	the following conversions:
276	n/a	a -> -3
277	n/a	b -> -2
278	n/a	c -> -1
279	n/a	(This permits Python-style version strings such as "1.4b3".)
280	n/a	"""
281	n/a	version = []
282	n/a	accumulator = []
283	n/a	def flush():
284	n/a	if not accumulator:
285	n/a	raise ValueError('Unsupported version string: ' + repr(s))
286	n/a	version.append(int(''.join(accumulator)))
287	n/a	accumulator.clear()
288	n/a
289	n/a	for c in s:
290	n/a	if c.isdigit():
291	n/a	accumulator.append(c)
292	n/a	elif c == '.':
293	n/a	flush()
294	n/a	elif c in 'abc':
295	n/a	flush()
296	n/a	version.append('abc'.index(c) - 3)
297	n/a	else:
298	n/a	raise ValueError('Illegal character ' + repr(c) + ' in version string ' + repr(s))
299	n/a	flush()
300	n/a	return tuple(version)
301	n/a
302	n/a	def version_comparitor(version1, version2):
303	n/a	iterator = itertools.zip_longest(version_splitter(version1), version_splitter(version2), fillvalue=0)
304	n/a	for i, (a, b) in enumerate(iterator):
305	n/a	if a < b:
306	n/a	return -1
307	n/a	if a > b:
308	n/a	return 1
309	n/a	return 0
310	n/a
311	n/a
312	n/a	class CRenderData:
313	n/a	def __init__(self):
314	n/a
315	n/a	# The C statements to declare variables.
316	n/a	# Should be full lines with \n eol characters.
317	n/a	self.declarations = []
318	n/a
319	n/a	# The C statements required to initialize the variables before the parse call.
320	n/a	# Should be full lines with \n eol characters.
321	n/a	self.initializers = []
322	n/a
323	n/a	# The C statements needed to dynamically modify the values
324	n/a	# parsed by the parse call, before calling the impl.
325	n/a	self.modifications = []
326	n/a
327	n/a	# The entries for the "keywords" array for PyArg_ParseTuple.
328	n/a	# Should be individual strings representing the names.
329	n/a	self.keywords = []
330	n/a
331	n/a	# The "format units" for PyArg_ParseTuple.
332	n/a	# Should be individual strings that will get
333	n/a	self.format_units = []
334	n/a
335	n/a	# The varargs arguments for PyArg_ParseTuple.
336	n/a	self.parse_arguments = []
337	n/a
338	n/a	# The parameter declarations for the impl function.
339	n/a	self.impl_parameters = []
340	n/a
341	n/a	# The arguments to the impl function at the time it's called.
342	n/a	self.impl_arguments = []
343	n/a
344	n/a	# For return converters: the name of the variable that
345	n/a	# should receive the value returned by the impl.
346	n/a	self.return_value = "return_value"
347	n/a
348	n/a	# For return converters: the code to convert the return
349	n/a	# value from the parse function. This is also where
350	n/a	# you should check the _return_value for errors, and
351	n/a	# "goto exit" if there are any.
352	n/a	self.return_conversion = []
353	n/a
354	n/a	# The C statements required to clean up after the impl call.
355	n/a	self.cleanup = []
356	n/a
357	n/a
358	n/a	class FormatCounterFormatter(string.Formatter):
359	n/a	"""
360	n/a	This counts how many instances of each formatter
361	n/a	"replacement string" appear in the format string.
362	n/a
363	n/a	e.g. after evaluating "string {a}, {b}, {c}, {a}"
364	n/a	the counts dict would now look like
365	n/a	{'a': 2, 'b': 1, 'c': 1}
366	n/a	"""
367	n/a	def __init__(self):
368	n/a	self.counts = collections.Counter()
369	n/a
370	n/a	def get_value(self, key, args, kwargs):
371	n/a	self.counts[key] += 1
372	n/a	return ''
373	n/a
374	n/a	class Language(metaclass=abc.ABCMeta):
375	n/a
376	n/a	start_line = ""
377	n/a	body_prefix = ""
378	n/a	stop_line = ""
379	n/a	checksum_line = ""
380	n/a
381	n/a	def __init__(self, filename):
382	n/a	pass
383	n/a
384	n/a	@abc.abstractmethod
385	n/a	def render(self, clinic, signatures):
386	n/a	pass
387	n/a
388	n/a	def parse_line(self, line):
389	n/a	pass
390	n/a
391	n/a	def validate(self):
392	n/a	def assert_only_one(attr, *additional_fields):
393	n/a	"""
394	n/a	Ensures that the string found at getattr(self, attr)
395	n/a	contains exactly one formatter replacement string for
396	n/a	each valid field. The list of valid fields is
397	n/a	['dsl_name'] extended by additional_fields.
398	n/a
399	n/a	e.g.
400	n/a	self.fmt = "{dsl_name} {a} {b}"
401	n/a
402	n/a	# this passes
403	n/a	self.assert_only_one('fmt', 'a', 'b')
404	n/a
405	n/a	# this fails, the format string has a {b} in it
406	n/a	self.assert_only_one('fmt', 'a')
407	n/a
408	n/a	# this fails, the format string doesn't have a {c} in it
409	n/a	self.assert_only_one('fmt', 'a', 'b', 'c')
410	n/a
411	n/a	# this fails, the format string has two {a}s in it,
412	n/a	# it must contain exactly one
413	n/a	self.fmt2 = '{dsl_name} {a} {a}'
414	n/a	self.assert_only_one('fmt2', 'a')
415	n/a
416	n/a	"""
417	n/a	fields = ['dsl_name']
418	n/a	fields.extend(additional_fields)
419	n/a	line = getattr(self, attr)
420	n/a	fcf = FormatCounterFormatter()
421	n/a	fcf.format(line)
422	n/a	def local_fail(should_be_there_but_isnt):
423	n/a	if should_be_there_but_isnt:
424	n/a	fail("{} {} must contain {{{}}} exactly once!".format(
425	n/a	self.__class__.__name__, attr, name))
426	n/a	else:
427	n/a	fail("{} {} must not contain {{{}}}!".format(
428	n/a	self.__class__.__name__, attr, name))
429	n/a
430	n/a	for name, count in fcf.counts.items():
431	n/a	if name in fields:
432	n/a	if count > 1:
433	n/a	local_fail(True)
434	n/a	else:
435	n/a	local_fail(False)
436	n/a	for name in fields:
437	n/a	if fcf.counts.get(name) != 1:
438	n/a	local_fail(True)
439	n/a
440	n/a	assert_only_one('start_line')
441	n/a	assert_only_one('stop_line')
442	n/a
443	n/a	field = "arguments" if "{arguments}" in self.checksum_line else "checksum"
444	n/a	assert_only_one('checksum_line', field)
445	n/a
446	n/a
447	n/a
448	n/a	class PythonLanguage(Language):
449	n/a
450	n/a	language = 'Python'
451	n/a	start_line = "#/*[{dsl_name} input]"
452	n/a	body_prefix = "#"
453	n/a	stop_line = "#[{dsl_name} start generated code]*/"
454	n/a	checksum_line = "#/[{dsl_name} end generated code: {arguments}]/"
455	n/a
456	n/a
457	n/a	def permute_left_option_groups(l):
458	n/a	"""
459	n/a	Given [1, 2, 3], should yield:
460	n/a	()
461	n/a	(3,)
462	n/a	(2, 3)
463	n/a	(1, 2, 3)
464	n/a	"""
465	n/a	yield tuple()
466	n/a	accumulator = []
467	n/a	for group in reversed(l):
468	n/a	accumulator = list(group) + accumulator
469	n/a	yield tuple(accumulator)
470	n/a
471	n/a
472	n/a	def permute_right_option_groups(l):
473	n/a	"""
474	n/a	Given [1, 2, 3], should yield:
475	n/a	()
476	n/a	(1,)
477	n/a	(1, 2)
478	n/a	(1, 2, 3)
479	n/a	"""
480	n/a	yield tuple()
481	n/a	accumulator = []
482	n/a	for group in l:
483	n/a	accumulator.extend(group)
484	n/a	yield tuple(accumulator)
485	n/a
486	n/a
487	n/a	def permute_optional_groups(left, required, right):
488	n/a	"""
489	n/a	Generator function that computes the set of acceptable
490	n/a	argument lists for the provided iterables of
491	n/a	argument groups. (Actually it generates a tuple of tuples.)
492	n/a
493	n/a	Algorithm: prefer left options over right options.
494	n/a
495	n/a	If required is empty, left must also be empty.
496	n/a	"""
497	n/a	required = tuple(required)
498	n/a	result = []
499	n/a
500	n/a	if not required:
501	n/a	assert not left
502	n/a
503	n/a	accumulator = []
504	n/a	counts = set()
505	n/a	for r in permute_right_option_groups(right):
506	n/a	for l in permute_left_option_groups(left):
507	n/a	t = l + required + r
508	n/a	if len(t) in counts:
509	n/a	continue
510	n/a	counts.add(len(t))
511	n/a	accumulator.append(t)
512	n/a
513	n/a	accumulator.sort(key=len)
514	n/a	return tuple(accumulator)
515	n/a
516	n/a
517	n/a	def strip_leading_and_trailing_blank_lines(s):
518	n/a	lines = s.rstrip().split('\n')
519	n/a	while lines:
520	n/a	line = lines[0]
521	n/a	if line.strip():
522	n/a	break
523	n/a	del lines[0]
524	n/a	return '\n'.join(lines)
525	n/a
526	n/a	@functools.lru_cache()
527	n/a	def normalize_snippet(s, *, indent=0):
528	n/a	"""
529	n/a	Reformats s:
530	n/a	* removes leading and trailing blank lines
531	n/a	* ensures that it does not end with a newline
532	n/a	* dedents so the first nonwhite character on any line is at column "indent"
533	n/a	"""
534	n/a	s = strip_leading_and_trailing_blank_lines(s)
535	n/a	s = textwrap.dedent(s)
536	n/a	if indent:
537	n/a	s = textwrap.indent(s, ' ' * indent)
538	n/a	return s
539	n/a
540	n/a
541	n/a	def wrap_declarations(text, length=78):
542	n/a	"""
543	n/a	A simple-minded text wrapper for C function declarations.
544	n/a
545	n/a	It views a declaration line as looking like this:
546	n/a	xxxxxxxx(xxxxxxxxx,xxxxxxxxx)
547	n/a	If called with length=30, it would wrap that line into
548	n/a	xxxxxxxx(xxxxxxxxx,
549	n/a	xxxxxxxxx)
550	n/a	(If the declaration has zero or one parameters, this
551	n/a	function won't wrap it.)
552	n/a
553	n/a	If this doesn't work properly, it's probably better to
554	n/a	start from scratch with a more sophisticated algorithm,
555	n/a	rather than try and improve/debug this dumb little function.
556	n/a	"""
557	n/a	lines = []
558	n/a	for line in text.split('\n'):
559	n/a	prefix, _, after_l_paren = line.partition('(')
560	n/a	if not after_l_paren:
561	n/a	lines.append(line)
562	n/a	continue
563	n/a	parameters, _, after_r_paren = after_l_paren.partition(')')
564	n/a	if not _:
565	n/a	lines.append(line)
566	n/a	continue
567	n/a	if ',' not in parameters:
568	n/a	lines.append(line)
569	n/a	continue
570	n/a	parameters = [x.strip() + ", " for x in parameters.split(',')]
571	n/a	prefix += "("
572	n/a	if len(prefix) < length:
573	n/a	spaces = " " * len(prefix)
574	n/a	else:
575	n/a	spaces = " " * 4
576	n/a
577	n/a	while parameters:
578	n/a	line = prefix
579	n/a	first = True
580	n/a	while parameters:
581	n/a	if (not first and
582	n/a	(len(line) + len(parameters[0]) > length)):
583	n/a	break
584	n/a	line += parameters.pop(0)
585	n/a	first = False
586	n/a	if not parameters:
587	n/a	line = line.rstrip(", ") + ")" + after_r_paren
588	n/a	lines.append(line.rstrip())
589	n/a	prefix = spaces
590	n/a	return "\n".join(lines)
591	n/a
592	n/a
593	n/a	class CLanguage(Language):
594	n/a
595	n/a	body_prefix = "#"
596	n/a	language = 'C'
597	n/a	start_line = "/*[{dsl_name} input]"
598	n/a	body_prefix = ""
599	n/a	stop_line = "[{dsl_name} start generated code]*/"
600	n/a	checksum_line = "/[{dsl_name} end generated code: {arguments}]/"
601	n/a
602	n/a	def __init__(self, filename):
603	n/a	super().__init__(filename)
604	n/a	self.cpp = cpp.Monitor(filename)
605	n/a	self.cpp.fail = fail
606	n/a
607	n/a	def parse_line(self, line):
608	n/a	self.cpp.writeline(line)
609	n/a
610	n/a	def render(self, clinic, signatures):
611	n/a	function = None
612	n/a	for o in signatures:
613	n/a	if isinstance(o, Function):
614	n/a	if function:
615	n/a	fail("You may specify at most one function per block.\nFound a block containing at least two:\n\t" + repr(function) + " and " + repr(o))
616	n/a	function = o
617	n/a	return self.render_function(clinic, function)
618	n/a
619	n/a	def docstring_for_c_string(self, f):
620	n/a	text, add, output = _text_accumulator()
621	n/a	# turn docstring into a properly quoted C string
622	n/a	for line in f.docstring.split('\n'):
623	n/a	add('"')
624	n/a	add(quoted_for_c_string(line))
625	n/a	add('\\n"\n')
626	n/a
627	n/a	if text[-2] == sig_end_marker:
628	n/a	# If we only have a signature, add the blank line that the
629	n/a	# __text_signature__ getter expects to be there.
630	n/a	add('"\\n"')
631	n/a	else:
632	n/a	text.pop()
633	n/a	add('"')
634	n/a	return ''.join(text)
635	n/a
636	n/a	def output_templates(self, f):
637	n/a	parameters = list(f.parameters.values())
638	n/a	assert parameters
639	n/a	assert isinstance(parameters[0].converter, self_converter)
640	n/a	del parameters[0]
641	n/a	converters = [p.converter for p in parameters]
642	n/a
643	n/a	has_option_groups = parameters and (parameters[0].group or parameters[-1].group)
644	n/a	default_return_converter = (not f.return_converter or
645	n/a	f.return_converter.type == 'PyObject *')
646	n/a
647	n/a	positional = parameters and parameters[-1].is_positional_only()
648	n/a	all_boring_objects = False # yes, this will be false if there are 0 parameters, it's fine
649	n/a	first_optional = len(parameters)
650	n/a	for i, p in enumerate(parameters):
651	n/a	c = p.converter
652	n/a	if type(c) != object_converter:
653	n/a	break
654	n/a	if c.format_unit != 'O':
655	n/a	break
656	n/a	if p.default is not unspecified:
657	n/a	first_optional = min(first_optional, i)
658	n/a	else:
659	n/a	all_boring_objects = True
660	n/a
661	n/a	new_or_init = f.kind in (METHOD_NEW, METHOD_INIT)
662	n/a
663	n/a	meth_o = (len(parameters) == 1 and
664	n/a	parameters[0].is_positional_only() and
665	n/a	not converters[0].is_optional() and
666	n/a	not new_or_init)
667	n/a
668	n/a	# we have to set these things before we're done:
669	n/a	#
670	n/a	# docstring_prototype
671	n/a	# docstring_definition
672	n/a	# impl_prototype
673	n/a	# methoddef_define
674	n/a	# parser_prototype
675	n/a	# parser_definition
676	n/a	# impl_definition
677	n/a	# cpp_if
678	n/a	# cpp_endif
679	n/a	# methoddef_ifndef
680	n/a
681	n/a	return_value_declaration = "PyObject *return_value = NULL;"
682	n/a
683	n/a	methoddef_define = normalize_snippet("""
684	n/a	#define {methoddef_name} \\
685	n/a	{{"{name}", (PyCFunction){c_basename}, {methoddef_flags}, {c_basename}__doc__}},
686	n/a	""")
687	n/a	if new_or_init and not f.docstring:
688	n/a	docstring_prototype = docstring_definition = ''
689	n/a	else:
690	n/a	docstring_prototype = normalize_snippet("""
691	n/a	PyDoc_VAR({c_basename}__doc__);
692	n/a	""")
693	n/a	docstring_definition = normalize_snippet("""
694	n/a	PyDoc_STRVAR({c_basename}__doc__,
695	n/a	{docstring});
696	n/a	""")
697	n/a	impl_definition = normalize_snippet("""
698	n/a	static {impl_return_type}
699	n/a	{c_basename}_impl({impl_parameters})
700	n/a	""")
701	n/a	impl_prototype = parser_prototype = parser_definition = None
702	n/a
703	n/a	parser_prototype_keyword = normalize_snippet("""
704	n/a	static PyObject *
705	n/a	{c_basename}({self_type}{self_name}, PyObject args, PyObject kwargs)
706	n/a	""")
707	n/a
708	n/a	parser_prototype_varargs = normalize_snippet("""
709	n/a	static PyObject *
710	n/a	{c_basename}({self_type}{self_name}, PyObject *args)
711	n/a	""")
712	n/a
713	n/a	parser_prototype_fastcall = normalize_snippet("""
714	n/a	static PyObject *
715	n/a	{c_basename}({self_type}{self_name}, PyObject *args, Py_ssize_t nargs, PyObject kwnames)
716	n/a	""")
717	n/a
718	n/a	# parser_body_fields remembers the fields passed in to the
719	n/a	# previous call to parser_body. this is used for an awful hack.
720	n/a	parser_body_fields = ()
721	n/a	def parser_body(prototype, *fields):
722	n/a	nonlocal parser_body_fields
723	n/a	add, output = text_accumulator()
724	n/a	add(prototype)
725	n/a	parser_body_fields = fields
726	n/a
727	n/a	fields = list(fields)
728	n/a	fields.insert(0, normalize_snippet("""
729	n/a	{{
730	n/a	{return_value_declaration}
731	n/a	{declarations}
732	n/a	{initializers}
733	n/a	""") + "\n")
734	n/a	# just imagine--your code is here in the middle
735	n/a	fields.append(normalize_snippet("""
736	n/a	{modifications}
737	n/a	{return_value} = {c_basename}_impl({impl_arguments});
738	n/a	{return_conversion}
739	n/a
740	n/a	{exit_label}
741	n/a	{cleanup}
742	n/a	return return_value;
743	n/a	}}
744	n/a	"""))
745	n/a	for field in fields:
746	n/a	add('\n')
747	n/a	add(field)
748	n/a	return output()
749	n/a
750	n/a	def insert_keywords(s):
751	n/a	return linear_format(s, declarations=
752	n/a	'static const char * const _keywords[] = {{{keywords}, NULL}};\n'
753	n/a	'static _PyArg_Parser _parser = {{"{format_units}:{name}", _keywords, 0}};\n'
754	n/a	'{declarations}')
755	n/a
756	n/a	if not parameters:
757	n/a	# no parameters, METH_NOARGS
758	n/a
759	n/a	flags = "METH_NOARGS"
760	n/a
761	n/a	parser_prototype = normalize_snippet("""
762	n/a	static PyObject *
763	n/a	{c_basename}({self_type}{self_name}, PyObject *Py_UNUSED(ignored))
764	n/a	""")
765	n/a	parser_definition = parser_prototype
766	n/a
767	n/a	if default_return_converter:
768	n/a	parser_definition = parser_prototype + '\n' + normalize_snippet("""
769	n/a	{{
770	n/a	return {c_basename}_impl({impl_arguments});
771	n/a	}}
772	n/a	""")
773	n/a	else:
774	n/a	parser_definition = parser_body(parser_prototype)
775	n/a
776	n/a	elif meth_o:
777	n/a	flags = "METH_O"
778	n/a
779	n/a	if (isinstance(converters[0], object_converter) and
780	n/a	converters[0].format_unit == 'O'):
781	n/a	meth_o_prototype = normalize_snippet("""
782	n/a	static PyObject *
783	n/a	{c_basename}({impl_parameters})
784	n/a	""")
785	n/a
786	n/a	if default_return_converter:
787	n/a	# maps perfectly to METH_O, doesn't need a return converter.
788	n/a	# so we skip making a parse function
789	n/a	# and call directly into the impl function.
790	n/a	impl_prototype = parser_prototype = parser_definition = ''
791	n/a	impl_definition = meth_o_prototype
792	n/a	else:
793	n/a	# SLIGHT HACK
794	n/a	# use impl_parameters for the parser here!
795	n/a	parser_prototype = meth_o_prototype
796	n/a	parser_definition = parser_body(parser_prototype)
797	n/a
798	n/a	else:
799	n/a	argname = 'arg'
800	n/a	if parameters[0].name == argname:
801	n/a	argname += '_'
802	n/a	parser_prototype = normalize_snippet("""
803	n/a	static PyObject *
804	n/a	{c_basename}({self_type}{self_name}, PyObject *%s)
805	n/a	""" % argname)
806	n/a
807	n/a	parser_definition = parser_body(parser_prototype, normalize_snippet("""
808	n/a	if (!PyArg_Parse(%s, "{format_units}:{name}", {parse_arguments})) {{
809	n/a	goto exit;
810	n/a	}}
811	n/a	""" % argname, indent=4))
812	n/a
813	n/a	elif has_option_groups:
814	n/a	# positional parameters with option groups
815	n/a	# (we have to generate lots of PyArg_ParseTuple calls
816	n/a	# in a big switch statement)
817	n/a
818	n/a	flags = "METH_VARARGS"
819	n/a	parser_prototype = parser_prototype_varargs
820	n/a
821	n/a	parser_definition = parser_body(parser_prototype, ' {option_group_parsing}')
822	n/a
823	n/a	elif positional and all_boring_objects:
824	n/a	# positional-only, but no option groups,
825	n/a	# and nothing but normal objects:
826	n/a	# PyArg_UnpackTuple!
827	n/a
828	n/a	if not new_or_init:
829	n/a	flags = "METH_FASTCALL"
830	n/a	parser_prototype = parser_prototype_fastcall
831	n/a
832	n/a	parser_definition = parser_body(parser_prototype, normalize_snippet("""
833	n/a	if (!_PyArg_UnpackStack(args, nargs, "{name}",
834	n/a	{unpack_min}, {unpack_max},
835	n/a	{parse_arguments})) {{
836	n/a	goto exit;
837	n/a	}}
838	n/a
839	n/a	if ({self_type_check}!_PyArg_NoStackKeywords("{name}", kwnames)) {{
840	n/a	goto exit;
841	n/a	}}
842	n/a	""", indent=4))
843	n/a	else:
844	n/a	flags = "METH_VARARGS"
845	n/a	parser_prototype = parser_prototype_varargs
846	n/a
847	n/a	parser_definition = parser_body(parser_prototype, normalize_snippet("""
848	n/a	if (!PyArg_UnpackTuple(args, "{name}",
849	n/a	{unpack_min}, {unpack_max},
850	n/a	{parse_arguments})) {{
851	n/a	goto exit;
852	n/a	}}
853	n/a	""", indent=4))
854	n/a
855	n/a	elif positional:
856	n/a	if not new_or_init:
857	n/a	# positional-only, but no option groups
858	n/a	# we only need one call to _PyArg_ParseStack
859	n/a
860	n/a	flags = "METH_FASTCALL"
861	n/a	parser_prototype = parser_prototype_fastcall
862	n/a
863	n/a	parser_definition = parser_body(parser_prototype, normalize_snippet("""
864	n/a	if (!_PyArg_ParseStack(args, nargs, "{format_units}:{name}",
865	n/a	{parse_arguments})) {{
866	n/a	goto exit;
867	n/a	}}
868	n/a
869	n/a	if ({self_type_check}!_PyArg_NoStackKeywords("{name}", kwnames)) {{
870	n/a	goto exit;
871	n/a	}}
872	n/a	""", indent=4))
873	n/a	else:
874	n/a	# positional-only, but no option groups
875	n/a	# we only need one call to PyArg_ParseTuple
876	n/a
877	n/a	flags = "METH_VARARGS"
878	n/a	parser_prototype = parser_prototype_varargs
879	n/a
880	n/a	parser_definition = parser_body(parser_prototype, normalize_snippet("""
881	n/a	if (!PyArg_ParseTuple(args, "{format_units}:{name}",
882	n/a	{parse_arguments})) {{
883	n/a	goto exit;
884	n/a	}}
885	n/a	""", indent=4))
886	n/a
887	n/a	elif not new_or_init:
888	n/a	flags = "METH_FASTCALL"
889	n/a
890	n/a	parser_prototype = parser_prototype_fastcall
891	n/a
892	n/a	body = normalize_snippet("""
893	n/a	if (!_PyArg_ParseStackAndKeywords(args, nargs, kwnames, &_parser,
894	n/a	{parse_arguments})) {{
895	n/a	goto exit;
896	n/a	}}
897	n/a	""", indent=4)
898	n/a	parser_definition = parser_body(parser_prototype, body)
899	n/a	parser_definition = insert_keywords(parser_definition)
900	n/a	else:
901	n/a	# positional-or-keyword arguments
902	n/a	flags = "METH_VARARGS\|METH_KEYWORDS"
903	n/a
904	n/a	parser_prototype = parser_prototype_keyword
905	n/a
906	n/a	body = normalize_snippet("""
907	n/a	if (!_PyArg_ParseTupleAndKeywordsFast(args, kwargs, &_parser,
908	n/a	{parse_arguments})) {{
909	n/a	goto exit;
910	n/a	}}
911	n/a	""", indent=4)
912	n/a	parser_definition = parser_body(parser_prototype, body)
913	n/a	parser_definition = insert_keywords(parser_definition)
914	n/a
915	n/a
916	n/a	if new_or_init:
917	n/a	methoddef_define = ''
918	n/a
919	n/a	if f.kind == METHOD_NEW:
920	n/a	parser_prototype = parser_prototype_keyword
921	n/a	else:
922	n/a	return_value_declaration = "int return_value = -1;"
923	n/a	parser_prototype = normalize_snippet("""
924	n/a	static int
925	n/a	{c_basename}({self_type}{self_name}, PyObject args, PyObject kwargs)
926	n/a	""")
927	n/a
928	n/a	fields = list(parser_body_fields)
929	n/a	parses_positional = 'METH_NOARGS' not in flags
930	n/a	parses_keywords = 'METH_KEYWORDS' in flags
931	n/a	if parses_keywords:
932	n/a	assert parses_positional
933	n/a
934	n/a	if not parses_keywords:
935	n/a	fields.insert(0, normalize_snippet("""
936	n/a	if ({self_type_check}!_PyArg_NoKeywords("{name}", kwargs)) {{
937	n/a	goto exit;
938	n/a	}}
939	n/a	""", indent=4))
940	n/a	if not parses_positional:
941	n/a	fields.insert(0, normalize_snippet("""
942	n/a	if ({self_type_check}!_PyArg_NoPositional("{name}", args)) {{
943	n/a	goto exit;
944	n/a	}}
945	n/a	""", indent=4))
946	n/a
947	n/a	parser_definition = parser_body(parser_prototype, *fields)
948	n/a	if parses_keywords:
949	n/a	parser_definition = insert_keywords(parser_definition)
950	n/a
951	n/a
952	n/a	if f.methoddef_flags:
953	n/a	flags += '\|' + f.methoddef_flags
954	n/a
955	n/a	methoddef_define = methoddef_define.replace('{methoddef_flags}', flags)
956	n/a
957	n/a	methoddef_ifndef = ''
958	n/a	conditional = self.cpp.condition()
959	n/a	if not conditional:
960	n/a	cpp_if = cpp_endif = ''
961	n/a	else:
962	n/a	cpp_if = "#if " + conditional
963	n/a	cpp_endif = "#endif /* " + conditional + " */"
964	n/a
965	n/a	if methoddef_define and f.name not in clinic.ifndef_symbols:
966	n/a	clinic.ifndef_symbols.add(f.name)
967	n/a	methoddef_ifndef = normalize_snippet("""
968	n/a	#ifndef {methoddef_name}
969	n/a	#define {methoddef_name}
970	n/a	#endif /* !defined({methoddef_name}) */
971	n/a	""")
972	n/a
973	n/a
974	n/a	# add ';' to the end of parser_prototype and impl_prototype
975	n/a	# (they mustn't be None, but they could be an empty string.)
976	n/a	assert parser_prototype is not None
977	n/a	if parser_prototype:
978	n/a	assert not parser_prototype.endswith(';')
979	n/a	parser_prototype += ';'
980	n/a
981	n/a	if impl_prototype is None:
982	n/a	impl_prototype = impl_definition
983	n/a	if impl_prototype:
984	n/a	impl_prototype += ";"
985	n/a
986	n/a	parser_definition = parser_definition.replace("{return_value_declaration}", return_value_declaration)
987	n/a
988	n/a	d = {
989	n/a	"docstring_prototype" : docstring_prototype,
990	n/a	"docstring_definition" : docstring_definition,
991	n/a	"impl_prototype" : impl_prototype,
992	n/a	"methoddef_define" : methoddef_define,
993	n/a	"parser_prototype" : parser_prototype,
994	n/a	"parser_definition" : parser_definition,
995	n/a	"impl_definition" : impl_definition,
996	n/a	"cpp_if" : cpp_if,
997	n/a	"cpp_endif" : cpp_endif,
998	n/a	"methoddef_ifndef" : methoddef_ifndef,
999	n/a	}
1000	n/a
1001	n/a	# make sure we didn't forget to assign something,
1002	n/a	# and wrap each non-empty value in \n's
1003	n/a	d2 = {}
1004	n/a	for name, value in d.items():
1005	n/a	assert value is not None, "got a None value for template " + repr(name)
1006	n/a	if value:
1007	n/a	value = '\n' + value + '\n'
1008	n/a	d2[name] = value
1009	n/a	return d2
1010	n/a
1011	n/a	@staticmethod
1012	n/a	def group_to_variable_name(group):
1013	n/a	adjective = "left_" if group < 0 else "right_"
1014	n/a	return "group_" + adjective + str(abs(group))
1015	n/a
1016	n/a	def render_option_group_parsing(self, f, template_dict):
1017	n/a	# positional only, grouped, optional arguments!
1018	n/a	# can be optional on the left or right.
1019	n/a	# here's an example:
1020	n/a	#
1021	n/a	# [ [ [ A1 A2 ] B1 B2 B3 ] C1 C2 ] D1 D2 D3 [ E1 E2 E3 [ F1 F2 F3 ] ]
1022	n/a	#
1023	n/a	# Here group D are required, and all other groups are optional.
1024	n/a	# (Group D's "group" is actually None.)
1025	n/a	# We can figure out which sets of arguments we have based on
1026	n/a	# how many arguments are in the tuple.
1027	n/a	#
1028	n/a	# Note that you need to count up on both sides. For example,
1029	n/a	# you could have groups C+D, or C+D+E, or C+D+E+F.
1030	n/a	#
1031	n/a	# What if the number of arguments leads us to an ambiguous result?
1032	n/a	# Clinic prefers groups on the left. So in the above example,
1033	n/a	# five arguments would map to B+C, not C+D.
1034	n/a
1035	n/a	add, output = text_accumulator()
1036	n/a	parameters = list(f.parameters.values())
1037	n/a	if isinstance(parameters[0].converter, self_converter):
1038	n/a	del parameters[0]
1039	n/a
1040	n/a	groups = []
1041	n/a	group = None
1042	n/a	left = []
1043	n/a	right = []
1044	n/a	required = []
1045	n/a	last = unspecified
1046	n/a
1047	n/a	for p in parameters:
1048	n/a	group_id = p.group
1049	n/a	if group_id != last:
1050	n/a	last = group_id
1051	n/a	group = []
1052	n/a	if group_id < 0:
1053	n/a	left.append(group)
1054	n/a	elif group_id == 0:
1055	n/a	group = required
1056	n/a	else:
1057	n/a	right.append(group)
1058	n/a	group.append(p)
1059	n/a
1060	n/a	count_min = sys.maxsize
1061	n/a	count_max = -1
1062	n/a
1063	n/a	add("switch (PyTuple_GET_SIZE(args)) {\n")
1064	n/a	for subset in permute_optional_groups(left, required, right):
1065	n/a	count = len(subset)
1066	n/a	count_min = min(count_min, count)
1067	n/a	count_max = max(count_max, count)
1068	n/a
1069	n/a	if count == 0:
1070	n/a	add(""" case 0:
1071	n/a	break;
1072	n/a	""")
1073	n/a	continue
1074	n/a
1075	n/a	group_ids = {p.group for p in subset} # eliminate duplicates
1076	n/a	d = {}
1077	n/a	d['count'] = count
1078	n/a	d['name'] = f.name
1079	n/a	d['format_units'] = "".join(p.converter.format_unit for p in subset)
1080	n/a
1081	n/a	parse_arguments = []
1082	n/a	for p in subset:
1083	n/a	p.converter.parse_argument(parse_arguments)
1084	n/a	d['parse_arguments'] = ", ".join(parse_arguments)
1085	n/a
1086	n/a	group_ids.discard(0)
1087	n/a	lines = [self.group_to_variable_name(g) + " = 1;" for g in group_ids]
1088	n/a	lines = "\n".join(lines)
1089	n/a
1090	n/a	s = """
1091	n/a	case {count}:
1092	n/a	if (!PyArg_ParseTuple(args, "{format_units}:{name}", {parse_arguments})) {{
1093	n/a	goto exit;
1094	n/a	}}
1095	n/a	{group_booleans}
1096	n/a	break;
1097	n/a	"""[1:]
1098	n/a	s = linear_format(s, group_booleans=lines)
1099	n/a	s = s.format_map(d)
1100	n/a	add(s)
1101	n/a
1102	n/a	add(" default:\n")
1103	n/a	s = ' PyErr_SetString(PyExc_TypeError, "{} requires {} to {} arguments");\n'
1104	n/a	add(s.format(f.full_name, count_min, count_max))
1105	n/a	add(' goto exit;\n')
1106	n/a	add("}")
1107	n/a	template_dict['option_group_parsing'] = format_escape(output())
1108	n/a
1109	n/a	def render_function(self, clinic, f):
1110	n/a	if not f:
1111	n/a	return ""
1112	n/a
1113	n/a	add, output = text_accumulator()
1114	n/a	data = CRenderData()
1115	n/a
1116	n/a	assert f.parameters, "We should always have a 'self' at this point!"
1117	n/a	parameters = f.render_parameters
1118	n/a	converters = [p.converter for p in parameters]
1119	n/a
1120	n/a	templates = self.output_templates(f)
1121	n/a
1122	n/a	f_self = parameters[0]
1123	n/a	selfless = parameters[1:]
1124	n/a	assert isinstance(f_self.converter, self_converter), "No self parameter in " + repr(f.full_name) + "!"
1125	n/a
1126	n/a	last_group = 0
1127	n/a	first_optional = len(selfless)
1128	n/a	positional = selfless and selfless[-1].is_positional_only()
1129	n/a	new_or_init = f.kind in (METHOD_NEW, METHOD_INIT)
1130	n/a	default_return_converter = (not f.return_converter or
1131	n/a	f.return_converter.type == 'PyObject *')
1132	n/a	has_option_groups = False
1133	n/a
1134	n/a	# offset i by -1 because first_optional needs to ignore self
1135	n/a	for i, p in enumerate(parameters, -1):
1136	n/a	c = p.converter
1137	n/a
1138	n/a	if (i != -1) and (p.default is not unspecified):
1139	n/a	first_optional = min(first_optional, i)
1140	n/a
1141	n/a	# insert group variable
1142	n/a	group = p.group
1143	n/a	if last_group != group:
1144	n/a	last_group = group
1145	n/a	if group:
1146	n/a	group_name = self.group_to_variable_name(group)
1147	n/a	data.impl_arguments.append(group_name)
1148	n/a	data.declarations.append("int " + group_name + " = 0;")
1149	n/a	data.impl_parameters.append("int " + group_name)
1150	n/a	has_option_groups = True
1151	n/a
1152	n/a	c.render(p, data)
1153	n/a
1154	n/a	if has_option_groups and (not positional):
1155	n/a	fail("You cannot use optional groups ('[' and ']')\nunless all parameters are positional-only ('/').")
1156	n/a
1157	n/a	# HACK
1158	n/a	# when we're METH_O, but have a custom return converter,
1159	n/a	# we use "impl_parameters" for the parsing function
1160	n/a	# because that works better. but that means we must
1161	n/a	# suppress actually declaring the impl's parameters
1162	n/a	# as variables in the parsing function. but since it's
1163	n/a	# METH_O, we have exactly one anyway, so we know exactly
1164	n/a	# where it is.
1165	n/a	if ("METH_O" in templates['methoddef_define'] and
1166	n/a	'{impl_parameters}' in templates['parser_prototype']):
1167	n/a	data.declarations.pop(0)
1168	n/a
1169	n/a	template_dict = {}
1170	n/a
1171	n/a	full_name = f.full_name
1172	n/a	template_dict['full_name'] = full_name
1173	n/a
1174	n/a	if new_or_init:
1175	n/a	name = f.cls.name
1176	n/a	else:
1177	n/a	name = f.name
1178	n/a
1179	n/a	template_dict['name'] = name
1180	n/a
1181	n/a	if f.c_basename:
1182	n/a	c_basename = f.c_basename
1183	n/a	else:
1184	n/a	fields = full_name.split(".")
1185	n/a	if fields[-1] == '__new__':
1186	n/a	fields.pop()
1187	n/a	c_basename = "_".join(fields)
1188	n/a
1189	n/a	template_dict['c_basename'] = c_basename
1190	n/a
1191	n/a	methoddef_name = "{}_METHODDEF".format(c_basename.upper())
1192	n/a	template_dict['methoddef_name'] = methoddef_name
1193	n/a
1194	n/a	template_dict['docstring'] = self.docstring_for_c_string(f)
1195	n/a
1196	n/a	template_dict['self_name'] = template_dict['self_type'] = template_dict['self_type_check'] = ''
1197	n/a	f_self.converter.set_template_dict(template_dict)
1198	n/a
1199	n/a	f.return_converter.render(f, data)
1200	n/a	template_dict['impl_return_type'] = f.return_converter.type
1201	n/a
1202	n/a	template_dict['declarations'] = format_escape("\n".join(data.declarations))
1203	n/a	template_dict['initializers'] = "\n\n".join(data.initializers)
1204	n/a	template_dict['modifications'] = '\n\n'.join(data.modifications)
1205	n/a	template_dict['keywords'] = '"' + '", "'.join(data.keywords) + '"'
1206	n/a	template_dict['format_units'] = ''.join(data.format_units)
1207	n/a	template_dict['parse_arguments'] = ', '.join(data.parse_arguments)
1208	n/a	template_dict['impl_parameters'] = ", ".join(data.impl_parameters)
1209	n/a	template_dict['impl_arguments'] = ", ".join(data.impl_arguments)
1210	n/a	template_dict['return_conversion'] = format_escape("".join(data.return_conversion).rstrip())
1211	n/a	template_dict['cleanup'] = format_escape("".join(data.cleanup))
1212	n/a	template_dict['return_value'] = data.return_value
1213	n/a
1214	n/a	# used by unpack tuple code generator
1215	n/a	ignore_self = -1 if isinstance(converters[0], self_converter) else 0
1216	n/a	unpack_min = first_optional
1217	n/a	unpack_max = len(selfless)
1218	n/a	template_dict['unpack_min'] = str(unpack_min)
1219	n/a	template_dict['unpack_max'] = str(unpack_max)
1220	n/a
1221	n/a	if has_option_groups:
1222	n/a	self.render_option_group_parsing(f, template_dict)
1223	n/a
1224	n/a	# buffers, not destination
1225	n/a	for name, destination in clinic.destination_buffers.items():
1226	n/a	template = templates[name]
1227	n/a	if has_option_groups:
1228	n/a	template = linear_format(template,
1229	n/a	option_group_parsing=template_dict['option_group_parsing'])
1230	n/a	template = linear_format(template,
1231	n/a	declarations=template_dict['declarations'],
1232	n/a	return_conversion=template_dict['return_conversion'],
1233	n/a	initializers=template_dict['initializers'],
1234	n/a	modifications=template_dict['modifications'],
1235	n/a	cleanup=template_dict['cleanup'],
1236	n/a	)
1237	n/a
1238	n/a	# Only generate the "exit:" label
1239	n/a	# if we have any gotos
1240	n/a	need_exit_label = "goto exit;" in template
1241	n/a	template = linear_format(template,
1242	n/a	exit_label="exit:" if need_exit_label else ''
1243	n/a	)
1244	n/a
1245	n/a	s = template.format_map(template_dict)
1246	n/a
1247	n/a	# mild hack:
1248	n/a	# reflow long impl declarations
1249	n/a	if name in {"impl_prototype", "impl_definition"}:
1250	n/a	s = wrap_declarations(s)
1251	n/a
1252	n/a	if clinic.line_prefix:
1253	n/a	s = indent_all_lines(s, clinic.line_prefix)
1254	n/a	if clinic.line_suffix:
1255	n/a	s = suffix_all_lines(s, clinic.line_suffix)
1256	n/a
1257	n/a	destination.append(s)
1258	n/a
1259	n/a	return clinic.get_destination('block').dump()
1260	n/a
1261	n/a
1262	n/a
1263	n/a
1264	n/a	@contextlib.contextmanager
1265	n/a	def OverrideStdioWith(stdout):
1266	n/a	saved_stdout = sys.stdout
1267	n/a	sys.stdout = stdout
1268	n/a	try:
1269	n/a	yield
1270	n/a	finally:
1271	n/a	assert sys.stdout is stdout
1272	n/a	sys.stdout = saved_stdout
1273	n/a
1274	n/a
1275	n/a	def create_regex(before, after, word=True, whole_line=True):
1276	n/a	"""Create an re object for matching marker lines."""
1277	n/a	group_re = r"\w+" if word else ".+"
1278	n/a	pattern = r'{}({}){}'
1279	n/a	if whole_line:
1280	n/a	pattern = '^' + pattern + '$'
1281	n/a	pattern = pattern.format(re.escape(before), group_re, re.escape(after))
1282	n/a	return re.compile(pattern)
1283	n/a
1284	n/a
1285	n/a	class Block:
1286	n/a	r"""
1287	n/a	Represents a single block of text embedded in
1288	n/a	another file. If dsl_name is None, the block represents
1289	n/a	verbatim text, raw original text from the file, in
1290	n/a	which case "input" will be the only non-false member.
1291	n/a	If dsl_name is not None, the block represents a Clinic
1292	n/a	block.
1293	n/a
1294	n/a	input is always str, with embedded \n characters.
1295	n/a	input represents the original text from the file;
1296	n/a	if it's a Clinic block, it is the original text with
1297	n/a	the body_prefix and redundant leading whitespace removed.
1298	n/a
1299	n/a	dsl_name is either str or None. If str, it's the text
1300	n/a	found on the start line of the block between the square
1301	n/a	brackets.
1302	n/a
1303	n/a	signatures is either list or None. If it's a list,
1304	n/a	it may only contain clinic.Module, clinic.Class, and
1305	n/a	clinic.Function objects. At the moment it should
1306	n/a	contain at most one of each.
1307	n/a
1308	n/a	output is either str or None. If str, it's the output
1309	n/a	from this block, with embedded '\n' characters.
1310	n/a
1311	n/a	indent is either str or None. It's the leading whitespace
1312	n/a	that was found on every line of input. (If body_prefix is
1313	n/a	not empty, this is the indent after removing the
1314	n/a	body_prefix.)
1315	n/a
1316	n/a	preindent is either str or None. It's the whitespace that
1317	n/a	was found in front of every line of input before the
1318	n/a	"body_prefix" (see the Language object). If body_prefix
1319	n/a	is empty, preindent must always be empty too.
1320	n/a
1321	n/a	To illustrate indent and preindent: Assume that '_'
1322	n/a	represents whitespace. If the block processed was in a
1323	n/a	Python file, and looked like this:
1324	n/a	____#/*[python]
1325	n/a	____#__for a in range(20):
1326	n/a	____#____print(a)
1327	n/a	____#[python]*/
1328	n/a	"preindent" would be "____" and "indent" would be "__".
1329	n/a
1330	n/a	"""
1331	n/a	def __init__(self, input, dsl_name=None, signatures=None, output=None, indent='', preindent=''):
1332	n/a	assert isinstance(input, str)
1333	n/a	self.input = input
1334	n/a	self.dsl_name = dsl_name
1335	n/a	self.signatures = signatures or []
1336	n/a	self.output = output
1337	n/a	self.indent = indent
1338	n/a	self.preindent = preindent
1339	n/a
1340	n/a	def __repr__(self):
1341	n/a	dsl_name = self.dsl_name or "text"
1342	n/a	def summarize(s):
1343	n/a	s = repr(s)
1344	n/a	if len(s) > 30:
1345	n/a	return s[:26] + "..." + s[0]
1346	n/a	return s
1347	n/a	return "".join((
1348	n/a	"<Block ", dsl_name, " input=", summarize(self.input), " output=", summarize(self.output), ">"))
1349	n/a
1350	n/a
1351	n/a	class BlockParser:
1352	n/a	"""
1353	n/a	Block-oriented parser for Argument Clinic.
1354	n/a	Iterator, yields Block objects.
1355	n/a	"""
1356	n/a
1357	n/a	def __init__(self, input, language, *, verify=True):
1358	n/a	"""
1359	n/a	"input" should be a str object
1360	n/a	with embedded \n characters.
1361	n/a
1362	n/a	"language" should be a Language object.
1363	n/a	"""
1364	n/a	language.validate()
1365	n/a
1366	n/a	self.input = collections.deque(reversed(input.splitlines(keepends=True)))
1367	n/a	self.block_start_line_number = self.line_number = 0
1368	n/a
1369	n/a	self.language = language
1370	n/a	before, _, after = language.start_line.partition('{dsl_name}')
1371	n/a	assert _ == '{dsl_name}'
1372	n/a	self.find_start_re = create_regex(before, after, whole_line=False)
1373	n/a	self.start_re = create_regex(before, after)
1374	n/a	self.verify = verify
1375	n/a	self.last_checksum_re = None
1376	n/a	self.last_dsl_name = None
1377	n/a	self.dsl_name = None
1378	n/a	self.first_block = True
1379	n/a
1380	n/a	def __iter__(self):
1381	n/a	return self
1382	n/a
1383	n/a	def __next__(self):
1384	n/a	while True:
1385	n/a	if not self.input:
1386	n/a	raise StopIteration
1387	n/a
1388	n/a	if self.dsl_name:
1389	n/a	return_value = self.parse_clinic_block(self.dsl_name)
1390	n/a	self.dsl_name = None
1391	n/a	self.first_block = False
1392	n/a	return return_value
1393	n/a	block = self.parse_verbatim_block()
1394	n/a	if self.first_block and not block.input:
1395	n/a	continue
1396	n/a	self.first_block = False
1397	n/a	return block
1398	n/a
1399	n/a
1400	n/a	def is_start_line(self, line):
1401	n/a	match = self.start_re.match(line.lstrip())
1402	n/a	return match.group(1) if match else None
1403	n/a
1404	n/a	def _line(self, lookahead=False):
1405	n/a	self.line_number += 1
1406	n/a	line = self.input.pop()
1407	n/a	if not lookahead:
1408	n/a	self.language.parse_line(line)
1409	n/a	return line
1410	n/a
1411	n/a	def parse_verbatim_block(self):
1412	n/a	add, output = text_accumulator()
1413	n/a	self.block_start_line_number = self.line_number
1414	n/a
1415	n/a	while self.input:
1416	n/a	line = self._line()
1417	n/a	dsl_name = self.is_start_line(line)
1418	n/a	if dsl_name:
1419	n/a	self.dsl_name = dsl_name
1420	n/a	break
1421	n/a	add(line)
1422	n/a
1423	n/a	return Block(output())
1424	n/a
1425	n/a	def parse_clinic_block(self, dsl_name):
1426	n/a	input_add, input_output = text_accumulator()
1427	n/a	self.block_start_line_number = self.line_number + 1
1428	n/a	stop_line = self.language.stop_line.format(dsl_name=dsl_name)
1429	n/a	body_prefix = self.language.body_prefix.format(dsl_name=dsl_name)
1430	n/a
1431	n/a	def is_stop_line(line):
1432	n/a	# make sure to recognize stop line even if it
1433	n/a	# doesn't end with EOL (it could be the very end of the file)
1434	n/a	if not line.startswith(stop_line):
1435	n/a	return False
1436	n/a	remainder = line[len(stop_line):]
1437	n/a	return (not remainder) or remainder.isspace()
1438	n/a
1439	n/a	# consume body of program
1440	n/a	while self.input:
1441	n/a	line = self._line()
1442	n/a	if is_stop_line(line) or self.is_start_line(line):
1443	n/a	break
1444	n/a	if body_prefix:
1445	n/a	line = line.lstrip()
1446	n/a	assert line.startswith(body_prefix)
1447	n/a	line = line[len(body_prefix):]
1448	n/a	input_add(line)
1449	n/a
1450	n/a	# consume output and checksum line, if present.
1451	n/a	if self.last_dsl_name == dsl_name:
1452	n/a	checksum_re = self.last_checksum_re
1453	n/a	else:
1454	n/a	before, _, after = self.language.checksum_line.format(dsl_name=dsl_name, arguments='{arguments}').partition('{arguments}')
1455	n/a	assert _ == '{arguments}'
1456	n/a	checksum_re = create_regex(before, after, word=False)
1457	n/a	self.last_dsl_name = dsl_name
1458	n/a	self.last_checksum_re = checksum_re
1459	n/a
1460	n/a	# scan forward for checksum line
1461	n/a	output_add, output_output = text_accumulator()
1462	n/a	arguments = None
1463	n/a	while self.input:
1464	n/a	line = self._line(lookahead=True)
1465	n/a	match = checksum_re.match(line.lstrip())
1466	n/a	arguments = match.group(1) if match else None
1467	n/a	if arguments:
1468	n/a	break
1469	n/a	output_add(line)
1470	n/a	if self.is_start_line(line):
1471	n/a	break
1472	n/a
1473	n/a	output = output_output()
1474	n/a	if arguments:
1475	n/a	d = {}
1476	n/a	for field in shlex.split(arguments):
1477	n/a	name, equals, value = field.partition('=')
1478	n/a	if not equals:
1479	n/a	fail("Mangled Argument Clinic marker line: {!r}".format(line))
1480	n/a	d[name.strip()] = value.strip()
1481	n/a
1482	n/a	if self.verify:
1483	n/a	if 'input' in d:
1484	n/a	checksum = d['output']
1485	n/a	input_checksum = d['input']
1486	n/a	else:
1487	n/a	checksum = d['checksum']
1488	n/a	input_checksum = None
1489	n/a
1490	n/a	computed = compute_checksum(output, len(checksum))
1491	n/a	if checksum != computed:
1492	n/a	fail("Checksum mismatch!\nExpected: {}\nComputed: {}\n"
1493	n/a	"Suggested fix: remove all generated code including "
1494	n/a	"the end marker,\n"
1495	n/a	"or use the '-f' option."
1496	n/a	.format(checksum, computed))
1497	n/a	else:
1498	n/a	# put back output
1499	n/a	output_lines = output.splitlines(keepends=True)
1500	n/a	self.line_number -= len(output_lines)
1501	n/a	self.input.extend(reversed(output_lines))
1502	n/a	output = None
1503	n/a
1504	n/a	return Block(input_output(), dsl_name, output=output)
1505	n/a
1506	n/a
1507	n/a	class BlockPrinter:
1508	n/a
1509	n/a	def __init__(self, language, f=None):
1510	n/a	self.language = language
1511	n/a	self.f = f or io.StringIO()
1512	n/a
1513	n/a	def print_block(self, block):
1514	n/a	input = block.input
1515	n/a	output = block.output
1516	n/a	dsl_name = block.dsl_name
1517	n/a	write = self.f.write
1518	n/a
1519	n/a	assert not ((dsl_name == None) ^ (output == None)), "you must specify dsl_name and output together, dsl_name " + repr(dsl_name)
1520	n/a
1521	n/a	if not dsl_name:
1522	n/a	write(input)
1523	n/a	return
1524	n/a
1525	n/a	write(self.language.start_line.format(dsl_name=dsl_name))
1526	n/a	write("\n")
1527	n/a
1528	n/a	body_prefix = self.language.body_prefix.format(dsl_name=dsl_name)
1529	n/a	if not body_prefix:
1530	n/a	write(input)
1531	n/a	else:
1532	n/a	for line in input.split('\n'):
1533	n/a	write(body_prefix)
1534	n/a	write(line)
1535	n/a	write("\n")
1536	n/a
1537	n/a	write(self.language.stop_line.format(dsl_name=dsl_name))
1538	n/a	write("\n")
1539	n/a
1540	n/a	input = ''.join(block.input)
1541	n/a	output = ''.join(block.output)
1542	n/a	if output:
1543	n/a	if not output.endswith('\n'):
1544	n/a	output += '\n'
1545	n/a	write(output)
1546	n/a
1547	n/a	arguments="output={} input={}".format(compute_checksum(output, 16), compute_checksum(input, 16))
1548	n/a	write(self.language.checksum_line.format(dsl_name=dsl_name, arguments=arguments))
1549	n/a	write("\n")
1550	n/a
1551	n/a	def write(self, text):
1552	n/a	self.f.write(text)
1553	n/a
1554	n/a
1555	n/a	class BufferSeries:
1556	n/a	"""
1557	n/a	Behaves like a "defaultlist".
1558	n/a	When you ask for an index that doesn't exist yet,
1559	n/a	the object grows the list until that item exists.
1560	n/a	So o[n] will always work.
1561	n/a
1562	n/a	Supports negative indices for actual items.
1563	n/a	e.g. o[-1] is an element immediately preceding o[0].
1564	n/a	"""
1565	n/a
1566	n/a	def __init__(self):
1567	n/a	self._start = 0
1568	n/a	self._array = []
1569	n/a	self._constructor = _text_accumulator
1570	n/a
1571	n/a	def __getitem__(self, i):
1572	n/a	i -= self._start
1573	n/a	if i < 0:
1574	n/a	self._start += i
1575	n/a	prefix = [self._constructor() for x in range(-i)]
1576	n/a	self._array = prefix + self._array
1577	n/a	i = 0
1578	n/a	while i >= len(self._array):
1579	n/a	self._array.append(self._constructor())
1580	n/a	return self._array[i]
1581	n/a
1582	n/a	def clear(self):
1583	n/a	for ta in self._array:
1584	n/a	ta._text.clear()
1585	n/a
1586	n/a	def dump(self):
1587	n/a	texts = [ta.output() for ta in self._array]
1588	n/a	return "".join(texts)
1589	n/a
1590	n/a
1591	n/a	class Destination:
1592	n/a	def __init__(self, name, type, clinic, *args):
1593	n/a	self.name = name
1594	n/a	self.type = type
1595	n/a	self.clinic = clinic
1596	n/a	valid_types = ('buffer', 'file', 'suppress')
1597	n/a	if type not in valid_types:
1598	n/a	fail("Invalid destination type " + repr(type) + " for " + name + " , must be " + ', '.join(valid_types))
1599	n/a	extra_arguments = 1 if type == "file" else 0
1600	n/a	if len(args) < extra_arguments:
1601	n/a	fail("Not enough arguments for destination " + name + " new " + type)
1602	n/a	if len(args) > extra_arguments:
1603	n/a	fail("Too many arguments for destination " + name + " new " + type)
1604	n/a	if type =='file':
1605	n/a	d = {}
1606	n/a	filename = clinic.filename
1607	n/a	d['path'] = filename
1608	n/a	dirname, basename = os.path.split(filename)
1609	n/a	if not dirname:
1610	n/a	dirname = '.'
1611	n/a	d['dirname'] = dirname
1612	n/a	d['basename'] = basename
1613	n/a	d['basename_root'], d['basename_extension'] = os.path.splitext(filename)
1614	n/a	self.filename = args[0].format_map(d)
1615	n/a
1616	n/a	self.buffers = BufferSeries()
1617	n/a
1618	n/a	def __repr__(self):
1619	n/a	if self.type == 'file':
1620	n/a	file_repr = " " + repr(self.filename)
1621	n/a	else:
1622	n/a	file_repr = ''
1623	n/a	return "".join(("<Destination ", self.name, " ", self.type, file_repr, ">"))
1624	n/a
1625	n/a	def clear(self):
1626	n/a	if self.type != 'buffer':
1627	n/a	fail("Can't clear destination" + self.name + " , it's not of type buffer")
1628	n/a	self.buffers.clear()
1629	n/a
1630	n/a	def dump(self):
1631	n/a	return self.buffers.dump()
1632	n/a
1633	n/a
1634	n/a	# maps strings to Language objects.
1635	n/a	# "languages" maps the name of the language ("C", "Python").
1636	n/a	# "extensions" maps the file extension ("c", "py").
1637	n/a	languages = { 'C': CLanguage, 'Python': PythonLanguage }
1638	n/a	extensions = { name: CLanguage for name in "c cc cpp cxx h hh hpp hxx".split() }
1639	n/a	extensions['py'] = PythonLanguage
1640	n/a
1641	n/a
1642	n/a	# maps strings to callables.
1643	n/a	# these callables must be of the form:
1644	n/a	# def foo(name, default, *, ...)
1645	n/a	# The callable may have any number of keyword-only parameters.
1646	n/a	# The callable must return a CConverter object.
1647	n/a	# The callable should not call builtins.print.
1648	n/a	converters = {}
1649	n/a
1650	n/a	# maps strings to callables.
1651	n/a	# these callables follow the same rules as those for "converters" above.
1652	n/a	# note however that they will never be called with keyword-only parameters.
1653	n/a	legacy_converters = {}
1654	n/a
1655	n/a
1656	n/a	# maps strings to callables.
1657	n/a	# these callables must be of the form:
1658	n/a	# def foo(*, ...)
1659	n/a	# The callable may have any number of keyword-only parameters.
1660	n/a	# The callable must return a CConverter object.
1661	n/a	# The callable should not call builtins.print.
1662	n/a	return_converters = {}
1663	n/a
1664	n/a	clinic = None
1665	n/a	class Clinic:
1666	n/a
1667	n/a	presets_text = """
1668	n/a	preset block
1669	n/a	everything block
1670	n/a	methoddef_ifndef buffer 1
1671	n/a	docstring_prototype suppress
1672	n/a	parser_prototype suppress
1673	n/a	cpp_if suppress
1674	n/a	cpp_endif suppress
1675	n/a
1676	n/a	preset original
1677	n/a	everything block
1678	n/a	methoddef_ifndef buffer 1
1679	n/a	docstring_prototype suppress
1680	n/a	parser_prototype suppress
1681	n/a	cpp_if suppress
1682	n/a	cpp_endif suppress
1683	n/a
1684	n/a	preset file
1685	n/a	everything file
1686	n/a	methoddef_ifndef file 1
1687	n/a	docstring_prototype suppress
1688	n/a	parser_prototype suppress
1689	n/a	impl_definition block
1690	n/a
1691	n/a	preset buffer
1692	n/a	everything buffer
1693	n/a	methoddef_ifndef buffer 1
1694	n/a	impl_definition block
1695	n/a	docstring_prototype suppress
1696	n/a	impl_prototype suppress
1697	n/a	parser_prototype suppress
1698	n/a
1699	n/a	preset partial-buffer
1700	n/a	everything buffer
1701	n/a	methoddef_ifndef buffer 1
1702	n/a	docstring_prototype block
1703	n/a	impl_prototype suppress
1704	n/a	methoddef_define block
1705	n/a	parser_prototype block
1706	n/a	impl_definition block
1707	n/a
1708	n/a	"""
1709	n/a
1710	n/a	def __init__(self, language, printer=None, *, force=False, verify=True, filename=None):
1711	n/a	# maps strings to Parser objects.
1712	n/a	# (instantiated from the "parsers" global.)
1713	n/a	self.parsers = {}
1714	n/a	self.language = language
1715	n/a	if printer:
1716	n/a	fail("Custom printers are broken right now")
1717	n/a	self.printer = printer or BlockPrinter(language)
1718	n/a	self.verify = verify
1719	n/a	self.force = force
1720	n/a	self.filename = filename
1721	n/a	self.modules = collections.OrderedDict()
1722	n/a	self.classes = collections.OrderedDict()
1723	n/a	self.functions = []
1724	n/a
1725	n/a	self.line_prefix = self.line_suffix = ''
1726	n/a
1727	n/a	self.destinations = {}
1728	n/a	self.add_destination("block", "buffer")
1729	n/a	self.add_destination("suppress", "suppress")
1730	n/a	self.add_destination("buffer", "buffer")
1731	n/a	if filename:
1732	n/a	self.add_destination("file", "file", "{dirname}/clinic/{basename}.h")
1733	n/a
1734	n/a	d = self.get_destination_buffer
1735	n/a	self.destination_buffers = collections.OrderedDict((
1736	n/a	('cpp_if', d('file')),
1737	n/a	('docstring_prototype', d('suppress')),
1738	n/a	('docstring_definition', d('file')),
1739	n/a	('methoddef_define', d('file')),
1740	n/a	('impl_prototype', d('file')),
1741	n/a	('parser_prototype', d('suppress')),
1742	n/a	('parser_definition', d('file')),
1743	n/a	('cpp_endif', d('file')),
1744	n/a	('methoddef_ifndef', d('file', 1)),
1745	n/a	('impl_definition', d('block')),
1746	n/a	))
1747	n/a
1748	n/a	self.destination_buffers_stack = []
1749	n/a	self.ifndef_symbols = set()
1750	n/a
1751	n/a	self.presets = {}
1752	n/a	preset = None
1753	n/a	for line in self.presets_text.strip().split('\n'):
1754	n/a	line = line.strip()
1755	n/a	if not line:
1756	n/a	continue
1757	n/a	name, value, *options = line.split()
1758	n/a	if name == 'preset':
1759	n/a	self.presets[value] = preset = collections.OrderedDict()
1760	n/a	continue
1761	n/a
1762	n/a	if len(options):
1763	n/a	index = int(options[0])
1764	n/a	else:
1765	n/a	index = 0
1766	n/a	buffer = self.get_destination_buffer(value, index)
1767	n/a
1768	n/a	if name == 'everything':
1769	n/a	for name in self.destination_buffers:
1770	n/a	preset[name] = buffer
1771	n/a	continue
1772	n/a
1773	n/a	assert name in self.destination_buffers
1774	n/a	preset[name] = buffer
1775	n/a
1776	n/a	global clinic
1777	n/a	clinic = self
1778	n/a
1779	n/a	def add_destination(self, name, type, *args):
1780	n/a	if name in self.destinations:
1781	n/a	fail("Destination already exists: " + repr(name))
1782	n/a	self.destinations[name] = Destination(name, type, self, *args)
1783	n/a
1784	n/a	def get_destination(self, name):
1785	n/a	d = self.destinations.get(name)
1786	n/a	if not d:
1787	n/a	fail("Destination does not exist: " + repr(name))
1788	n/a	return d
1789	n/a
1790	n/a	def get_destination_buffer(self, name, item=0):
1791	n/a	d = self.get_destination(name)
1792	n/a	return d.buffers[item]
1793	n/a
1794	n/a	def parse(self, input):
1795	n/a	printer = self.printer
1796	n/a	self.block_parser = BlockParser(input, self.language, verify=self.verify)
1797	n/a	for block in self.block_parser:
1798	n/a	dsl_name = block.dsl_name
1799	n/a	if dsl_name:
1800	n/a	if dsl_name not in self.parsers:
1801	n/a	assert dsl_name in parsers, "No parser to handle {!r} block.".format(dsl_name)
1802	n/a	self.parsers[dsl_name] = parsers[dsl_name](self)
1803	n/a	parser = self.parsers[dsl_name]
1804	n/a	try:
1805	n/a	parser.parse(block)
1806	n/a	except Exception:
1807	n/a	fail('Exception raised during parsing:\n' +
1808	n/a	traceback.format_exc().rstrip())
1809	n/a	printer.print_block(block)
1810	n/a
1811	n/a	second_pass_replacements = {}
1812	n/a
1813	n/a	# these are destinations not buffers
1814	n/a	for name, destination in self.destinations.items():
1815	n/a	if destination.type == 'suppress':
1816	n/a	continue
1817	n/a	output = destination.dump()
1818	n/a
1819	n/a	if output:
1820	n/a
1821	n/a	block = Block("", dsl_name="clinic", output=output)
1822	n/a
1823	n/a	if destination.type == 'buffer':
1824	n/a	block.input = "dump " + name + "\n"
1825	n/a	warn("Destination buffer " + repr(name) + " not empty at end of file, emptying.")
1826	n/a	printer.write("\n")
1827	n/a	printer.print_block(block)
1828	n/a	continue
1829	n/a
1830	n/a	if destination.type == 'file':
1831	n/a	try:
1832	n/a	dirname = os.path.dirname(destination.filename)
1833	n/a	try:
1834	n/a	os.makedirs(dirname)
1835	n/a	except FileExistsError:
1836	n/a	if not os.path.isdir(dirname):
1837	n/a	fail("Can't write to destination {}, "
1838	n/a	"can't make directory {}!".format(
1839	n/a	destination.filename, dirname))
1840	n/a	if self.verify:
1841	n/a	with open(destination.filename, "rt") as f:
1842	n/a	parser_2 = BlockParser(f.read(), language=self.language)
1843	n/a	blocks = list(parser_2)
1844	n/a	if (len(blocks) != 1) or (blocks[0].input != 'preserve\n'):
1845	n/a	fail("Modified destination file " + repr(destination.filename) + ", not overwriting!")
1846	n/a	except FileNotFoundError:
1847	n/a	pass
1848	n/a
1849	n/a	block.input = 'preserve\n'
1850	n/a	printer_2 = BlockPrinter(self.language)
1851	n/a	printer_2.print_block(block)
1852	n/a	with open(destination.filename, "wt") as f:
1853	n/a	f.write(printer_2.f.getvalue())
1854	n/a	continue
1855	n/a	text = printer.f.getvalue()
1856	n/a
1857	n/a	if second_pass_replacements:
1858	n/a	printer_2 = BlockPrinter(self.language)
1859	n/a	parser_2 = BlockParser(text, self.language)
1860	n/a	changed = False
1861	n/a	for block in parser_2:
1862	n/a	if block.dsl_name:
1863	n/a	for id, replacement in second_pass_replacements.items():
1864	n/a	if id in block.output:
1865	n/a	changed = True
1866	n/a	block.output = block.output.replace(id, replacement)
1867	n/a	printer_2.print_block(block)
1868	n/a	if changed:
1869	n/a	text = printer_2.f.getvalue()
1870	n/a
1871	n/a	return text
1872	n/a
1873	n/a
1874	n/a	def _module_and_class(self, fields):
1875	n/a	"""
1876	n/a	fields should be an iterable of field names.
1877	n/a	returns a tuple of (module, class).
1878	n/a	the module object could actually be self (a clinic object).
1879	n/a	this function is only ever used to find the parent of where
1880	n/a	a new class/module should go.
1881	n/a	"""
1882	n/a	in_classes = False
1883	n/a	parent = module = self
1884	n/a	cls = None
1885	n/a	so_far = []
1886	n/a
1887	n/a	for field in fields:
1888	n/a	so_far.append(field)
1889	n/a	if not in_classes:
1890	n/a	child = parent.modules.get(field)
1891	n/a	if child:
1892	n/a	parent = module = child
1893	n/a	continue
1894	n/a	in_classes = True
1895	n/a	if not hasattr(parent, 'classes'):
1896	n/a	return module, cls
1897	n/a	child = parent.classes.get(field)
1898	n/a	if not child:
1899	n/a	fail('Parent class or module ' + '.'.join(so_far) + " does not exist.")
1900	n/a	cls = parent = child
1901	n/a
1902	n/a	return module, cls
1903	n/a
1904	n/a
1905	n/a	def parse_file(filename, *, force=False, verify=True, output=None, encoding='utf-8'):
1906	n/a	extension = os.path.splitext(filename)[1][1:]
1907	n/a	if not extension:
1908	n/a	fail("Can't extract file type for file " + repr(filename))
1909	n/a
1910	n/a	try:
1911	n/a	language = extensions[extension](filename)
1912	n/a	except KeyError:
1913	n/a	fail("Can't identify file type for file " + repr(filename))
1914	n/a
1915	n/a	with open(filename, 'r', encoding=encoding) as f:
1916	n/a	raw = f.read()
1917	n/a
1918	n/a	# exit quickly if there are no clinic markers in the file
1919	n/a	find_start_re = BlockParser("", language).find_start_re
1920	n/a	if not find_start_re.search(raw):
1921	n/a	return
1922	n/a
1923	n/a	clinic = Clinic(language, force=force, verify=verify, filename=filename)
1924	n/a	cooked = clinic.parse(raw)
1925	n/a	if (cooked == raw) and not force:
1926	n/a	return
1927	n/a
1928	n/a	directory = os.path.dirname(filename) or '.'
1929	n/a
1930	n/a	with tempfile.TemporaryDirectory(prefix="clinic", dir=directory) as tmpdir:
1931	n/a	bytes = cooked.encode(encoding)
1932	n/a	tmpfilename = os.path.join(tmpdir, os.path.basename(filename))
1933	n/a	with open(tmpfilename, "wb") as f:
1934	n/a	f.write(bytes)
1935	n/a	os.replace(tmpfilename, output or filename)
1936	n/a
1937	n/a
1938	n/a	def compute_checksum(input, length=None):
1939	n/a	input = input or ''
1940	n/a	s = hashlib.sha1(input.encode('utf-8')).hexdigest()
1941	n/a	if length:
1942	n/a	s = s[:length]
1943	n/a	return s
1944	n/a
1945	n/a
1946	n/a
1947	n/a
1948	n/a	class PythonParser:
1949	n/a	def __init__(self, clinic):
1950	n/a	pass
1951	n/a
1952	n/a	def parse(self, block):
1953	n/a	s = io.StringIO()
1954	n/a	with OverrideStdioWith(s):
1955	n/a	exec(block.input)
1956	n/a	block.output = s.getvalue()
1957	n/a
1958	n/a
1959	n/a	class Module:
1960	n/a	def __init__(self, name, module=None):
1961	n/a	self.name = name
1962	n/a	self.module = self.parent = module
1963	n/a
1964	n/a	self.modules = collections.OrderedDict()
1965	n/a	self.classes = collections.OrderedDict()
1966	n/a	self.functions = []
1967	n/a
1968	n/a	def __repr__(self):
1969	n/a	return "<clinic.Module " + repr(self.name) + " at " + str(id(self)) + ">"
1970	n/a
1971	n/a	class Class:
1972	n/a	def __init__(self, name, module=None, cls=None, typedef=None, type_object=None):
1973	n/a	self.name = name
1974	n/a	self.module = module
1975	n/a	self.cls = cls
1976	n/a	self.typedef = typedef
1977	n/a	self.type_object = type_object
1978	n/a	self.parent = cls or module
1979	n/a
1980	n/a	self.classes = collections.OrderedDict()
1981	n/a	self.functions = []
1982	n/a
1983	n/a	def __repr__(self):
1984	n/a	return "<clinic.Class " + repr(self.name) + " at " + str(id(self)) + ">"
1985	n/a
1986	n/a	unsupported_special_methods = set("""
1987	n/a
1988	n/a	__abs__
1989	n/a	__add__
1990	n/a	__and__
1991	n/a	__bytes__
1992	n/a	__call__
1993	n/a	__complex__
1994	n/a	__delitem__
1995	n/a	__divmod__
1996	n/a	__eq__
1997	n/a	__float__
1998	n/a	__floordiv__
1999	n/a	__ge__
2000	n/a	__getattr__
2001	n/a	__getattribute__
2002	n/a	__getitem__
2003	n/a	__gt__
2004	n/a	__hash__
2005	n/a	__iadd__
2006	n/a	__iand__
2007	n/a	__ifloordiv__
2008	n/a	__ilshift__
2009	n/a	__imatmul__
2010	n/a	__imod__
2011	n/a	__imul__
2012	n/a	__index__
2013	n/a	__int__
2014	n/a	__invert__
2015	n/a	__ior__
2016	n/a	__ipow__
2017	n/a	__irshift__
2018	n/a	__isub__
2019	n/a	__iter__
2020	n/a	__itruediv__
2021	n/a	__ixor__
2022	n/a	__le__
2023	n/a	__len__
2024	n/a	__lshift__
2025	n/a	__lt__
2026	n/a	__matmul__
2027	n/a	__mod__
2028	n/a	__mul__
2029	n/a	__neg__
2030	n/a	__new__
2031	n/a	__next__
2032	n/a	__or__
2033	n/a	__pos__
2034	n/a	__pow__
2035	n/a	__radd__
2036	n/a	__rand__
2037	n/a	__rdivmod__
2038	n/a	__repr__
2039	n/a	__rfloordiv__
2040	n/a	__rlshift__
2041	n/a	__rmatmul__
2042	n/a	__rmod__
2043	n/a	__rmul__
2044	n/a	__ror__
2045	n/a	__round__
2046	n/a	__rpow__
2047	n/a	__rrshift__
2048	n/a	__rshift__
2049	n/a	__rsub__
2050	n/a	__rtruediv__
2051	n/a	__rxor__
2052	n/a	__setattr__
2053	n/a	__setitem__
2054	n/a	__str__
2055	n/a	__sub__
2056	n/a	__truediv__
2057	n/a	__xor__
2058	n/a
2059	n/a	""".strip().split())
2060	n/a
2061	n/a
2062	n/a	INVALID, CALLABLE, STATIC_METHOD, CLASS_METHOD, METHOD_INIT, METHOD_NEW = """
2063	n/a	INVALID, CALLABLE, STATIC_METHOD, CLASS_METHOD, METHOD_INIT, METHOD_NEW
2064	n/a	""".replace(",", "").strip().split()
2065	n/a
2066	n/a	class Function:
2067	n/a	"""
2068	n/a	Mutable duck type for inspect.Function.
2069	n/a
2070	n/a	docstring - a str containing
2071	n/a	* embedded line breaks
2072	n/a	* text outdented to the left margin
2073	n/a	* no trailing whitespace.
2074	n/a	It will always be true that
2075	n/a	(not docstring) or ((not docstring[0].isspace()) and (docstring.rstrip() == docstring))
2076	n/a	"""
2077	n/a
2078	n/a	def __init__(self, parameters=None, *, name,
2079	n/a	module, cls=None, c_basename=None,
2080	n/a	full_name=None,
2081	n/a	return_converter, return_annotation=_empty,
2082	n/a	docstring=None, kind=CALLABLE, coexist=False,
2083	n/a	docstring_only=False):
2084	n/a	self.parameters = parameters or collections.OrderedDict()
2085	n/a	self.return_annotation = return_annotation
2086	n/a	self.name = name
2087	n/a	self.full_name = full_name
2088	n/a	self.module = module
2089	n/a	self.cls = cls
2090	n/a	self.parent = cls or module
2091	n/a	self.c_basename = c_basename
2092	n/a	self.return_converter = return_converter
2093	n/a	self.docstring = docstring or ''
2094	n/a	self.kind = kind
2095	n/a	self.coexist = coexist
2096	n/a	self.self_converter = None
2097	n/a	# docstring_only means "don't generate a machine-readable
2098	n/a	# signature, just a normal docstring". it's True for
2099	n/a	# functions with optional groups because we can't represent
2100	n/a	# those accurately with inspect.Signature in 3.4.
2101	n/a	self.docstring_only = docstring_only
2102	n/a
2103	n/a	self.rendered_parameters = None
2104	n/a
2105	n/a	__render_parameters__ = None
2106	n/a	@property
2107	n/a	def render_parameters(self):
2108	n/a	if not self.__render_parameters__:
2109	n/a	self.__render_parameters__ = l = []
2110	n/a	for p in self.parameters.values():
2111	n/a	p = p.copy()
2112	n/a	p.converter.pre_render()
2113	n/a	l.append(p)
2114	n/a	return self.__render_parameters__
2115	n/a
2116	n/a	@property
2117	n/a	def methoddef_flags(self):
2118	n/a	if self.kind in (METHOD_INIT, METHOD_NEW):
2119	n/a	return None
2120	n/a	flags = []
2121	n/a	if self.kind == CLASS_METHOD:
2122	n/a	flags.append('METH_CLASS')
2123	n/a	elif self.kind == STATIC_METHOD:
2124	n/a	flags.append('METH_STATIC')
2125	n/a	else:
2126	n/a	assert self.kind == CALLABLE, "unknown kind: " + repr(self.kind)
2127	n/a	if self.coexist:
2128	n/a	flags.append('METH_COEXIST')
2129	n/a	return '\|'.join(flags)
2130	n/a
2131	n/a	def __repr__(self):
2132	n/a	return '<clinic.Function ' + self.name + '>'
2133	n/a
2134	n/a	def copy(self, **overrides):
2135	n/a	kwargs = {
2136	n/a	'name': self.name, 'module': self.module, 'parameters': self.parameters,
2137	n/a	'cls': self.cls, 'c_basename': self.c_basename,
2138	n/a	'full_name': self.full_name,
2139	n/a	'return_converter': self.return_converter, 'return_annotation': self.return_annotation,
2140	n/a	'docstring': self.docstring, 'kind': self.kind, 'coexist': self.coexist,
2141	n/a	'docstring_only': self.docstring_only,
2142	n/a	}
2143	n/a	kwargs.update(overrides)
2144	n/a	f = Function(**kwargs)
2145	n/a
2146	n/a	parameters = collections.OrderedDict()
2147	n/a	for name, value in f.parameters.items():
2148	n/a	value = value.copy(function=f)
2149	n/a	parameters[name] = value
2150	n/a	f.parameters = parameters
2151	n/a	return f
2152	n/a
2153	n/a
2154	n/a	class Parameter:
2155	n/a	"""
2156	n/a	Mutable duck type of inspect.Parameter.
2157	n/a	"""
2158	n/a
2159	n/a	def __init__(self, name, kind, *, default=_empty,
2160	n/a	function, converter, annotation=_empty,
2161	n/a	docstring=None, group=0):
2162	n/a	self.name = name
2163	n/a	self.kind = kind
2164	n/a	self.default = default
2165	n/a	self.function = function
2166	n/a	self.converter = converter
2167	n/a	self.annotation = annotation
2168	n/a	self.docstring = docstring or ''
2169	n/a	self.group = group
2170	n/a
2171	n/a	def __repr__(self):
2172	n/a	return '<clinic.Parameter ' + self.name + '>'
2173	n/a
2174	n/a	def is_keyword_only(self):
2175	n/a	return self.kind == inspect.Parameter.KEYWORD_ONLY
2176	n/a
2177	n/a	def is_positional_only(self):
2178	n/a	return self.kind == inspect.Parameter.POSITIONAL_ONLY
2179	n/a
2180	n/a	def copy(self, **overrides):
2181	n/a	kwargs = {
2182	n/a	'name': self.name, 'kind': self.kind, 'default':self.default,
2183	n/a	'function': self.function, 'converter': self.converter, 'annotation': self.annotation,
2184	n/a	'docstring': self.docstring, 'group': self.group,
2185	n/a	}
2186	n/a	kwargs.update(overrides)
2187	n/a	if 'converter' not in overrides:
2188	n/a	converter = copy.copy(self.converter)
2189	n/a	converter.function = kwargs['function']
2190	n/a	kwargs['converter'] = converter
2191	n/a	return Parameter(**kwargs)
2192	n/a
2193	n/a
2194	n/a
2195	n/a	class LandMine:
2196	n/a	# try to access any
2197	n/a	def __init__(self, message):
2198	n/a	self.__message__ = message
2199	n/a
2200	n/a	def __repr__(self):
2201	n/a	return '<LandMine ' + repr(self.__message__) + ">"
2202	n/a
2203	n/a	def __getattribute__(self, name):
2204	n/a	if name in ('__repr__', '__message__'):
2205	n/a	return super().__getattribute__(name)
2206	n/a	# raise RuntimeError(repr(name))
2207	n/a	fail("Stepped on a land mine, trying to access attribute " + repr(name) + ":\n" + self.__message__)
2208	n/a
2209	n/a
2210	n/a	def add_c_converter(f, name=None):
2211	n/a	if not name:
2212	n/a	name = f.__name__
2213	n/a	if not name.endswith('_converter'):
2214	n/a	return f
2215	n/a	name = name[:-len('_converter')]
2216	n/a	converters[name] = f
2217	n/a	return f
2218	n/a
2219	n/a	def add_default_legacy_c_converter(cls):
2220	n/a	# automatically add converter for default format unit
2221	n/a	# (but without stomping on the existing one if it's already
2222	n/a	# set, in case you subclass)
2223	n/a	if ((cls.format_unit not in ('O&', '')) and
2224	n/a	(cls.format_unit not in legacy_converters)):
2225	n/a	legacy_converters[cls.format_unit] = cls
2226	n/a	return cls
2227	n/a
2228	n/a	def add_legacy_c_converter(format_unit, **kwargs):
2229	n/a	"""
2230	n/a	Adds a legacy converter.
2231	n/a	"""
2232	n/a	def closure(f):
2233	n/a	if not kwargs:
2234	n/a	added_f = f
2235	n/a	else:
2236	n/a	added_f = functools.partial(f, **kwargs)
2237	n/a	if format_unit:
2238	n/a	legacy_converters[format_unit] = added_f
2239	n/a	return f
2240	n/a	return closure
2241	n/a
2242	n/a	class CConverterAutoRegister(type):
2243	n/a	def __init__(cls, name, bases, classdict):
2244	n/a	add_c_converter(cls)
2245	n/a	add_default_legacy_c_converter(cls)
2246	n/a
2247	n/a	class CConverter(metaclass=CConverterAutoRegister):
2248	n/a	"""
2249	n/a	For the init function, self, name, function, and default
2250	n/a	must be keyword-or-positional parameters. All other
2251	n/a	parameters must be keyword-only.
2252	n/a	"""
2253	n/a
2254	n/a	# The C name to use for this variable.
2255	n/a	name = None
2256	n/a
2257	n/a	# The Python name to use for this variable.
2258	n/a	py_name = None
2259	n/a
2260	n/a	# The C type to use for this variable.
2261	n/a	# 'type' should be a Python string specifying the type, e.g. "int".
2262	n/a	# If this is a pointer type, the type string should end with ' *'.
2263	n/a	type = None
2264	n/a
2265	n/a	# The Python default value for this parameter, as a Python value.
2266	n/a	# Or the magic value "unspecified" if there is no default.
2267	n/a	# Or the magic value "unknown" if this value is a cannot be evaluated
2268	n/a	# at Argument-Clinic-preprocessing time (but is presumed to be valid
2269	n/a	# at runtime).
2270	n/a	default = unspecified
2271	n/a
2272	n/a	# If not None, default must be isinstance() of this type.
2273	n/a	# (You can also specify a tuple of types.)
2274	n/a	default_type = None
2275	n/a
2276	n/a	# "default" converted into a C value, as a string.
2277	n/a	# Or None if there is no default.
2278	n/a	c_default = None
2279	n/a
2280	n/a	# "default" converted into a Python value, as a string.
2281	n/a	# Or None if there is no default.
2282	n/a	py_default = None
2283	n/a
2284	n/a	# The default value used to initialize the C variable when
2285	n/a	# there is no default, but not specifying a default may
2286	n/a	# result in an "uninitialized variable" warning. This can
2287	n/a	# easily happen when using option groups--although
2288	n/a	# properly-written code won't actually use the variable,
2289	n/a	# the variable does get passed in to the _impl. (Ah, if
2290	n/a	# only dataflow analysis could inline the static function!)
2291	n/a	#
2292	n/a	# This value is specified as a string.
2293	n/a	# Every non-abstract subclass should supply a valid value.
2294	n/a	c_ignored_default = 'NULL'
2295	n/a
2296	n/a	# The C converter function to be used, if any.
2297	n/a	# (If this is not None, format_unit must be 'O&'.)
2298	n/a	converter = None
2299	n/a
2300	n/a	# Should Argument Clinic add a '&' before the name of
2301	n/a	# the variable when passing it into the _impl function?
2302	n/a	impl_by_reference = False
2303	n/a
2304	n/a	# Should Argument Clinic add a '&' before the name of
2305	n/a	# the variable when passing it into PyArg_ParseTuple (AndKeywords)?
2306	n/a	parse_by_reference = True
2307	n/a
2308	n/a	#############################################################
2309	n/a	#############################################################
2310	n/a	## You shouldn't need to read anything below this point to ##
2311	n/a	## write your own converter functions. ##
2312	n/a	#############################################################
2313	n/a	#############################################################
2314	n/a
2315	n/a	# The "format unit" to specify for this variable when
2316	n/a	# parsing arguments using PyArg_ParseTuple (AndKeywords).
2317	n/a	# Custom converters should always use the default value of 'O&'.
2318	n/a	format_unit = 'O&'
2319	n/a
2320	n/a	# What encoding do we want for this variable? Only used
2321	n/a	# by format units starting with 'e'.
2322	n/a	encoding = None
2323	n/a
2324	n/a	# Should this object be required to be a subclass of a specific type?
2325	n/a	# If not None, should be a string representing a pointer to a
2326	n/a	# PyTypeObject (e.g. "&PyUnicode_Type").
2327	n/a	# Only used by the 'O!' format unit (and the "object" converter).
2328	n/a	subclass_of = None
2329	n/a
2330	n/a	# Do we want an adjacent '_length' variable for this variable?
2331	n/a	# Only used by format units ending with '#'.
2332	n/a	length = False
2333	n/a
2334	n/a	# Should we show this parameter in the generated
2335	n/a	# __text_signature__? This is almost always True.
2336	n/a	# (It's only False for __new__, __init__, and METH_STATIC functions.)
2337	n/a	show_in_signature = True
2338	n/a
2339	n/a	# Overrides the name used in a text signature.
2340	n/a	# The name used for a "self" parameter must be one of
2341	n/a	# self, type, or module; however users can set their own.
2342	n/a	# This lets the self_converter overrule the user-settable
2343	n/a	# name, just for the text signature.
2344	n/a	# Only set by self_converter.
2345	n/a	signature_name = None
2346	n/a
2347	n/a	# keep in sync with self_converter.__init__!
2348	n/a	def __init__(self, name, py_name, function, default=unspecified, , c_default=None, py_default=None, annotation=unspecified, *kwargs):
2349	n/a	self.name = name
2350	n/a	self.py_name = py_name
2351	n/a
2352	n/a	if default is not unspecified:
2353	n/a	if self.default_type and not isinstance(default, (self.default_type, Unknown)):
2354	n/a	if isinstance(self.default_type, type):
2355	n/a	types_str = self.default_type.__name__
2356	n/a	else:
2357	n/a	types_str = ', '.join((cls.__name__ for cls in self.default_type))
2358	n/a	fail("{}: default value {!r} for field {} is not of type {}".format(
2359	n/a	self.__class__.__name__, default, name, types_str))
2360	n/a	self.default = default
2361	n/a
2362	n/a	if c_default:
2363	n/a	self.c_default = c_default
2364	n/a	if py_default:
2365	n/a	self.py_default = py_default
2366	n/a
2367	n/a	if annotation != unspecified:
2368	n/a	fail("The 'annotation' parameter is not currently permitted.")
2369	n/a
2370	n/a	# this is deliberate, to prevent you from caching information
2371	n/a	# about the function in the init.
2372	n/a	# (that breaks if we get cloned.)
2373	n/a	# so after this change we will noisily fail.
2374	n/a	self.function = LandMine("Don't access members of self.function inside converter_init!")
2375	n/a	self.converter_init(**kwargs)
2376	n/a	self.function = function
2377	n/a
2378	n/a	def converter_init(self):
2379	n/a	pass
2380	n/a
2381	n/a	def is_optional(self):
2382	n/a	return (self.default is not unspecified)
2383	n/a
2384	n/a	def _render_self(self, parameter, data):
2385	n/a	self.parameter = parameter
2386	n/a	original_name = self.name
2387	n/a	name = ensure_legal_c_identifier(original_name)
2388	n/a
2389	n/a	# impl_arguments
2390	n/a	s = ("&" if self.impl_by_reference else "") + name
2391	n/a	data.impl_arguments.append(s)
2392	n/a	if self.length:
2393	n/a	data.impl_arguments.append(self.length_name())
2394	n/a
2395	n/a	# impl_parameters
2396	n/a	data.impl_parameters.append(self.simple_declaration(by_reference=self.impl_by_reference))
2397	n/a	if self.length:
2398	n/a	data.impl_parameters.append("Py_ssize_clean_t " + self.length_name())
2399	n/a
2400	n/a	def _render_non_self(self, parameter, data):
2401	n/a	self.parameter = parameter
2402	n/a	original_name = self.name
2403	n/a	name = ensure_legal_c_identifier(original_name)
2404	n/a
2405	n/a	# declarations
2406	n/a	d = self.declaration()
2407	n/a	data.declarations.append(d)
2408	n/a
2409	n/a	# initializers
2410	n/a	initializers = self.initialize()
2411	n/a	if initializers:
2412	n/a	data.initializers.append('/* initializers for ' + name + ' */\n' + initializers.rstrip())
2413	n/a
2414	n/a	# modifications
2415	n/a	modifications = self.modify()
2416	n/a	if modifications:
2417	n/a	data.modifications.append('/* modifications for ' + name + ' */\n' + modifications.rstrip())
2418	n/a
2419	n/a	# keywords
2420	n/a	if parameter.is_positional_only():
2421	n/a	data.keywords.append('')
2422	n/a	else:
2423	n/a	data.keywords.append(parameter.name)
2424	n/a
2425	n/a	# format_units
2426	n/a	if self.is_optional() and '\|' not in data.format_units:
2427	n/a	data.format_units.append('\|')
2428	n/a	if parameter.is_keyword_only() and '$' not in data.format_units:
2429	n/a	data.format_units.append('$')
2430	n/a	data.format_units.append(self.format_unit)
2431	n/a
2432	n/a	# parse_arguments
2433	n/a	self.parse_argument(data.parse_arguments)
2434	n/a
2435	n/a	# cleanup
2436	n/a	cleanup = self.cleanup()
2437	n/a	if cleanup:
2438	n/a	data.cleanup.append('/* Cleanup for ' + name + ' */\n' + cleanup.rstrip() + "\n")
2439	n/a
2440	n/a	def render(self, parameter, data):
2441	n/a	"""
2442	n/a	parameter is a clinic.Parameter instance.
2443	n/a	data is a CRenderData instance.
2444	n/a	"""
2445	n/a	self._render_self(parameter, data)
2446	n/a	self._render_non_self(parameter, data)
2447	n/a
2448	n/a	def length_name(self):
2449	n/a	"""Computes the name of the associated "length" variable."""
2450	n/a	if not self.length:
2451	n/a	return None
2452	n/a	return ensure_legal_c_identifier(self.name) + "_length"
2453	n/a
2454	n/a	# Why is this one broken out separately?
2455	n/a	# For "positional-only" function parsing,
2456	n/a	# which generates a bunch of PyArg_ParseTuple calls.
2457	n/a	def parse_argument(self, list):
2458	n/a	assert not (self.converter and self.encoding)
2459	n/a	if self.format_unit == 'O&':
2460	n/a	assert self.converter
2461	n/a	list.append(self.converter)
2462	n/a
2463	n/a	if self.encoding:
2464	n/a	list.append(c_repr(self.encoding))
2465	n/a	elif self.subclass_of:
2466	n/a	list.append(self.subclass_of)
2467	n/a
2468	n/a	legal_name = ensure_legal_c_identifier(self.name)
2469	n/a	s = ("&" if self.parse_by_reference else "") + legal_name
2470	n/a	list.append(s)
2471	n/a
2472	n/a	if self.length:
2473	n/a	list.append("&" + self.length_name())
2474	n/a
2475	n/a	#
2476	n/a	# All the functions after here are intended as extension points.
2477	n/a	#
2478	n/a
2479	n/a	def simple_declaration(self, by_reference=False):
2480	n/a	"""
2481	n/a	Computes the basic declaration of the variable.
2482	n/a	Used in computing the prototype declaration and the
2483	n/a	variable declaration.
2484	n/a	"""
2485	n/a	prototype = [self.type]
2486	n/a	if by_reference or not self.type.endswith('*'):
2487	n/a	prototype.append(" ")
2488	n/a	if by_reference:
2489	n/a	prototype.append('*')
2490	n/a	prototype.append(ensure_legal_c_identifier(self.name))
2491	n/a	return "".join(prototype)
2492	n/a
2493	n/a	def declaration(self):
2494	n/a	"""
2495	n/a	The C statement to declare this variable.
2496	n/a	"""
2497	n/a	declaration = [self.simple_declaration()]
2498	n/a	default = self.c_default
2499	n/a	if not default and self.parameter.group:
2500	n/a	default = self.c_ignored_default
2501	n/a	if default:
2502	n/a	declaration.append(" = ")
2503	n/a	declaration.append(default)
2504	n/a	declaration.append(";")
2505	n/a	if self.length:
2506	n/a	declaration.append('\nPy_ssize_clean_t ')
2507	n/a	declaration.append(self.length_name())
2508	n/a	declaration.append(';')
2509	n/a	return "".join(declaration)
2510	n/a
2511	n/a	def initialize(self):
2512	n/a	"""
2513	n/a	The C statements required to set up this variable before parsing.
2514	n/a	Returns a string containing this code indented at column 0.
2515	n/a	If no initialization is necessary, returns an empty string.
2516	n/a	"""
2517	n/a	return ""
2518	n/a
2519	n/a	def modify(self):
2520	n/a	"""
2521	n/a	The C statements required to modify this variable after parsing.
2522	n/a	Returns a string containing this code indented at column 0.
2523	n/a	If no initialization is necessary, returns an empty string.
2524	n/a	"""
2525	n/a	return ""
2526	n/a
2527	n/a	def cleanup(self):
2528	n/a	"""
2529	n/a	The C statements required to clean up after this variable.
2530	n/a	Returns a string containing this code indented at column 0.
2531	n/a	If no cleanup is necessary, returns an empty string.
2532	n/a	"""
2533	n/a	return ""
2534	n/a
2535	n/a	def pre_render(self):
2536	n/a	"""
2537	n/a	A second initialization function, like converter_init,
2538	n/a	called just before rendering.
2539	n/a	You are permitted to examine self.function here.
2540	n/a	"""
2541	n/a	pass
2542	n/a
2543	n/a
2544	n/a	class bool_converter(CConverter):
2545	n/a	type = 'int'
2546	n/a	default_type = bool
2547	n/a	format_unit = 'p'
2548	n/a	c_ignored_default = '0'
2549	n/a
2550	n/a	def converter_init(self):
2551	n/a	if self.default is not unspecified:
2552	n/a	self.default = bool(self.default)
2553	n/a	self.c_default = str(int(self.default))
2554	n/a
2555	n/a	class char_converter(CConverter):
2556	n/a	type = 'char'
2557	n/a	default_type = (bytes, bytearray)
2558	n/a	format_unit = 'c'
2559	n/a	c_ignored_default = "'\0'"
2560	n/a
2561	n/a	def converter_init(self):
2562	n/a	if isinstance(self.default, self.default_type) and (len(self.default) != 1):
2563	n/a	fail("char_converter: illegal default value " + repr(self.default))
2564	n/a
2565	n/a
2566	n/a	@add_legacy_c_converter('B', bitwise=True)
2567	n/a	class unsigned_char_converter(CConverter):
2568	n/a	type = 'unsigned char'
2569	n/a	default_type = int
2570	n/a	format_unit = 'b'
2571	n/a	c_ignored_default = "'\0'"
2572	n/a
2573	n/a	def converter_init(self, *, bitwise=False):
2574	n/a	if bitwise:
2575	n/a	self.format_unit = 'B'
2576	n/a
2577	n/a	class byte_converter(unsigned_char_converter): pass
2578	n/a
2579	n/a	class short_converter(CConverter):
2580	n/a	type = 'short'
2581	n/a	default_type = int
2582	n/a	format_unit = 'h'
2583	n/a	c_ignored_default = "0"
2584	n/a
2585	n/a	class unsigned_short_converter(CConverter):
2586	n/a	type = 'unsigned short'
2587	n/a	default_type = int
2588	n/a	format_unit = 'H'
2589	n/a	c_ignored_default = "0"
2590	n/a
2591	n/a	def converter_init(self, *, bitwise=False):
2592	n/a	if not bitwise:
2593	n/a	fail("Unsigned shorts must be bitwise (for now).")
2594	n/a
2595	n/a	@add_legacy_c_converter('C', accept={str})
2596	n/a	class int_converter(CConverter):
2597	n/a	type = 'int'
2598	n/a	default_type = int
2599	n/a	format_unit = 'i'
2600	n/a	c_ignored_default = "0"
2601	n/a
2602	n/a	def converter_init(self, *, accept={int}, type=None):
2603	n/a	if accept == {str}:
2604	n/a	self.format_unit = 'C'
2605	n/a	elif accept != {int}:
2606	n/a	fail("int_converter: illegal 'accept' argument " + repr(accept))
2607	n/a	if type != None:
2608	n/a	self.type = type
2609	n/a
2610	n/a	class unsigned_int_converter(CConverter):
2611	n/a	type = 'unsigned int'
2612	n/a	default_type = int
2613	n/a	format_unit = 'I'
2614	n/a	c_ignored_default = "0"
2615	n/a
2616	n/a	def converter_init(self, *, bitwise=False):
2617	n/a	if not bitwise:
2618	n/a	fail("Unsigned ints must be bitwise (for now).")
2619	n/a
2620	n/a	class long_converter(CConverter):
2621	n/a	type = 'long'
2622	n/a	default_type = int
2623	n/a	format_unit = 'l'
2624	n/a	c_ignored_default = "0"
2625	n/a
2626	n/a	class unsigned_long_converter(CConverter):
2627	n/a	type = 'unsigned long'
2628	n/a	default_type = int
2629	n/a	format_unit = 'k'
2630	n/a	c_ignored_default = "0"
2631	n/a
2632	n/a	def converter_init(self, *, bitwise=False):
2633	n/a	if not bitwise:
2634	n/a	fail("Unsigned longs must be bitwise (for now).")
2635	n/a
2636	n/a	class long_long_converter(CConverter):
2637	n/a	type = 'long long'
2638	n/a	default_type = int
2639	n/a	format_unit = 'L'
2640	n/a	c_ignored_default = "0"
2641	n/a
2642	n/a	class unsigned_long_long_converter(CConverter):
2643	n/a	type = 'unsigned long long'
2644	n/a	default_type = int
2645	n/a	format_unit = 'K'
2646	n/a	c_ignored_default = "0"
2647	n/a
2648	n/a	def converter_init(self, *, bitwise=False):
2649	n/a	if not bitwise:
2650	n/a	fail("Unsigned long long must be bitwise (for now).")
2651	n/a
2652	n/a	class Py_ssize_t_converter(CConverter):
2653	n/a	type = 'Py_ssize_t'
2654	n/a	default_type = int
2655	n/a	format_unit = 'n'
2656	n/a	c_ignored_default = "0"
2657	n/a
2658	n/a
2659	n/a	class float_converter(CConverter):
2660	n/a	type = 'float'
2661	n/a	default_type = float
2662	n/a	format_unit = 'f'
2663	n/a	c_ignored_default = "0.0"
2664	n/a
2665	n/a	class double_converter(CConverter):
2666	n/a	type = 'double'
2667	n/a	default_type = float
2668	n/a	format_unit = 'd'
2669	n/a	c_ignored_default = "0.0"
2670	n/a
2671	n/a
2672	n/a	class Py_complex_converter(CConverter):
2673	n/a	type = 'Py_complex'
2674	n/a	default_type = complex
2675	n/a	format_unit = 'D'
2676	n/a	c_ignored_default = "{0.0, 0.0}"
2677	n/a
2678	n/a
2679	n/a	class object_converter(CConverter):
2680	n/a	type = 'PyObject *'
2681	n/a	format_unit = 'O'
2682	n/a
2683	n/a	def converter_init(self, *, converter=None, type=None, subclass_of=None):
2684	n/a	if converter:
2685	n/a	if subclass_of:
2686	n/a	fail("object: Cannot pass in both 'converter' and 'subclass_of'")
2687	n/a	self.format_unit = 'O&'
2688	n/a	self.converter = converter
2689	n/a	elif subclass_of:
2690	n/a	self.format_unit = 'O!'
2691	n/a	self.subclass_of = subclass_of
2692	n/a
2693	n/a	if type is not None:
2694	n/a	self.type = type
2695	n/a
2696	n/a
2697	n/a	#
2698	n/a	# We define three conventions for buffer types in the 'accept' argument:
2699	n/a	#
2700	n/a	# buffer : any object supporting the buffer interface
2701	n/a	# rwbuffer: any object supporting the buffer interface, but must be writeable
2702	n/a	# robuffer: any object supporting the buffer interface, but must not be writeable
2703	n/a	#
2704	n/a
2705	n/a	class buffer: pass
2706	n/a	class rwbuffer: pass
2707	n/a	class robuffer: pass
2708	n/a
2709	n/a	def str_converter_key(types, encoding, zeroes):
2710	n/a	return (frozenset(types), bool(encoding), bool(zeroes))
2711	n/a
2712	n/a	str_converter_argument_map = {}
2713	n/a
2714	n/a	class str_converter(CConverter):
2715	n/a	type = 'const char *'
2716	n/a	default_type = (str, Null, NoneType)
2717	n/a	format_unit = 's'
2718	n/a
2719	n/a	def converter_init(self, *, accept={str}, encoding=None, zeroes=False):
2720	n/a
2721	n/a	key = str_converter_key(accept, encoding, zeroes)
2722	n/a	format_unit = str_converter_argument_map.get(key)
2723	n/a	if not format_unit:
2724	n/a	fail("str_converter: illegal combination of arguments", key)
2725	n/a
2726	n/a	self.format_unit = format_unit
2727	n/a	self.length = bool(zeroes)
2728	n/a	if encoding:
2729	n/a	if self.default not in (Null, None, unspecified):
2730	n/a	fail("str_converter: Argument Clinic doesn't support default values for encoded strings")
2731	n/a	self.encoding = encoding
2732	n/a	self.type = 'char *'
2733	n/a	# sorry, clinic can't support preallocated buffers
2734	n/a	# for es# and et#
2735	n/a	self.c_default = "NULL"
2736	n/a
2737	n/a	def cleanup(self):
2738	n/a	if self.encoding:
2739	n/a	name = ensure_legal_c_identifier(self.name)
2740	n/a	return "".join(["if (", name, ") {\n PyMem_FREE(", name, ");\n}\n"])
2741	n/a
2742	n/a	#
2743	n/a	# This is the fourth or fifth rewrite of registering all the
2744	n/a	# crazy string converter format units. Previous approaches hid
2745	n/a	# bugs--generally mismatches between the semantics of the format
2746	n/a	# unit and the arguments necessary to represent those semantics
2747	n/a	# properly. Hopefully with this approach we'll get it 100% right.
2748	n/a	#
2749	n/a	# The r() function (short for "register") both registers the
2750	n/a	# mapping from arguments to format unit and registers the
2751	n/a	# legacy C converter for that format unit.
2752	n/a	#
2753	n/a	def r(format_unit, *, accept, encoding=False, zeroes=False):
2754	n/a	if not encoding and format_unit != 's':
2755	n/a	# add the legacy c converters here too.
2756	n/a	#
2757	n/a	# note: add_legacy_c_converter can't work for
2758	n/a	# es, es#, et, or et#
2759	n/a	# because of their extra encoding argument
2760	n/a	#
2761	n/a	# also don't add the converter for 's' because
2762	n/a	# the metaclass for CConverter adds it for us.
2763	n/a	kwargs = {}
2764	n/a	if accept != {str}:
2765	n/a	kwargs['accept'] = accept
2766	n/a	if zeroes:
2767	n/a	kwargs['zeroes'] = True
2768	n/a	added_f = functools.partial(str_converter, **kwargs)
2769	n/a	legacy_converters[format_unit] = added_f
2770	n/a
2771	n/a	d = str_converter_argument_map
2772	n/a	key = str_converter_key(accept, encoding, zeroes)
2773	n/a	if key in d:
2774	n/a	sys.exit("Duplicate keys specified for str_converter_argument_map!")
2775	n/a	d[key] = format_unit
2776	n/a
2777	n/a	r('es', encoding=True, accept={str})
2778	n/a	r('es#', encoding=True, zeroes=True, accept={str})
2779	n/a	r('et', encoding=True, accept={bytes, bytearray, str})
2780	n/a	r('et#', encoding=True, zeroes=True, accept={bytes, bytearray, str})
2781	n/a	r('s', accept={str})
2782	n/a	r('s#', zeroes=True, accept={robuffer, str})
2783	n/a	r('y', accept={robuffer})
2784	n/a	r('y#', zeroes=True, accept={robuffer})
2785	n/a	r('z', accept={str, NoneType})
2786	n/a	r('z#', zeroes=True, accept={robuffer, str, NoneType})
2787	n/a	del r
2788	n/a
2789	n/a
2790	n/a	class PyBytesObject_converter(CConverter):
2791	n/a	type = 'PyBytesObject *'
2792	n/a	format_unit = 'S'
2793	n/a	# accept = {bytes}
2794	n/a
2795	n/a	class PyByteArrayObject_converter(CConverter):
2796	n/a	type = 'PyByteArrayObject *'
2797	n/a	format_unit = 'Y'
2798	n/a	# accept = {bytearray}
2799	n/a
2800	n/a	class unicode_converter(CConverter):
2801	n/a	type = 'PyObject *'
2802	n/a	default_type = (str, Null, NoneType)
2803	n/a	format_unit = 'U'
2804	n/a
2805	n/a	@add_legacy_c_converter('u#', zeroes=True)
2806	n/a	@add_legacy_c_converter('Z', accept={str, NoneType})
2807	n/a	@add_legacy_c_converter('Z#', accept={str, NoneType}, zeroes=True)
2808	n/a	class Py_UNICODE_converter(CConverter):
2809	n/a	type = 'Py_UNICODE *'
2810	n/a	default_type = (str, Null, NoneType)
2811	n/a	format_unit = 'u'
2812	n/a
2813	n/a	def converter_init(self, *, accept={str}, zeroes=False):
2814	n/a	format_unit = 'Z' if accept=={str, NoneType} else 'u'
2815	n/a	if zeroes:
2816	n/a	format_unit += '#'
2817	n/a	self.length = True
2818	n/a	self.format_unit = format_unit
2819	n/a
2820	n/a	@add_legacy_c_converter('s*', accept={str, buffer})
2821	n/a	@add_legacy_c_converter('z*', accept={str, buffer, NoneType})
2822	n/a	@add_legacy_c_converter('w*', accept={rwbuffer})
2823	n/a	class Py_buffer_converter(CConverter):
2824	n/a	type = 'Py_buffer'
2825	n/a	format_unit = 'y*'
2826	n/a	impl_by_reference = True
2827	n/a	c_ignored_default = "{NULL, NULL}"
2828	n/a
2829	n/a	def converter_init(self, *, accept={buffer}):
2830	n/a	if self.default not in (unspecified, None):
2831	n/a	fail("The only legal default value for Py_buffer is None.")
2832	n/a
2833	n/a	self.c_default = self.c_ignored_default
2834	n/a
2835	n/a	if accept == {str, buffer, NoneType}:
2836	n/a	format_unit = 'z*'
2837	n/a	elif accept == {str, buffer}:
2838	n/a	format_unit = 's*'
2839	n/a	elif accept == {buffer}:
2840	n/a	format_unit = 'y*'
2841	n/a	elif accept == {rwbuffer}:
2842	n/a	format_unit = 'w*'
2843	n/a	else:
2844	n/a	fail("Py_buffer_converter: illegal combination of arguments")
2845	n/a
2846	n/a	self.format_unit = format_unit
2847	n/a
2848	n/a	def cleanup(self):
2849	n/a	name = ensure_legal_c_identifier(self.name)
2850	n/a	return "".join(["if (", name, ".obj) {\n PyBuffer_Release(&", name, ");\n}\n"])
2851	n/a
2852	n/a
2853	n/a	def correct_name_for_self(f):
2854	n/a	if f.kind in (CALLABLE, METHOD_INIT):
2855	n/a	if f.cls:
2856	n/a	return "PyObject *", "self"
2857	n/a	return "PyObject *", "module"
2858	n/a	if f.kind == STATIC_METHOD:
2859	n/a	return "void *", "null"
2860	n/a	if f.kind in (CLASS_METHOD, METHOD_NEW):
2861	n/a	return "PyTypeObject *", "type"
2862	n/a	raise RuntimeError("Unhandled type of function f: " + repr(f.kind))
2863	n/a
2864	n/a	def required_type_for_self_for_parser(f):
2865	n/a	type, _ = correct_name_for_self(f)
2866	n/a	if f.kind in (METHOD_INIT, METHOD_NEW, STATIC_METHOD, CLASS_METHOD):
2867	n/a	return type
2868	n/a	return None
2869	n/a
2870	n/a
2871	n/a	class self_converter(CConverter):
2872	n/a	"""
2873	n/a	A special-case converter:
2874	n/a	this is the default converter used for "self".
2875	n/a	"""
2876	n/a	type = None
2877	n/a	format_unit = ''
2878	n/a
2879	n/a	def converter_init(self, *, type=None):
2880	n/a	self.specified_type = type
2881	n/a
2882	n/a	def pre_render(self):
2883	n/a	f = self.function
2884	n/a	default_type, default_name = correct_name_for_self(f)
2885	n/a	self.signature_name = default_name
2886	n/a	self.type = self.specified_type or self.type or default_type
2887	n/a
2888	n/a	kind = self.function.kind
2889	n/a	new_or_init = kind in (METHOD_NEW, METHOD_INIT)
2890	n/a
2891	n/a	if (kind == STATIC_METHOD) or new_or_init:
2892	n/a	self.show_in_signature = False
2893	n/a
2894	n/a	# tp_new (METHOD_NEW) functions are of type newfunc:
2895	n/a	# typedef PyObject (newfunc)(struct _typeobject , PyObject , PyObject *);
2896	n/a	# PyTypeObject is a typedef for struct _typeobject.
2897	n/a	#
2898	n/a	# tp_init (METHOD_INIT) functions are of type initproc:
2899	n/a	# typedef int (initproc)(PyObject , PyObject , PyObject );
2900	n/a	#
2901	n/a	# All other functions generated by Argument Clinic are stored in
2902	n/a	# PyMethodDef structures, in the ml_meth slot, which is of type PyCFunction:
2903	n/a	# typedef PyObject (PyCFunction)(PyObject , PyObject );
2904	n/a	# However! We habitually cast these functions to PyCFunction,
2905	n/a	# since functions that accept keyword arguments don't fit this signature
2906	n/a	# but are stored there anyway. So strict type equality isn't important
2907	n/a	# for these functions.
2908	n/a	#
2909	n/a	# So:
2910	n/a	#
2911	n/a	# * The name of the first parameter to the impl and the parsing function will always
2912	n/a	# be self.name.
2913	n/a	#
2914	n/a	# * The type of the first parameter to the impl will always be of self.type.
2915	n/a	#
2916	n/a	# * If the function is neither tp_new (METHOD_NEW) nor tp_init (METHOD_INIT):
2917	n/a	# * The type of the first parameter to the parsing function is also self.type.
2918	n/a	# This means that if you step into the parsing function, your "self" parameter
2919	n/a	# is of the correct type, which may make debugging more pleasant.
2920	n/a	#
2921	n/a	# * Else if the function is tp_new (METHOD_NEW):
2922	n/a	# * The type of the first parameter to the parsing function is "PyTypeObject *",
2923	n/a	# so the type signature of the function call is an exact match.
2924	n/a	# * If self.type != "PyTypeObject *", we cast the first parameter to self.type
2925	n/a	# in the impl call.
2926	n/a	#
2927	n/a	# * Else if the function is tp_init (METHOD_INIT):
2928	n/a	# * The type of the first parameter to the parsing function is "PyObject *",
2929	n/a	# so the type signature of the function call is an exact match.
2930	n/a	# * If self.type != "PyObject *", we cast the first parameter to self.type
2931	n/a	# in the impl call.
2932	n/a
2933	n/a	@property
2934	n/a	def parser_type(self):
2935	n/a	return required_type_for_self_for_parser(self.function) or self.type
2936	n/a
2937	n/a	def render(self, parameter, data):
2938	n/a	"""
2939	n/a	parameter is a clinic.Parameter instance.
2940	n/a	data is a CRenderData instance.
2941	n/a	"""
2942	n/a	if self.function.kind == STATIC_METHOD:
2943	n/a	return
2944	n/a
2945	n/a	self._render_self(parameter, data)
2946	n/a
2947	n/a	if self.type != self.parser_type:
2948	n/a	# insert cast to impl_argument[0], aka self.
2949	n/a	# we know we're in the first slot in all the CRenderData lists,
2950	n/a	# because we render parameters in order, and self is always first.
2951	n/a	assert len(data.impl_arguments) == 1
2952	n/a	assert data.impl_arguments[0] == self.name
2953	n/a	data.impl_arguments[0] = '(' + self.type + ")" + data.impl_arguments[0]
2954	n/a
2955	n/a	def set_template_dict(self, template_dict):
2956	n/a	template_dict['self_name'] = self.name
2957	n/a	template_dict['self_type'] = self.parser_type
2958	n/a	kind = self.function.kind
2959	n/a	cls = self.function.cls
2960	n/a
2961	n/a	if ((kind in (METHOD_NEW, METHOD_INIT)) and cls and cls.typedef):
2962	n/a	if kind == METHOD_NEW:
2963	n/a	passed_in_type = self.name
2964	n/a	else:
2965	n/a	passed_in_type = 'Py_TYPE({})'.format(self.name)
2966	n/a
2967	n/a	line = '({passed_in_type} == {type_object}) &&\n '
2968	n/a	d = {
2969	n/a	'type_object': self.function.cls.type_object,
2970	n/a	'passed_in_type': passed_in_type
2971	n/a	}
2972	n/a	template_dict['self_type_check'] = line.format_map(d)
2973	n/a
2974	n/a
2975	n/a
2976	n/a	def add_c_return_converter(f, name=None):
2977	n/a	if not name:
2978	n/a	name = f.__name__
2979	n/a	if not name.endswith('_return_converter'):
2980	n/a	return f
2981	n/a	name = name[:-len('_return_converter')]
2982	n/a	return_converters[name] = f
2983	n/a	return f
2984	n/a
2985	n/a
2986	n/a	class CReturnConverterAutoRegister(type):
2987	n/a	def __init__(cls, name, bases, classdict):
2988	n/a	add_c_return_converter(cls)
2989	n/a
2990	n/a	class CReturnConverter(metaclass=CReturnConverterAutoRegister):
2991	n/a
2992	n/a	# The C type to use for this variable.
2993	n/a	# 'type' should be a Python string specifying the type, e.g. "int".
2994	n/a	# If this is a pointer type, the type string should end with ' *'.
2995	n/a	type = 'PyObject *'
2996	n/a
2997	n/a	# The Python default value for this parameter, as a Python value.
2998	n/a	# Or the magic value "unspecified" if there is no default.
2999	n/a	default = None
3000	n/a
3001	n/a	def __init__(self, , py_default=None, *kwargs):
3002	n/a	self.py_default = py_default
3003	n/a	try:
3004	n/a	self.return_converter_init(**kwargs)
3005	n/a	except TypeError as e:
3006	n/a	s = ', '.join(name + '=' + repr(value) for name, value in kwargs.items())
3007	n/a	sys.exit(self.__class__.__name__ + '(' + s + ')\n' + str(e))
3008	n/a
3009	n/a	def return_converter_init(self):
3010	n/a	pass
3011	n/a
3012	n/a	def declare(self, data, name="_return_value"):
3013	n/a	line = []
3014	n/a	add = line.append
3015	n/a	add(self.type)
3016	n/a	if not self.type.endswith('*'):
3017	n/a	add(' ')
3018	n/a	add(name + ';')
3019	n/a	data.declarations.append(''.join(line))
3020	n/a	data.return_value = name
3021	n/a
3022	n/a	def err_occurred_if(self, expr, data):
3023	n/a	data.return_conversion.append('if (({}) && PyErr_Occurred()) {{\n goto exit;\n}}\n'.format(expr))
3024	n/a
3025	n/a	def err_occurred_if_null_pointer(self, variable, data):
3026	n/a	data.return_conversion.append('if ({} == NULL) {{\n goto exit;\n}}\n'.format(variable))
3027	n/a
3028	n/a	def render(self, function, data):
3029	n/a	"""
3030	n/a	function is a clinic.Function instance.
3031	n/a	data is a CRenderData instance.
3032	n/a	"""
3033	n/a	pass
3034	n/a
3035	n/a	add_c_return_converter(CReturnConverter, 'object')
3036	n/a
3037	n/a	class NoneType_return_converter(CReturnConverter):
3038	n/a	def render(self, function, data):
3039	n/a	self.declare(data)
3040	n/a	data.return_conversion.append('''
3041	n/a	if (_return_value != Py_None) {
3042	n/a	goto exit;
3043	n/a	}
3044	n/a	return_value = Py_None;
3045	n/a	Py_INCREF(Py_None);
3046	n/a	'''.strip())
3047	n/a
3048	n/a	class bool_return_converter(CReturnConverter):
3049	n/a	type = 'int'
3050	n/a
3051	n/a	def render(self, function, data):
3052	n/a	self.declare(data)
3053	n/a	self.err_occurred_if("_return_value == -1", data)
3054	n/a	data.return_conversion.append('return_value = PyBool_FromLong((long)_return_value);\n')
3055	n/a
3056	n/a	class long_return_converter(CReturnConverter):
3057	n/a	type = 'long'
3058	n/a	conversion_fn = 'PyLong_FromLong'
3059	n/a	cast = ''
3060	n/a	unsigned_cast = ''
3061	n/a
3062	n/a	def render(self, function, data):
3063	n/a	self.declare(data)
3064	n/a	self.err_occurred_if("_return_value == {}-1".format(self.unsigned_cast), data)
3065	n/a	data.return_conversion.append(
3066	n/a	''.join(('return_value = ', self.conversion_fn, '(', self.cast, '_return_value);\n')))
3067	n/a
3068	n/a	class int_return_converter(long_return_converter):
3069	n/a	type = 'int'
3070	n/a	cast = '(long)'
3071	n/a
3072	n/a	class init_return_converter(long_return_converter):
3073	n/a	"""
3074	n/a	Special return converter for __init__ functions.
3075	n/a	"""
3076	n/a	type = 'int'
3077	n/a	cast = '(long)'
3078	n/a
3079	n/a	def render(self, function, data):
3080	n/a	pass
3081	n/a
3082	n/a	class unsigned_long_return_converter(long_return_converter):
3083	n/a	type = 'unsigned long'
3084	n/a	conversion_fn = 'PyLong_FromUnsignedLong'
3085	n/a	unsigned_cast = '(unsigned long)'
3086	n/a
3087	n/a	class unsigned_int_return_converter(unsigned_long_return_converter):
3088	n/a	type = 'unsigned int'
3089	n/a	cast = '(unsigned long)'
3090	n/a	unsigned_cast = '(unsigned int)'
3091	n/a
3092	n/a	class Py_ssize_t_return_converter(long_return_converter):
3093	n/a	type = 'Py_ssize_t'
3094	n/a	conversion_fn = 'PyLong_FromSsize_t'
3095	n/a
3096	n/a	class size_t_return_converter(long_return_converter):
3097	n/a	type = 'size_t'
3098	n/a	conversion_fn = 'PyLong_FromSize_t'
3099	n/a	unsigned_cast = '(size_t)'
3100	n/a
3101	n/a
3102	n/a	class double_return_converter(CReturnConverter):
3103	n/a	type = 'double'
3104	n/a	cast = ''
3105	n/a
3106	n/a	def render(self, function, data):
3107	n/a	self.declare(data)
3108	n/a	self.err_occurred_if("_return_value == -1.0", data)
3109	n/a	data.return_conversion.append(
3110	n/a	'return_value = PyFloat_FromDouble(' + self.cast + '_return_value);\n')
3111	n/a
3112	n/a	class float_return_converter(double_return_converter):
3113	n/a	type = 'float'
3114	n/a	cast = '(double)'
3115	n/a
3116	n/a
3117	n/a	class DecodeFSDefault_return_converter(CReturnConverter):
3118	n/a	type = 'char *'
3119	n/a
3120	n/a	def render(self, function, data):
3121	n/a	self.declare(data)
3122	n/a	self.err_occurred_if_null_pointer("_return_value", data)
3123	n/a	data.return_conversion.append(
3124	n/a	'return_value = PyUnicode_DecodeFSDefault(_return_value);\n')
3125	n/a
3126	n/a
3127	n/a	def eval_ast_expr(node, globals, *, filename='-'):
3128	n/a	"""
3129	n/a	Takes an ast.Expr node. Compiles and evaluates it.
3130	n/a	Returns the result of the expression.
3131	n/a
3132	n/a	globals represents the globals dict the expression
3133	n/a	should see. (There's no equivalent for "locals" here.)
3134	n/a	"""
3135	n/a
3136	n/a	if isinstance(node, ast.Expr):
3137	n/a	node = node.value
3138	n/a
3139	n/a	node = ast.Expression(node)
3140	n/a	co = compile(node, filename, 'eval')
3141	n/a	fn = types.FunctionType(co, globals)
3142	n/a	return fn()
3143	n/a
3144	n/a
3145	n/a	class IndentStack:
3146	n/a	def __init__(self):
3147	n/a	self.indents = []
3148	n/a	self.margin = None
3149	n/a
3150	n/a	def _ensure(self):
3151	n/a	if not self.indents:
3152	n/a	fail('IndentStack expected indents, but none are defined.')
3153	n/a
3154	n/a	def measure(self, line):
3155	n/a	"""
3156	n/a	Returns the length of the line's margin.
3157	n/a	"""
3158	n/a	if '\t' in line:
3159	n/a	fail('Tab characters are illegal in the Argument Clinic DSL.')
3160	n/a	stripped = line.lstrip()
3161	n/a	if not len(stripped):
3162	n/a	# we can't tell anything from an empty line
3163	n/a	# so just pretend it's indented like our current indent
3164	n/a	self._ensure()
3165	n/a	return self.indents[-1]
3166	n/a	return len(line) - len(stripped)
3167	n/a
3168	n/a	def infer(self, line):
3169	n/a	"""
3170	n/a	Infer what is now the current margin based on this line.
3171	n/a	Returns:
3172	n/a	1 if we have indented (or this is the first margin)
3173	n/a	0 if the margin has not changed
3174	n/a	-N if we have dedented N times
3175	n/a	"""
3176	n/a	indent = self.measure(line)
3177	n/a	margin = ' ' * indent
3178	n/a	if not self.indents:
3179	n/a	self.indents.append(indent)
3180	n/a	self.margin = margin
3181	n/a	return 1
3182	n/a	current = self.indents[-1]
3183	n/a	if indent == current:
3184	n/a	return 0
3185	n/a	if indent > current:
3186	n/a	self.indents.append(indent)
3187	n/a	self.margin = margin
3188	n/a	return 1
3189	n/a	# indent < current
3190	n/a	if indent not in self.indents:
3191	n/a	fail("Illegal outdent.")
3192	n/a	outdent_count = 0
3193	n/a	while indent != current:
3194	n/a	self.indents.pop()
3195	n/a	current = self.indents[-1]
3196	n/a	outdent_count -= 1
3197	n/a	self.margin = margin
3198	n/a	return outdent_count
3199	n/a
3200	n/a	@property
3201	n/a	def depth(self):
3202	n/a	"""
3203	n/a	Returns how many margins are currently defined.
3204	n/a	"""
3205	n/a	return len(self.indents)
3206	n/a
3207	n/a	def indent(self, line):
3208	n/a	"""
3209	n/a	Indents a line by the currently defined margin.
3210	n/a	"""
3211	n/a	return self.margin + line
3212	n/a
3213	n/a	def dedent(self, line):
3214	n/a	"""
3215	n/a	Dedents a line by the currently defined margin.
3216	n/a	(The inverse of 'indent'.)
3217	n/a	"""
3218	n/a	margin = self.margin
3219	n/a	indent = self.indents[-1]
3220	n/a	if not line.startswith(margin):
3221	n/a	fail('Cannot dedent, line does not start with the previous margin:')
3222	n/a	return line[indent:]
3223	n/a
3224	n/a
3225	n/a	class DSLParser:
3226	n/a	def __init__(self, clinic):
3227	n/a	self.clinic = clinic
3228	n/a
3229	n/a	self.directives = {}
3230	n/a	for name in dir(self):
3231	n/a	# functions that start with directive_ are added to directives
3232	n/a	_, s, key = name.partition("directive_")
3233	n/a	if s:
3234	n/a	self.directives[key] = getattr(self, name)
3235	n/a
3236	n/a	# functions that start with at_ are too, with an @ in front
3237	n/a	_, s, key = name.partition("at_")
3238	n/a	if s:
3239	n/a	self.directives['@' + key] = getattr(self, name)
3240	n/a
3241	n/a	self.reset()
3242	n/a
3243	n/a	def reset(self):
3244	n/a	self.function = None
3245	n/a	self.state = self.state_dsl_start
3246	n/a	self.parameter_indent = None
3247	n/a	self.keyword_only = False
3248	n/a	self.positional_only = False
3249	n/a	self.group = 0
3250	n/a	self.parameter_state = self.ps_start
3251	n/a	self.seen_positional_with_default = False
3252	n/a	self.indent = IndentStack()
3253	n/a	self.kind = CALLABLE
3254	n/a	self.coexist = False
3255	n/a	self.parameter_continuation = ''
3256	n/a	self.preserve_output = False
3257	n/a
3258	n/a	def directive_version(self, required):
3259	n/a	global version
3260	n/a	if version_comparitor(version, required) < 0:
3261	n/a	fail("Insufficient Clinic version!\n Version: " + version + "\n Required: " + required)
3262	n/a
3263	n/a	def directive_module(self, name):
3264	n/a	fields = name.split('.')
3265	n/a	new = fields.pop()
3266	n/a	module, cls = self.clinic._module_and_class(fields)
3267	n/a	if cls:
3268	n/a	fail("Can't nest a module inside a class!")
3269	n/a
3270	n/a	if name in module.classes:
3271	n/a	fail("Already defined module " + repr(name) + "!")
3272	n/a
3273	n/a	m = Module(name, module)
3274	n/a	module.modules[name] = m
3275	n/a	self.block.signatures.append(m)
3276	n/a
3277	n/a	def directive_class(self, name, typedef, type_object):
3278	n/a	fields = name.split('.')
3279	n/a	in_classes = False
3280	n/a	parent = self
3281	n/a	name = fields.pop()
3282	n/a	so_far = []
3283	n/a	module, cls = self.clinic._module_and_class(fields)
3284	n/a
3285	n/a	parent = cls or module
3286	n/a	if name in parent.classes:
3287	n/a	fail("Already defined class " + repr(name) + "!")
3288	n/a
3289	n/a	c = Class(name, module, cls, typedef, type_object)
3290	n/a	parent.classes[name] = c
3291	n/a	self.block.signatures.append(c)
3292	n/a
3293	n/a	def directive_set(self, name, value):
3294	n/a	if name not in ("line_prefix", "line_suffix"):
3295	n/a	fail("unknown variable", repr(name))
3296	n/a
3297	n/a	value = value.format_map({
3298	n/a	'block comment start': '/*',
3299	n/a	'block comment end': '*/',
3300	n/a	})
3301	n/a
3302	n/a	self.clinic.__dict__[name] = value
3303	n/a
3304	n/a	def directive_destination(self, name, command, *args):
3305	n/a	if command == 'new':
3306	n/a	self.clinic.add_destination(name, *args)
3307	n/a	return
3308	n/a
3309	n/a	if command == 'clear':
3310	n/a	self.clinic.get_destination(name).clear()
3311	n/a	fail("unknown destination command", repr(command))
3312	n/a
3313	n/a
3314	n/a	def directive_output(self, command_or_name, destination=''):
3315	n/a	fd = self.clinic.destination_buffers
3316	n/a
3317	n/a	if command_or_name == "preset":
3318	n/a	preset = self.clinic.presets.get(destination)
3319	n/a	if not preset:
3320	n/a	fail("Unknown preset " + repr(destination) + "!")
3321	n/a	fd.update(preset)
3322	n/a	return
3323	n/a
3324	n/a	if command_or_name == "push":
3325	n/a	self.clinic.destination_buffers_stack.append(fd.copy())
3326	n/a	return
3327	n/a
3328	n/a	if command_or_name == "pop":
3329	n/a	if not self.clinic.destination_buffers_stack:
3330	n/a	fail("Can't 'output pop', stack is empty!")
3331	n/a	previous_fd = self.clinic.destination_buffers_stack.pop()
3332	n/a	fd.update(previous_fd)
3333	n/a	return
3334	n/a
3335	n/a	# secret command for debugging!
3336	n/a	if command_or_name == "print":
3337	n/a	self.block.output.append(pprint.pformat(fd))
3338	n/a	self.block.output.append('\n')
3339	n/a	return
3340	n/a
3341	n/a	d = self.clinic.get_destination(destination)
3342	n/a
3343	n/a	if command_or_name == "everything":
3344	n/a	for name in list(fd):
3345	n/a	fd[name] = d
3346	n/a	return
3347	n/a
3348	n/a	if command_or_name not in fd:
3349	n/a	fail("Invalid command / destination name " + repr(command_or_name) + ", must be one of:\n preset push pop print everything " + " ".join(fd))
3350	n/a	fd[command_or_name] = d
3351	n/a
3352	n/a	def directive_dump(self, name):
3353	n/a	self.block.output.append(self.clinic.get_destination(name).dump())
3354	n/a
3355	n/a	def directive_print(self, *args):
3356	n/a	self.block.output.append(' '.join(args))
3357	n/a	self.block.output.append('\n')
3358	n/a
3359	n/a	def directive_preserve(self):
3360	n/a	if self.preserve_output:
3361	n/a	fail("Can't have preserve twice in one block!")
3362	n/a	self.preserve_output = True
3363	n/a
3364	n/a	def at_classmethod(self):
3365	n/a	if self.kind is not CALLABLE:
3366	n/a	fail("Can't set @classmethod, function is not a normal callable")
3367	n/a	self.kind = CLASS_METHOD
3368	n/a
3369	n/a	def at_staticmethod(self):
3370	n/a	if self.kind is not CALLABLE:
3371	n/a	fail("Can't set @staticmethod, function is not a normal callable")
3372	n/a	self.kind = STATIC_METHOD
3373	n/a
3374	n/a	def at_coexist(self):
3375	n/a	if self.coexist:
3376	n/a	fail("Called @coexist twice!")
3377	n/a	self.coexist = True
3378	n/a
3379	n/a	def parse(self, block):
3380	n/a	self.reset()
3381	n/a	self.block = block
3382	n/a	self.saved_output = self.block.output
3383	n/a	block.output = []
3384	n/a	block_start = self.clinic.block_parser.line_number
3385	n/a	lines = block.input.split('\n')
3386	n/a	for line_number, line in enumerate(lines, self.clinic.block_parser.block_start_line_number):
3387	n/a	if '\t' in line:
3388	n/a	fail('Tab characters are illegal in the Clinic DSL.\n\t' + repr(line), line_number=block_start)
3389	n/a	self.state(line)
3390	n/a
3391	n/a	self.next(self.state_terminal)
3392	n/a	self.state(None)
3393	n/a
3394	n/a	block.output.extend(self.clinic.language.render(clinic, block.signatures))
3395	n/a
3396	n/a	if self.preserve_output:
3397	n/a	if block.output:
3398	n/a	fail("'preserve' only works for blocks that don't produce any output!")
3399	n/a	block.output = self.saved_output
3400	n/a
3401	n/a	@staticmethod
3402	n/a	def ignore_line(line):
3403	n/a	# ignore comment-only lines
3404	n/a	if line.lstrip().startswith('#'):
3405	n/a	return True
3406	n/a
3407	n/a	# Ignore empty lines too
3408	n/a	# (but not in docstring sections!)
3409	n/a	if not line.strip():
3410	n/a	return True
3411	n/a
3412	n/a	return False
3413	n/a
3414	n/a	@staticmethod
3415	n/a	def calculate_indent(line):
3416	n/a	return len(line) - len(line.strip())
3417	n/a
3418	n/a	def next(self, state, line=None):
3419	n/a	# real_print(self.state.__name__, "->", state.__name__, ", line=", line)
3420	n/a	self.state = state
3421	n/a	if line is not None:
3422	n/a	self.state(line)
3423	n/a
3424	n/a	def state_dsl_start(self, line):
3425	n/a	# self.block = self.ClinicOutputBlock(self)
3426	n/a	if self.ignore_line(line):
3427	n/a	return
3428	n/a
3429	n/a	# is it a directive?
3430	n/a	fields = shlex.split(line)
3431	n/a	directive_name = fields[0]
3432	n/a	directive = self.directives.get(directive_name, None)
3433	n/a	if directive:
3434	n/a	try:
3435	n/a	directive(*fields[1:])
3436	n/a	except TypeError as e:
3437	n/a	fail(str(e))
3438	n/a	return
3439	n/a
3440	n/a	self.next(self.state_modulename_name, line)
3441	n/a
3442	n/a	def state_modulename_name(self, line):
3443	n/a	# looking for declaration, which establishes the leftmost column
3444	n/a	# line should be
3445	n/a	# modulename.fnname [as c_basename] [-> return annotation]
3446	n/a	# square brackets denote optional syntax.
3447	n/a	#
3448	n/a	# alternatively:
3449	n/a	# modulename.fnname [as c_basename] = modulename.existing_fn_name
3450	n/a	# clones the parameters and return converter from that
3451	n/a	# function. you can't modify them. you must enter a
3452	n/a	# new docstring.
3453	n/a	#
3454	n/a	# (but we might find a directive first!)
3455	n/a	#
3456	n/a	# this line is permitted to start with whitespace.
3457	n/a	# we'll call this number of spaces F (for "function").
3458	n/a
3459	n/a	if not line.strip():
3460	n/a	return
3461	n/a
3462	n/a	self.indent.infer(line)
3463	n/a
3464	n/a	# are we cloning?
3465	n/a	before, equals, existing = line.rpartition('=')
3466	n/a	if equals:
3467	n/a	full_name, _, c_basename = before.partition(' as ')
3468	n/a	full_name = full_name.strip()
3469	n/a	c_basename = c_basename.strip()
3470	n/a	existing = existing.strip()
3471	n/a	if (is_legal_py_identifier(full_name) and
3472	n/a	(not c_basename or is_legal_c_identifier(c_basename)) and
3473	n/a	is_legal_py_identifier(existing)):
3474	n/a	# we're cloning!
3475	n/a	fields = [x.strip() for x in existing.split('.')]
3476	n/a	function_name = fields.pop()
3477	n/a	module, cls = self.clinic._module_and_class(fields)
3478	n/a
3479	n/a	for existing_function in (cls or module).functions:
3480	n/a	if existing_function.name == function_name:
3481	n/a	break
3482	n/a	else:
3483	n/a	existing_function = None
3484	n/a	if not existing_function:
3485	n/a	print("class", cls, "module", module, "existing", existing)
3486	n/a	print("cls. functions", cls.functions)
3487	n/a	fail("Couldn't find existing function " + repr(existing) + "!")
3488	n/a
3489	n/a	fields = [x.strip() for x in full_name.split('.')]
3490	n/a	function_name = fields.pop()
3491	n/a	module, cls = self.clinic._module_and_class(fields)
3492	n/a
3493	n/a	if not (existing_function.kind == self.kind and existing_function.coexist == self.coexist):
3494	n/a	fail("'kind' of function and cloned function don't match! (@classmethod/@staticmethod/@coexist)")
3495	n/a	self.function = existing_function.copy(name=function_name, full_name=full_name, module=module, cls=cls, c_basename=c_basename, docstring='')
3496	n/a
3497	n/a	self.block.signatures.append(self.function)
3498	n/a	(cls or module).functions.append(self.function)
3499	n/a	self.next(self.state_function_docstring)
3500	n/a	return
3501	n/a
3502	n/a	line, _, returns = line.partition('->')
3503	n/a
3504	n/a	full_name, _, c_basename = line.partition(' as ')
3505	n/a	full_name = full_name.strip()
3506	n/a	c_basename = c_basename.strip() or None
3507	n/a
3508	n/a	if not is_legal_py_identifier(full_name):
3509	n/a	fail("Illegal function name: {}".format(full_name))
3510	n/a	if c_basename and not is_legal_c_identifier(c_basename):
3511	n/a	fail("Illegal C basename: {}".format(c_basename))
3512	n/a
3513	n/a	return_converter = None
3514	n/a	if returns:
3515	n/a	ast_input = "def x() -> {}: pass".format(returns)
3516	n/a	module = None
3517	n/a	try:
3518	n/a	module = ast.parse(ast_input)
3519	n/a	except SyntaxError:
3520	n/a	pass
3521	n/a	if not module:
3522	n/a	fail("Badly-formed annotation for " + full_name + ": " + returns)
3523	n/a	try:
3524	n/a	name, legacy, kwargs = self.parse_converter(module.body[0].returns)
3525	n/a	if legacy:
3526	n/a	fail("Legacy converter {!r} not allowed as a return converter"
3527	n/a	.format(name))
3528	n/a	if name not in return_converters:
3529	n/a	fail("No available return converter called " + repr(name))
3530	n/a	return_converter = return_converters[name](**kwargs)
3531	n/a	except ValueError:
3532	n/a	fail("Badly-formed annotation for " + full_name + ": " + returns)
3533	n/a
3534	n/a	fields = [x.strip() for x in full_name.split('.')]
3535	n/a	function_name = fields.pop()
3536	n/a	module, cls = self.clinic._module_and_class(fields)
3537	n/a
3538	n/a	fields = full_name.split('.')
3539	n/a	if fields[-1] == '__new__':
3540	n/a	if (self.kind != CLASS_METHOD) or (not cls):
3541	n/a	fail("__new__ must be a class method!")
3542	n/a	self.kind = METHOD_NEW
3543	n/a	elif fields[-1] == '__init__':
3544	n/a	if (self.kind != CALLABLE) or (not cls):
3545	n/a	fail("__init__ must be a normal method, not a class or static method!")
3546	n/a	self.kind = METHOD_INIT
3547	n/a	if not return_converter:
3548	n/a	return_converter = init_return_converter()
3549	n/a	elif fields[-1] in unsupported_special_methods:
3550	n/a	fail(fields[-1] + " is a special method and cannot be converted to Argument Clinic! (Yet.)")
3551	n/a
3552	n/a	if not return_converter:
3553	n/a	return_converter = CReturnConverter()
3554	n/a
3555	n/a	if not module:
3556	n/a	fail("Undefined module used in declaration of " + repr(full_name.strip()) + ".")
3557	n/a	self.function = Function(name=function_name, full_name=full_name, module=module, cls=cls, c_basename=c_basename,
3558	n/a	return_converter=return_converter, kind=self.kind, coexist=self.coexist)
3559	n/a	self.block.signatures.append(self.function)
3560	n/a
3561	n/a	# insert a self converter automatically
3562	n/a	type, name = correct_name_for_self(self.function)
3563	n/a	kwargs = {}
3564	n/a	if cls and type == "PyObject *":
3565	n/a	kwargs['type'] = cls.typedef
3566	n/a	sc = self.function.self_converter = self_converter(name, name, self.function, **kwargs)
3567	n/a	p_self = Parameter(sc.name, inspect.Parameter.POSITIONAL_ONLY, function=self.function, converter=sc)
3568	n/a	self.function.parameters[sc.name] = p_self
3569	n/a
3570	n/a	(cls or module).functions.append(self.function)
3571	n/a	self.next(self.state_parameters_start)
3572	n/a
3573	n/a	# Now entering the parameters section. The rules, formally stated:
3574	n/a	#
3575	n/a	# * All lines must be indented with spaces only.
3576	n/a	# * The first line must be a parameter declaration.
3577	n/a	# * The first line must be indented.
3578	n/a	# * This first line establishes the indent for parameters.
3579	n/a	# * We'll call this number of spaces P (for "parameter").
3580	n/a	# * Thenceforth:
3581	n/a	# * Lines indented with P spaces specify a parameter.
3582	n/a	# * Lines indented with > P spaces are docstrings for the previous
3583	n/a	# parameter.
3584	n/a	# * We'll call this number of spaces D (for "docstring").
3585	n/a	# * All subsequent lines indented with >= D spaces are stored as
3586	n/a	# part of the per-parameter docstring.
3587	n/a	# * All lines will have the first D spaces of the indent stripped
3588	n/a	# before they are stored.
3589	n/a	# * It's illegal to have a line starting with a number of spaces X
3590	n/a	# such that P < X < D.
3591	n/a	# * A line with < P spaces is the first line of the function
3592	n/a	# docstring, which ends processing for parameters and per-parameter
3593	n/a	# docstrings.
3594	n/a	# * The first line of the function docstring must be at the same
3595	n/a	# indent as the function declaration.
3596	n/a	# * It's illegal to have any line in the parameters section starting
3597	n/a	# with X spaces such that F < X < P. (As before, F is the indent
3598	n/a	# of the function declaration.)
3599	n/a	#
3600	n/a	# Also, currently Argument Clinic places the following restrictions on groups:
3601	n/a	# * Each group must contain at least one parameter.
3602	n/a	# * Each group may contain at most one group, which must be the furthest
3603	n/a	# thing in the group from the required parameters. (The nested group
3604	n/a	# must be the first in the group when it's before the required
3605	n/a	# parameters, and the last thing in the group when after the required
3606	n/a	# parameters.)
3607	n/a	# * There may be at most one (top-level) group to the left or right of
3608	n/a	# the required parameters.
3609	n/a	# * You must specify a slash, and it must be after all parameters.
3610	n/a	# (In other words: either all parameters are positional-only,
3611	n/a	# or none are.)
3612	n/a	#
3613	n/a	# Said another way:
3614	n/a	# * Each group must contain at least one parameter.
3615	n/a	# * All left square brackets before the required parameters must be
3616	n/a	# consecutive. (You can't have a left square bracket followed
3617	n/a	# by a parameter, then another left square bracket. You can't
3618	n/a	# have a left square bracket, a parameter, a right square bracket,
3619	n/a	# and then a left square bracket.)
3620	n/a	# * All right square brackets after the required parameters must be
3621	n/a	# consecutive.
3622	n/a	#
3623	n/a	# These rules are enforced with a single state variable:
3624	n/a	# "parameter_state". (Previously the code was a miasma of ifs and
3625	n/a	# separate boolean state variables.) The states are:
3626	n/a	#
3627	n/a	# [ [ a, b, ] c, ] d, e, f=3, [ g, h, [ i ] ] <- line
3628	n/a	# 01 2 3 4 5 6 <- state transitions
3629	n/a	#
3630	n/a	# 0: ps_start. before we've seen anything. legal transitions are to 1 or 3.
3631	n/a	# 1: ps_left_square_before. left square brackets before required parameters.
3632	n/a	# 2: ps_group_before. in a group, before required parameters.
3633	n/a	# 3: ps_required. required parameters, positional-or-keyword or positional-only
3634	n/a	# (we don't know yet). (renumber left groups!)
3635	n/a	# 4: ps_optional. positional-or-keyword or positional-only parameters that
3636	n/a	# now must have default values.
3637	n/a	# 5: ps_group_after. in a group, after required parameters.
3638	n/a	# 6: ps_right_square_after. right square brackets after required parameters.
3639	n/a	ps_start, ps_left_square_before, ps_group_before, ps_required, \
3640	n/a	ps_optional, ps_group_after, ps_right_square_after = range(7)
3641	n/a
3642	n/a	def state_parameters_start(self, line):
3643	n/a	if self.ignore_line(line):
3644	n/a	return
3645	n/a
3646	n/a	# if this line is not indented, we have no parameters
3647	n/a	if not self.indent.infer(line):
3648	n/a	return self.next(self.state_function_docstring, line)
3649	n/a
3650	n/a	self.parameter_continuation = ''
3651	n/a	return self.next(self.state_parameter, line)
3652	n/a
3653	n/a
3654	n/a	def to_required(self):
3655	n/a	"""
3656	n/a	Transition to the "required" parameter state.
3657	n/a	"""
3658	n/a	if self.parameter_state != self.ps_required:
3659	n/a	self.parameter_state = self.ps_required
3660	n/a	for p in self.function.parameters.values():
3661	n/a	p.group = -p.group
3662	n/a
3663	n/a	def state_parameter(self, line):
3664	n/a	if self.parameter_continuation:
3665	n/a	line = self.parameter_continuation + ' ' + line.lstrip()
3666	n/a	self.parameter_continuation = ''
3667	n/a
3668	n/a	if self.ignore_line(line):
3669	n/a	return
3670	n/a
3671	n/a	assert self.indent.depth == 2
3672	n/a	indent = self.indent.infer(line)
3673	n/a	if indent == -1:
3674	n/a	# we outdented, must be to definition column
3675	n/a	return self.next(self.state_function_docstring, line)
3676	n/a
3677	n/a	if indent == 1:
3678	n/a	# we indented, must be to new parameter docstring column
3679	n/a	return self.next(self.state_parameter_docstring_start, line)
3680	n/a
3681	n/a	line = line.rstrip()
3682	n/a	if line.endswith('\\'):
3683	n/a	self.parameter_continuation = line[:-1]
3684	n/a	return
3685	n/a
3686	n/a	line = line.lstrip()
3687	n/a
3688	n/a	if line in ('*', '/', '[', ']'):
3689	n/a	self.parse_special_symbol(line)
3690	n/a	return
3691	n/a
3692	n/a	if self.parameter_state in (self.ps_start, self.ps_required):
3693	n/a	self.to_required()
3694	n/a	elif self.parameter_state == self.ps_left_square_before:
3695	n/a	self.parameter_state = self.ps_group_before
3696	n/a	elif self.parameter_state == self.ps_group_before:
3697	n/a	if not self.group:
3698	n/a	self.to_required()
3699	n/a	elif self.parameter_state in (self.ps_group_after, self.ps_optional):
3700	n/a	pass
3701	n/a	else:
3702	n/a	fail("Function " + self.function.name + " has an unsupported group configuration. (Unexpected state " + str(self.parameter_state) + ".a)")
3703	n/a
3704	n/a	# handle "as" for parameters too
3705	n/a	c_name = None
3706	n/a	name, have_as_token, trailing = line.partition(' as ')
3707	n/a	if have_as_token:
3708	n/a	name = name.strip()
3709	n/a	if ' ' not in name:
3710	n/a	fields = trailing.strip().split(' ')
3711	n/a	if not fields:
3712	n/a	fail("Invalid 'as' clause!")
3713	n/a	c_name = fields[0]
3714	n/a	if c_name.endswith(':'):
3715	n/a	name += ':'
3716	n/a	c_name = c_name[:-1]
3717	n/a	fields[0] = name
3718	n/a	line = ' '.join(fields)
3719	n/a
3720	n/a	base, equals, default = line.rpartition('=')
3721	n/a	if not equals:
3722	n/a	base = default
3723	n/a	default = None
3724	n/a
3725	n/a	module = None
3726	n/a	try:
3727	n/a	ast_input = "def x({}): pass".format(base)
3728	n/a	module = ast.parse(ast_input)
3729	n/a	except SyntaxError:
3730	n/a	try:
3731	n/a	# the last = was probably inside a function call, like
3732	n/a	# c: int(accept={str})
3733	n/a	# so assume there was no actual default value.
3734	n/a	default = None
3735	n/a	ast_input = "def x({}): pass".format(line)
3736	n/a	module = ast.parse(ast_input)
3737	n/a	except SyntaxError:
3738	n/a	pass
3739	n/a	if not module:
3740	n/a	fail("Function " + self.function.name + " has an invalid parameter declaration:\n\t" + line)
3741	n/a
3742	n/a	function_args = module.body[0].args
3743	n/a
3744	n/a	if len(function_args.args) > 1:
3745	n/a	fail("Function " + self.function.name + " has an invalid parameter declaration (comma?):\n\t" + line)
3746	n/a	if function_args.defaults or function_args.kw_defaults:
3747	n/a	fail("Function " + self.function.name + " has an invalid parameter declaration (default value?):\n\t" + line)
3748	n/a	if function_args.vararg or function_args.kwarg:
3749	n/a	fail("Function " + self.function.name + " has an invalid parameter declaration (args? *kwargs?):\n\t" + line)
3750	n/a
3751	n/a	parameter = function_args.args[0]
3752	n/a
3753	n/a	parameter_name = parameter.arg
3754	n/a	name, legacy, kwargs = self.parse_converter(parameter.annotation)
3755	n/a
3756	n/a	if not default:
3757	n/a	if self.parameter_state == self.ps_optional:
3758	n/a	fail("Can't have a parameter without a default (" + repr(parameter_name) + ")\nafter a parameter with a default!")
3759	n/a	value = unspecified
3760	n/a	if 'py_default' in kwargs:
3761	n/a	fail("You can't specify py_default without specifying a default value!")
3762	n/a	else:
3763	n/a	if self.parameter_state == self.ps_required:
3764	n/a	self.parameter_state = self.ps_optional
3765	n/a	default = default.strip()
3766	n/a	bad = False
3767	n/a	ast_input = "x = {}".format(default)
3768	n/a	bad = False
3769	n/a	try:
3770	n/a	module = ast.parse(ast_input)
3771	n/a
3772	n/a	if 'c_default' not in kwargs:
3773	n/a	# we can only represent very simple data values in C.
3774	n/a	# detect whether default is okay, via a blacklist
3775	n/a	# of disallowed ast nodes.
3776	n/a	class DetectBadNodes(ast.NodeVisitor):
3777	n/a	bad = False
3778	n/a	def bad_node(self, node):
3779	n/a	self.bad = True
3780	n/a
3781	n/a	# inline function call
3782	n/a	visit_Call = bad_node
3783	n/a	# inline if statement ("x = 3 if y else z")
3784	n/a	visit_IfExp = bad_node
3785	n/a
3786	n/a	# comprehensions and generator expressions
3787	n/a	visit_ListComp = visit_SetComp = bad_node
3788	n/a	visit_DictComp = visit_GeneratorExp = bad_node
3789	n/a
3790	n/a	# literals for advanced types
3791	n/a	visit_Dict = visit_Set = bad_node
3792	n/a	visit_List = visit_Tuple = bad_node
3793	n/a
3794	n/a	# "starred": "a = [1, 2, 3]; *a"
3795	n/a	visit_Starred = bad_node
3796	n/a
3797	n/a	# allow ellipsis, for now
3798	n/a	# visit_Ellipsis = bad_node
3799	n/a
3800	n/a	blacklist = DetectBadNodes()
3801	n/a	blacklist.visit(module)
3802	n/a	bad = blacklist.bad
3803	n/a	else:
3804	n/a	# if they specify a c_default, we can be more lenient about the default value.
3805	n/a	# but at least make an attempt at ensuring it's a valid expression.
3806	n/a	try:
3807	n/a	value = eval(default)
3808	n/a	if value == unspecified:
3809	n/a	fail("'unspecified' is not a legal default value!")
3810	n/a	except NameError:
3811	n/a	pass # probably a named constant
3812	n/a	except Exception as e:
3813	n/a	fail("Malformed expression given as default value\n"
3814	n/a	"{!r} caused {!r}".format(default, e))
3815	n/a	if bad:
3816	n/a	fail("Unsupported expression as default value: " + repr(default))
3817	n/a
3818	n/a	expr = module.body[0].value
3819	n/a	# mild hack: explicitly support NULL as a default value
3820	n/a	if isinstance(expr, ast.Name) and expr.id == 'NULL':
3821	n/a	value = NULL
3822	n/a	py_default = 'None'
3823	n/a	c_default = "NULL"
3824	n/a	elif (isinstance(expr, ast.BinOp) or
3825	n/a	(isinstance(expr, ast.UnaryOp) and not isinstance(expr.operand, ast.Num))):
3826	n/a	c_default = kwargs.get("c_default")
3827	n/a	if not (isinstance(c_default, str) and c_default):
3828	n/a	fail("When you specify an expression (" + repr(default) + ") as your default value,\nyou MUST specify a valid c_default.")
3829	n/a	py_default = default
3830	n/a	value = unknown
3831	n/a	elif isinstance(expr, ast.Attribute):
3832	n/a	a = []
3833	n/a	n = expr
3834	n/a	while isinstance(n, ast.Attribute):
3835	n/a	a.append(n.attr)
3836	n/a	n = n.value
3837	n/a	if not isinstance(n, ast.Name):
3838	n/a	fail("Unsupported default value " + repr(default) + " (looked like a Python constant)")
3839	n/a	a.append(n.id)
3840	n/a	py_default = ".".join(reversed(a))
3841	n/a
3842	n/a	c_default = kwargs.get("c_default")
3843	n/a	if not (isinstance(c_default, str) and c_default):
3844	n/a	fail("When you specify a named constant (" + repr(py_default) + ") as your default value,\nyou MUST specify a valid c_default.")
3845	n/a
3846	n/a	try:
3847	n/a	value = eval(py_default)
3848	n/a	except NameError:
3849	n/a	value = unknown
3850	n/a	else:
3851	n/a	value = ast.literal_eval(expr)
3852	n/a	py_default = repr(value)
3853	n/a	if isinstance(value, (bool, None.__class__)):
3854	n/a	c_default = "Py_" + py_default
3855	n/a	elif isinstance(value, str):
3856	n/a	c_default = c_repr(value)
3857	n/a	else:
3858	n/a	c_default = py_default
3859	n/a
3860	n/a	except SyntaxError as e:
3861	n/a	fail("Syntax error: " + repr(e.text))
3862	n/a	except (ValueError, AttributeError):
3863	n/a	value = unknown
3864	n/a	c_default = kwargs.get("c_default")
3865	n/a	py_default = default
3866	n/a	if not (isinstance(c_default, str) and c_default):
3867	n/a	fail("When you specify a named constant (" + repr(py_default) + ") as your default value,\nyou MUST specify a valid c_default.")
3868	n/a
3869	n/a	kwargs.setdefault('c_default', c_default)
3870	n/a	kwargs.setdefault('py_default', py_default)
3871	n/a
3872	n/a	dict = legacy_converters if legacy else converters
3873	n/a	legacy_str = "legacy " if legacy else ""
3874	n/a	if name not in dict:
3875	n/a	fail('{} is not a valid {}converter'.format(name, legacy_str))
3876	n/a	# if you use a c_name for the parameter, we just give that name to the converter
3877	n/a	# but the parameter object gets the python name
3878	n/a	converter = dict[name](c_name or parameter_name, parameter_name, self.function, value, **kwargs)
3879	n/a
3880	n/a	kind = inspect.Parameter.KEYWORD_ONLY if self.keyword_only else inspect.Parameter.POSITIONAL_OR_KEYWORD
3881	n/a
3882	n/a	if isinstance(converter, self_converter):
3883	n/a	if len(self.function.parameters) == 1:
3884	n/a	if (self.parameter_state != self.ps_required):
3885	n/a	fail("A 'self' parameter cannot be marked optional.")
3886	n/a	if value is not unspecified:
3887	n/a	fail("A 'self' parameter cannot have a default value.")
3888	n/a	if self.group:
3889	n/a	fail("A 'self' parameter cannot be in an optional group.")
3890	n/a	kind = inspect.Parameter.POSITIONAL_ONLY
3891	n/a	self.parameter_state = self.ps_start
3892	n/a	self.function.parameters.clear()
3893	n/a	else:
3894	n/a	fail("A 'self' parameter, if specified, must be the very first thing in the parameter block.")
3895	n/a
3896	n/a	p = Parameter(parameter_name, kind, function=self.function, converter=converter, default=value, group=self.group)
3897	n/a
3898	n/a	if parameter_name in self.function.parameters:
3899	n/a	fail("You can't have two parameters named " + repr(parameter_name) + "!")
3900	n/a	self.function.parameters[parameter_name] = p
3901	n/a
3902	n/a	def parse_converter(self, annotation):
3903	n/a	if isinstance(annotation, ast.Str):
3904	n/a	return annotation.s, True, {}
3905	n/a
3906	n/a	if isinstance(annotation, ast.Name):
3907	n/a	return annotation.id, False, {}
3908	n/a
3909	n/a	if not isinstance(annotation, ast.Call):
3910	n/a	fail("Annotations must be either a name, a function call, or a string.")
3911	n/a
3912	n/a	name = annotation.func.id
3913	n/a	symbols = globals()
3914	n/a
3915	n/a	kwargs = {node.arg: eval_ast_expr(node.value, symbols) for node in annotation.keywords}
3916	n/a	return name, False, kwargs
3917	n/a
3918	n/a	def parse_special_symbol(self, symbol):
3919	n/a	if symbol == '*':
3920	n/a	if self.keyword_only:
3921	n/a	fail("Function " + self.function.name + " uses '*' more than once.")
3922	n/a	self.keyword_only = True
3923	n/a	elif symbol == '[':
3924	n/a	if self.parameter_state in (self.ps_start, self.ps_left_square_before):
3925	n/a	self.parameter_state = self.ps_left_square_before
3926	n/a	elif self.parameter_state in (self.ps_required, self.ps_group_after):
3927	n/a	self.parameter_state = self.ps_group_after
3928	n/a	else:
3929	n/a	fail("Function " + self.function.name + " has an unsupported group configuration. (Unexpected state " + str(self.parameter_state) + ".b)")
3930	n/a	self.group += 1
3931	n/a	self.function.docstring_only = True
3932	n/a	elif symbol == ']':
3933	n/a	if not self.group:
3934	n/a	fail("Function " + self.function.name + " has a ] without a matching [.")
3935	n/a	if not any(p.group == self.group for p in self.function.parameters.values()):
3936	n/a	fail("Function " + self.function.name + " has an empty group.\nAll groups must contain at least one parameter.")
3937	n/a	self.group -= 1
3938	n/a	if self.parameter_state in (self.ps_left_square_before, self.ps_group_before):
3939	n/a	self.parameter_state = self.ps_group_before
3940	n/a	elif self.parameter_state in (self.ps_group_after, self.ps_right_square_after):
3941	n/a	self.parameter_state = self.ps_right_square_after
3942	n/a	else:
3943	n/a	fail("Function " + self.function.name + " has an unsupported group configuration. (Unexpected state " + str(self.parameter_state) + ".c)")
3944	n/a	elif symbol == '/':
3945	n/a	if self.positional_only:
3946	n/a	fail("Function " + self.function.name + " uses '/' more than once.")
3947	n/a	self.positional_only = True
3948	n/a	# ps_required and ps_optional are allowed here, that allows positional-only without option groups
3949	n/a	# to work (and have default values!)
3950	n/a	if (self.parameter_state not in (self.ps_required, self.ps_optional, self.ps_right_square_after, self.ps_group_before)) or self.group:
3951	n/a	fail("Function " + self.function.name + " has an unsupported group configuration. (Unexpected state " + str(self.parameter_state) + ".d)")
3952	n/a	if self.keyword_only:
3953	n/a	fail("Function " + self.function.name + " mixes keyword-only and positional-only parameters, which is unsupported.")
3954	n/a	# fixup preceding parameters
3955	n/a	for p in self.function.parameters.values():
3956	n/a	if (p.kind != inspect.Parameter.POSITIONAL_OR_KEYWORD and not isinstance(p.converter, self_converter)):
3957	n/a	fail("Function " + self.function.name + " mixes keyword-only and positional-only parameters, which is unsupported.")
3958	n/a	p.kind = inspect.Parameter.POSITIONAL_ONLY
3959	n/a
3960	n/a	def state_parameter_docstring_start(self, line):
3961	n/a	self.parameter_docstring_indent = len(self.indent.margin)
3962	n/a	assert self.indent.depth == 3
3963	n/a	return self.next(self.state_parameter_docstring, line)
3964	n/a
3965	n/a	# every line of the docstring must start with at least F spaces,
3966	n/a	# where F > P.
3967	n/a	# these F spaces will be stripped.
3968	n/a	def state_parameter_docstring(self, line):
3969	n/a	stripped = line.strip()
3970	n/a	if stripped.startswith('#'):
3971	n/a	return
3972	n/a
3973	n/a	indent = self.indent.measure(line)
3974	n/a	if indent < self.parameter_docstring_indent:
3975	n/a	self.indent.infer(line)
3976	n/a	assert self.indent.depth < 3
3977	n/a	if self.indent.depth == 2:
3978	n/a	# back to a parameter
3979	n/a	return self.next(self.state_parameter, line)
3980	n/a	assert self.indent.depth == 1
3981	n/a	return self.next(self.state_function_docstring, line)
3982	n/a
3983	n/a	assert self.function.parameters
3984	n/a	last_parameter = next(reversed(list(self.function.parameters.values())))
3985	n/a
3986	n/a	new_docstring = last_parameter.docstring
3987	n/a
3988	n/a	if new_docstring:
3989	n/a	new_docstring += '\n'
3990	n/a	if stripped:
3991	n/a	new_docstring += self.indent.dedent(line)
3992	n/a
3993	n/a	last_parameter.docstring = new_docstring
3994	n/a
3995	n/a	# the final stanza of the DSL is the docstring.
3996	n/a	def state_function_docstring(self, line):
3997	n/a	if self.group:
3998	n/a	fail("Function " + self.function.name + " has a ] without a matching [.")
3999	n/a
4000	n/a	stripped = line.strip()
4001	n/a	if stripped.startswith('#'):
4002	n/a	return
4003	n/a
4004	n/a	new_docstring = self.function.docstring
4005	n/a	if new_docstring:
4006	n/a	new_docstring += "\n"
4007	n/a	if stripped:
4008	n/a	line = self.indent.dedent(line).rstrip()
4009	n/a	else:
4010	n/a	line = ''
4011	n/a	new_docstring += line
4012	n/a	self.function.docstring = new_docstring
4013	n/a
4014	n/a	def format_docstring(self):
4015	n/a	f = self.function
4016	n/a
4017	n/a	new_or_init = f.kind in (METHOD_NEW, METHOD_INIT)
4018	n/a	if new_or_init and not f.docstring:
4019	n/a	# don't render a docstring at all, no signature, nothing.
4020	n/a	return f.docstring
4021	n/a
4022	n/a	text, add, output = _text_accumulator()
4023	n/a	parameters = f.render_parameters
4024	n/a
4025	n/a	##
4026	n/a	## docstring first line
4027	n/a	##
4028	n/a
4029	n/a	if new_or_init:
4030	n/a	# classes get just the name of the class
4031	n/a	# not __new__, not __init__, and not module.classname
4032	n/a	assert f.cls
4033	n/a	add(f.cls.name)
4034	n/a	else:
4035	n/a	add(f.name)
4036	n/a	add('(')
4037	n/a
4038	n/a	# populate "right_bracket_count" field for every parameter
4039	n/a	assert parameters, "We should always have a self parameter. " + repr(f)
4040	n/a	assert isinstance(parameters[0].converter, self_converter)
4041	n/a	# self is always positional-only.
4042	n/a	assert parameters[0].is_positional_only()
4043	n/a	parameters[0].right_bracket_count = 0
4044	n/a	positional_only = True
4045	n/a	for p in parameters[1:]:
4046	n/a	if not p.is_positional_only():
4047	n/a	positional_only = False
4048	n/a	else:
4049	n/a	assert positional_only
4050	n/a	if positional_only:
4051	n/a	p.right_bracket_count = abs(p.group)
4052	n/a	else:
4053	n/a	# don't put any right brackets around non-positional-only parameters, ever.
4054	n/a	p.right_bracket_count = 0
4055	n/a
4056	n/a	right_bracket_count = 0
4057	n/a
4058	n/a	def fix_right_bracket_count(desired):
4059	n/a	nonlocal right_bracket_count
4060	n/a	s = ''
4061	n/a	while right_bracket_count < desired:
4062	n/a	s += '['
4063	n/a	right_bracket_count += 1
4064	n/a	while right_bracket_count > desired:
4065	n/a	s += ']'
4066	n/a	right_bracket_count -= 1
4067	n/a	return s
4068	n/a
4069	n/a	need_slash = False
4070	n/a	added_slash = False
4071	n/a	need_a_trailing_slash = False
4072	n/a
4073	n/a	# we only need a trailing slash:
4074	n/a	# * if this is not a "docstring_only" signature
4075	n/a	# * and if the last shown parameter is
4076	n/a	# positional only
4077	n/a	if not f.docstring_only:
4078	n/a	for p in reversed(parameters):
4079	n/a	if not p.converter.show_in_signature:
4080	n/a	continue
4081	n/a	if p.is_positional_only():
4082	n/a	need_a_trailing_slash = True
4083	n/a	break
4084	n/a
4085	n/a
4086	n/a	added_star = False
4087	n/a
4088	n/a	first_parameter = True
4089	n/a	last_p = parameters[-1]
4090	n/a	line_length = len(''.join(text))
4091	n/a	indent = " " * line_length
4092	n/a	def add_parameter(text):
4093	n/a	nonlocal line_length
4094	n/a	nonlocal first_parameter
4095	n/a	if first_parameter:
4096	n/a	s = text
4097	n/a	first_parameter = False
4098	n/a	else:
4099	n/a	s = ' ' + text
4100	n/a	if line_length + len(s) >= 72:
4101	n/a	add('\n')
4102	n/a	add(indent)
4103	n/a	line_length = len(indent)
4104	n/a	s = text
4105	n/a	line_length += len(s)
4106	n/a	add(s)
4107	n/a
4108	n/a	for p in parameters:
4109	n/a	if not p.converter.show_in_signature:
4110	n/a	continue
4111	n/a	assert p.name
4112	n/a
4113	n/a	is_self = isinstance(p.converter, self_converter)
4114	n/a	if is_self and f.docstring_only:
4115	n/a	# this isn't a real machine-parsable signature,
4116	n/a	# so let's not print the "self" parameter
4117	n/a	continue
4118	n/a
4119	n/a	if p.is_positional_only():
4120	n/a	need_slash = not f.docstring_only
4121	n/a	elif need_slash and not (added_slash or p.is_positional_only()):
4122	n/a	added_slash = True
4123	n/a	add_parameter('/,')
4124	n/a
4125	n/a	if p.is_keyword_only() and not added_star:
4126	n/a	added_star = True
4127	n/a	add_parameter('*,')
4128	n/a
4129	n/a	p_add, p_output = text_accumulator()
4130	n/a	p_add(fix_right_bracket_count(p.right_bracket_count))
4131	n/a
4132	n/a	if isinstance(p.converter, self_converter):
4133	n/a	# annotate first parameter as being a "self".
4134	n/a	#
4135	n/a	# if inspect.Signature gets this function,
4136	n/a	# and it's already bound, the self parameter
4137	n/a	# will be stripped off.
4138	n/a	#
4139	n/a	# if it's not bound, it should be marked
4140	n/a	# as positional-only.
4141	n/a	#
4142	n/a	# note: we don't print "self" for __init__,
4143	n/a	# because this isn't actually the signature
4144	n/a	# for __init__. (it can't be, __init__ doesn't
4145	n/a	# have a docstring.) if this is an __init__
4146	n/a	# (or __new__), then this signature is for
4147	n/a	# calling the class to construct a new instance.
4148	n/a	p_add('$')
4149	n/a
4150	n/a	name = p.converter.signature_name or p.name
4151	n/a	p_add(name)
4152	n/a
4153	n/a	if p.converter.is_optional():
4154	n/a	p_add('=')
4155	n/a	value = p.converter.py_default
4156	n/a	if not value:
4157	n/a	value = repr(p.converter.default)
4158	n/a	p_add(value)
4159	n/a
4160	n/a	if (p != last_p) or need_a_trailing_slash:
4161	n/a	p_add(',')
4162	n/a
4163	n/a	add_parameter(p_output())
4164	n/a
4165	n/a	add(fix_right_bracket_count(0))
4166	n/a	if need_a_trailing_slash:
4167	n/a	add_parameter('/')
4168	n/a	add(')')
4169	n/a
4170	n/a	# PEP 8 says:
4171	n/a	#
4172	n/a	# The Python standard library will not use function annotations
4173	n/a	# as that would result in a premature commitment to a particular
4174	n/a	# annotation style. Instead, the annotations are left for users
4175	n/a	# to discover and experiment with useful annotation styles.
4176	n/a	#
4177	n/a	# therefore this is commented out:
4178	n/a	#
4179	n/a	# if f.return_converter.py_default:
4180	n/a	# add(' -> ')
4181	n/a	# add(f.return_converter.py_default)
4182	n/a
4183	n/a	if not f.docstring_only:
4184	n/a	add("\n" + sig_end_marker + "\n")
4185	n/a
4186	n/a	docstring_first_line = output()
4187	n/a
4188	n/a	# now fix up the places where the brackets look wrong
4189	n/a	docstring_first_line = docstring_first_line.replace(', ]', ',] ')
4190	n/a
4191	n/a	# okay. now we're officially building the "parameters" section.
4192	n/a	# create substitution text for {parameters}
4193	n/a	spacer_line = False
4194	n/a	for p in parameters:
4195	n/a	if not p.docstring.strip():
4196	n/a	continue
4197	n/a	if spacer_line:
4198	n/a	add('\n')
4199	n/a	else:
4200	n/a	spacer_line = True
4201	n/a	add(" ")
4202	n/a	add(p.name)
4203	n/a	add('\n')
4204	n/a	add(textwrap.indent(rstrip_lines(p.docstring.rstrip()), " "))
4205	n/a	parameters = output()
4206	n/a	if parameters:
4207	n/a	parameters += '\n'
4208	n/a
4209	n/a	##
4210	n/a	## docstring body
4211	n/a	##
4212	n/a
4213	n/a	docstring = f.docstring.rstrip()
4214	n/a	lines = [line.rstrip() for line in docstring.split('\n')]
4215	n/a
4216	n/a	# Enforce the summary line!
4217	n/a	# The first line of a docstring should be a summary of the function.
4218	n/a	# It should fit on one line (80 columns? 79 maybe?) and be a paragraph
4219	n/a	# by itself.
4220	n/a	#
4221	n/a	# Argument Clinic enforces the following rule:
4222	n/a	# * either the docstring is empty,
4223	n/a	# * or it must have a summary line.
4224	n/a	#
4225	n/a	# Guido said Clinic should enforce this:
4226	n/a	# http://mail.python.org/pipermail/python-dev/2013-June/127110.html
4227	n/a
4228	n/a	if len(lines) >= 2:
4229	n/a	if lines[1]:
4230	n/a	fail("Docstring for " + f.full_name + " does not have a summary line!\n" +
4231	n/a	"Every non-blank function docstring must start with\n" +
4232	n/a	"a single line summary followed by an empty line.")
4233	n/a	elif len(lines) == 1:
4234	n/a	# the docstring is only one line right now--the summary line.
4235	n/a	# add an empty line after the summary line so we have space
4236	n/a	# between it and the {parameters} we're about to add.
4237	n/a	lines.append('')
4238	n/a
4239	n/a	parameters_marker_count = len(docstring.split('{parameters}')) - 1
4240	n/a	if parameters_marker_count > 1:
4241	n/a	fail('You may not specify {parameters} more than once in a docstring!')
4242	n/a
4243	n/a	if not parameters_marker_count:
4244	n/a	# insert after summary line
4245	n/a	lines.insert(2, '{parameters}')
4246	n/a
4247	n/a	# insert at front of docstring
4248	n/a	lines.insert(0, docstring_first_line)
4249	n/a
4250	n/a	docstring = "\n".join(lines)
4251	n/a
4252	n/a	add(docstring)
4253	n/a	docstring = output()
4254	n/a
4255	n/a	docstring = linear_format(docstring, parameters=parameters)
4256	n/a	docstring = docstring.rstrip()
4257	n/a
4258	n/a	return docstring
4259	n/a
4260	n/a	def state_terminal(self, line):
4261	n/a	"""
4262	n/a	Called when processing the block is done.
4263	n/a	"""
4264	n/a	assert not line
4265	n/a
4266	n/a	if not self.function:
4267	n/a	return
4268	n/a
4269	n/a	if self.keyword_only:
4270	n/a	values = self.function.parameters.values()
4271	n/a	if not values:
4272	n/a	no_parameter_after_star = True
4273	n/a	else:
4274	n/a	last_parameter = next(reversed(list(values)))
4275	n/a	no_parameter_after_star = last_parameter.kind != inspect.Parameter.KEYWORD_ONLY
4276	n/a	if no_parameter_after_star:
4277	n/a	fail("Function " + self.function.name + " specifies '*' without any parameters afterwards.")
4278	n/a
4279	n/a	# remove trailing whitespace from all parameter docstrings
4280	n/a	for name, value in self.function.parameters.items():
4281	n/a	if not value:
4282	n/a	continue
4283	n/a	value.docstring = value.docstring.rstrip()
4284	n/a
4285	n/a	self.function.docstring = self.format_docstring()
4286	n/a
4287	n/a
4288	n/a
4289	n/a
4290	n/a	# maps strings to callables.
4291	n/a	# the callable should return an object
4292	n/a	# that implements the clinic parser
4293	n/a	# interface (__init__ and parse).
4294	n/a	#
4295	n/a	# example parsers:
4296	n/a	# "clinic", handles the Clinic DSL
4297	n/a	# "python", handles running Python code
4298	n/a	#
4299	n/a	parsers = {'clinic' : DSLParser, 'python': PythonParser}
4300	n/a
4301	n/a
4302	n/a	clinic = None
4303	n/a
4304	n/a
4305	n/a	def main(argv):
4306	n/a	import sys
4307	n/a
4308	n/a	if sys.version_info.major < 3 or sys.version_info.minor < 3:
4309	n/a	sys.exit("Error: clinic.py requires Python 3.3 or greater.")
4310	n/a
4311	n/a	import argparse
4312	n/a	cmdline = argparse.ArgumentParser()
4313	n/a	cmdline.add_argument("-f", "--force", action='store_true')
4314	n/a	cmdline.add_argument("-o", "--output", type=str)
4315	n/a	cmdline.add_argument("-v", "--verbose", action='store_true')
4316	n/a	cmdline.add_argument("--converters", action='store_true')
4317	n/a	cmdline.add_argument("--make", action='store_true')
4318	n/a	cmdline.add_argument("filename", type=str, nargs="*")
4319	n/a	ns = cmdline.parse_args(argv)
4320	n/a
4321	n/a	if ns.converters:
4322	n/a	if ns.filename:
4323	n/a	print("Usage error: can't specify --converters and a filename at the same time.")
4324	n/a	print()
4325	n/a	cmdline.print_usage()
4326	n/a	sys.exit(-1)
4327	n/a	converters = []
4328	n/a	return_converters = []
4329	n/a	ignored = set("""
4330	n/a	add_c_converter
4331	n/a	add_c_return_converter
4332	n/a	add_default_legacy_c_converter
4333	n/a	add_legacy_c_converter
4334	n/a	""".strip().split())
4335	n/a	module = globals()
4336	n/a	for name in module:
4337	n/a	for suffix, ids in (
4338	n/a	("_return_converter", return_converters),
4339	n/a	("_converter", converters),
4340	n/a	):
4341	n/a	if name in ignored:
4342	n/a	continue
4343	n/a	if name.endswith(suffix):
4344	n/a	ids.append((name, name[:-len(suffix)]))
4345	n/a	break
4346	n/a	print()
4347	n/a
4348	n/a	print("Legacy converters:")
4349	n/a	legacy = sorted(legacy_converters)
4350	n/a	print(' ' + ' '.join(c for c in legacy if c[0].isupper()))
4351	n/a	print(' ' + ' '.join(c for c in legacy if c[0].islower()))
4352	n/a	print()
4353	n/a
4354	n/a	for title, attribute, ids in (
4355	n/a	("Converters", 'converter_init', converters),
4356	n/a	("Return converters", 'return_converter_init', return_converters),
4357	n/a	):
4358	n/a	print(title + ":")
4359	n/a	longest = -1
4360	n/a	for name, short_name in ids:
4361	n/a	longest = max(longest, len(short_name))
4362	n/a	for name, short_name in sorted(ids, key=lambda x: x[1].lower()):
4363	n/a	cls = module[name]
4364	n/a	callable = getattr(cls, attribute, None)
4365	n/a	if not callable:
4366	n/a	continue
4367	n/a	signature = inspect.signature(callable)
4368	n/a	parameters = []
4369	n/a	for parameter_name, parameter in signature.parameters.items():
4370	n/a	if parameter.kind == inspect.Parameter.KEYWORD_ONLY:
4371	n/a	if parameter.default != inspect.Parameter.empty:
4372	n/a	s = '{}={!r}'.format(parameter_name, parameter.default)
4373	n/a	else:
4374	n/a	s = parameter_name
4375	n/a	parameters.append(s)
4376	n/a	print(' {}({})'.format(short_name, ', '.join(parameters)))
4377	n/a	print()
4378	n/a	print("All converters also accept (c_default=None, py_default=None, annotation=None).")
4379	n/a	print("All return converters also accept (py_default=None).")
4380	n/a	sys.exit(0)
4381	n/a
4382	n/a	if ns.make:
4383	n/a	if ns.output or ns.filename:
4384	n/a	print("Usage error: can't use -o or filenames with --make.")
4385	n/a	print()
4386	n/a	cmdline.print_usage()
4387	n/a	sys.exit(-1)
4388	n/a	for root, dirs, files in os.walk('.'):
4389	n/a	for rcs_dir in ('.svn', '.git', '.hg', 'build', 'externals'):
4390	n/a	if rcs_dir in dirs:
4391	n/a	dirs.remove(rcs_dir)
4392	n/a	for filename in files:
4393	n/a	if not (filename.endswith('.c') or filename.endswith('.h')):
4394	n/a	continue
4395	n/a	path = os.path.join(root, filename)
4396	n/a	if ns.verbose:
4397	n/a	print(path)
4398	n/a	parse_file(path, force=ns.force, verify=not ns.force)
4399	n/a	return
4400	n/a
4401	n/a	if not ns.filename:
4402	n/a	cmdline.print_usage()
4403	n/a	sys.exit(-1)
4404	n/a
4405	n/a	if ns.output and len(ns.filename) > 1:
4406	n/a	print("Usage error: can't use -o with multiple filenames.")
4407	n/a	print()
4408	n/a	cmdline.print_usage()
4409	n/a	sys.exit(-1)
4410	n/a
4411	n/a	for filename in ns.filename:
4412	n/a	if ns.verbose:
4413	n/a	print(filename)
4414	n/a	parse_file(filename, output=ns.output, force=ns.force, verify=not ns.force)
4415	n/a
4416	n/a
4417	n/a	if __name__ == "__main__":
4418	n/a	sys.exit(main(sys.argv[1:]))