| 1 |
from __future__ import annotations |
| 2 |
|
| 3 |
import argparse |
| 4 |
import inspect |
| 5 |
import os |
| 6 |
import re |
| 7 |
import sys |
| 8 |
from collections.abc import Callable |
| 9 |
from typing import NoReturn |
| 10 |
|
| 11 |
|
| 12 |
# Local imports. |
| 13 |
import libclinic |
| 14 |
import libclinic.cpp |
| 15 |
from libclinic import ClinicError |
| 16 |
from libclinic.language import Language, PythonLanguage |
| 17 |
from libclinic.block_parser import BlockParser |
| 18 |
from libclinic.converter import ( |
| 19 |
ConverterType, converters, legacy_converters) |
| 20 |
from libclinic.return_converters import ( |
| 21 |
return_converters, ReturnConverterType) |
| 22 |
from libclinic.clanguage import CLanguage |
| 23 |
from libclinic.app import Clinic |
| 24 |
|
| 25 |
|
| 26 |
# TODO: |
| 27 |
# |
| 28 |
# soon: |
| 29 |
# |
| 30 |
# * allow mixing any two of {positional-only, positional-or-keyword, |
| 31 |
# keyword-only} |
| 32 |
# * dict constructor uses positional-only and keyword-only |
| 33 |
# * max and min use positional only with an optional group |
| 34 |
# and keyword-only |
| 35 |
# |
| 36 |
|
| 37 |
|
| 38 |
# Match '#define Py_LIMITED_API'. |
| 39 |
# Match '# define Py_LIMITED_API 0x030d0000' (without the version). |
| 40 |
LIMITED_CAPI_REGEX = re.compile(r'# *define +Py_LIMITED_API') |
| 41 |
|
| 42 |
|
| 43 |
# "extensions" maps the file extension ("c", "py") to Language classes. |
| 44 |
LangDict = dict[str, Callable[[str], Language]] |
| 45 |
extensions: LangDict = { name: CLanguage for name in "c cc cpp cxx h hh hpp hxx".split() } |
| 46 |
extensions['py'] = PythonLanguage |
| 47 |
|
| 48 |
|
| 49 |
def parse_file( |
| 50 |
filename: str, |
| 51 |
*, |
| 52 |
limited_capi: bool, |
| 53 |
output: str | None = None, |
| 54 |
verify: bool = True, |
| 55 |
) -> None: |
| 56 |
if not output: |
| 57 |
output = filename |
| 58 |
|
| 59 |
extension = os.path.splitext(filename)[1][1:] |
| 60 |
if not extension: |
| 61 |
raise ClinicError(f"Can't extract file type for file {filename!r}") |
| 62 |
|
| 63 |
try: |
| 64 |
language = extensions[extension](filename) |
| 65 |
except KeyError: |
| 66 |
raise ClinicError(f"Can't identify file type for file {filename!r}") |
| 67 |
|
| 68 |
with open(filename, encoding="utf-8") as f: |
| 69 |
raw = f.read() |
| 70 |
|
| 71 |
# exit quickly if there are no clinic markers in the file |
| 72 |
find_start_re = BlockParser("", language).find_start_re |
| 73 |
if not find_start_re.search(raw): |
| 74 |
return |
| 75 |
|
| 76 |
if LIMITED_CAPI_REGEX.search(raw): |
| 77 |
limited_capi = True |
| 78 |
|
| 79 |
assert isinstance(language, CLanguage) |
| 80 |
clinic = Clinic(language, |
| 81 |
verify=verify, |
| 82 |
filename=filename, |
| 83 |
limited_capi=limited_capi) |
| 84 |
cooked = clinic.parse(raw) |
| 85 |
|
| 86 |
libclinic.write_file(output, cooked) |
| 87 |
|
| 88 |
|
| 89 |
def create_cli() -> argparse.ArgumentParser: |
| 90 |
cmdline = argparse.ArgumentParser( |
| 91 |
prog="clinic.py", |
| 92 |
description="""Preprocessor for CPython C files. |
| 93 |
|
| 94 |
The purpose of the Argument Clinic is automating all the boilerplate involved |
| 95 |
with writing argument parsing code for builtins and providing introspection |
| 96 |
signatures ("docstrings") for CPython builtins. |
| 97 |
|
| 98 |
For more information see https://devguide.python.org/development-tools/clinic/""") |
| 99 |
cmdline.add_argument("-f", "--force", action='store_true', |
| 100 |
help="force output regeneration") |
| 101 |
cmdline.add_argument("-o", "--output", type=str, |
| 102 |
help="redirect file output to OUTPUT") |
| 103 |
cmdline.add_argument("-v", "--verbose", action='store_true', |
| 104 |
help="enable verbose mode") |
| 105 |
cmdline.add_argument("--converters", action='store_true', |
| 106 |
help=("print a list of all supported converters " |
| 107 |
"and return converters")) |
| 108 |
cmdline.add_argument("--make", action='store_true', |
| 109 |
help="walk --srcdir to run over all relevant files") |
| 110 |
cmdline.add_argument("--srcdir", type=str, default=os.curdir, |
| 111 |
help="the directory tree to walk in --make mode") |
| 112 |
cmdline.add_argument("--exclude", type=str, action="append", |
| 113 |
help=("a file to exclude in --make mode; " |
| 114 |
"can be given multiple times")) |
| 115 |
cmdline.add_argument("--limited", dest="limited_capi", action='store_true', |
| 116 |
help="use the Limited C API") |
| 117 |
cmdline.add_argument("filename", metavar="FILE", type=str, nargs="*", |
| 118 |
help="the list of files to process") |
| 119 |
return cmdline |
| 120 |
|
| 121 |
|
| 122 |
def run_clinic(parser: argparse.ArgumentParser, ns: argparse.Namespace) -> None: |
| 123 |
if ns.converters: |
| 124 |
if ns.filename: |
| 125 |
parser.error( |
| 126 |
"can't specify --converters and a filename at the same time" |
| 127 |
) |
| 128 |
AnyConverterType = ConverterType | ReturnConverterType |
| 129 |
converter_list: list[tuple[str, AnyConverterType]] = [] |
| 130 |
return_converter_list: list[tuple[str, AnyConverterType]] = [] |
| 131 |
|
| 132 |
for name, converter in converters.items(): |
| 133 |
converter_list.append(( |
| 134 |
name, |
| 135 |
converter, |
| 136 |
)) |
| 137 |
for name, return_converter in return_converters.items(): |
| 138 |
return_converter_list.append(( |
| 139 |
name, |
| 140 |
return_converter |
| 141 |
)) |
| 142 |
|
| 143 |
print() |
| 144 |
|
| 145 |
print("Legacy converters:") |
| 146 |
legacy = sorted(legacy_converters) |
| 147 |
print(' ' + ' '.join(c for c in legacy if c[0].isupper())) |
| 148 |
print(' ' + ' '.join(c for c in legacy if c[0].islower())) |
| 149 |
print() |
| 150 |
|
| 151 |
for title, attribute, ids in ( |
| 152 |
("Converters", 'converter_init', converter_list), |
| 153 |
("Return converters", 'return_converter_init', return_converter_list), |
| 154 |
): |
| 155 |
print(title + ":") |
| 156 |
|
| 157 |
ids.sort(key=lambda item: item[0].lower()) |
| 158 |
longest = -1 |
| 159 |
for name, _ in ids: |
| 160 |
longest = max(longest, len(name)) |
| 161 |
|
| 162 |
for name, cls in ids: |
| 163 |
callable = getattr(cls, attribute, None) |
| 164 |
if not callable: |
| 165 |
continue |
| 166 |
signature = inspect.signature(callable) |
| 167 |
parameters = [] |
| 168 |
for parameter_name, parameter in signature.parameters.items(): |
| 169 |
if parameter.kind == inspect.Parameter.KEYWORD_ONLY: |
| 170 |
if parameter.default != inspect.Parameter.empty: |
| 171 |
s = f'{parameter_name}={parameter.default!r}' |
| 172 |
else: |
| 173 |
s = parameter_name |
| 174 |
parameters.append(s) |
| 175 |
print(' {}({})'.format(name, ', '.join(parameters))) |
| 176 |
print() |
| 177 |
print("All converters also accept (c_default=None, py_default=None, annotation=None).") |
| 178 |
print("All return converters also accept (py_default=None).") |
| 179 |
return |
| 180 |
|
| 181 |
if ns.make: |
| 182 |
if ns.output or ns.filename: |
| 183 |
parser.error("can't use -o or filenames with --make") |
| 184 |
if not ns.srcdir: |
| 185 |
parser.error("--srcdir must not be empty with --make") |
| 186 |
if ns.exclude: |
| 187 |
excludes = [os.path.join(ns.srcdir, f) for f in ns.exclude] |
| 188 |
excludes = [os.path.normpath(f) for f in excludes] |
| 189 |
else: |
| 190 |
excludes = [] |
| 191 |
for root, dirs, files in os.walk(ns.srcdir): |
| 192 |
for rcs_dir in ('.svn', '.git', '.hg', 'build', 'externals'): |
| 193 |
if rcs_dir in dirs: |
| 194 |
dirs.remove(rcs_dir) |
| 195 |
for filename in files: |
| 196 |
# handle .c, .cpp and .h files |
| 197 |
if not filename.endswith(('.c', '.cpp', '.h')): |
| 198 |
continue |
| 199 |
path = os.path.join(root, filename) |
| 200 |
path = os.path.normpath(path) |
| 201 |
if path in excludes: |
| 202 |
continue |
| 203 |
if ns.verbose: |
| 204 |
print(path) |
| 205 |
parse_file(path, |
| 206 |
verify=not ns.force, limited_capi=ns.limited_capi) |
| 207 |
return |
| 208 |
|
| 209 |
if not ns.filename: |
| 210 |
parser.error("no input files") |
| 211 |
|
| 212 |
if ns.output and len(ns.filename) > 1: |
| 213 |
parser.error("can't use -o with multiple filenames") |
| 214 |
|
| 215 |
for filename in ns.filename: |
| 216 |
if ns.verbose: |
| 217 |
print(filename) |
| 218 |
parse_file(filename, output=ns.output, |
| 219 |
verify=not ns.force, limited_capi=ns.limited_capi) |
| 220 |
|
| 221 |
|
| 222 |
def main(argv: list[str] | None = None) -> NoReturn: |
| 223 |
parser = create_cli() |
| 224 |
args = parser.parse_args(argv) |
| 225 |
try: |
| 226 |
run_clinic(parser, args) |
| 227 |
except ClinicError as exc: |
| 228 |
sys.stderr.write(exc.report()) |
| 229 |
sys.exit(1) |
| 230 |
else: |
| 231 |
sys.exit(0) |