Skip to content

Commit 53785fc

Browse files
steve-ssteve-s
committed
[GR-25518] Argument clinic for GraalPython.
PullRequest: graalpython/1232
2 parents 334ac94 + 579a734 commit 53785fc

File tree

65 files changed

+2695
-413
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+2695
-413
lines changed

‎docs/contributor/CONTRIBUTING.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,13 @@ that library. If something is missing that is commonly used, we probably have
8686
some Node for it, but it may be a good idea to add it to the
8787
`PythonObjectLibrary` for easier discovery.
8888

89+
GraalPython has its own variant of the argument clinic preprocessor. It is
90+
activated by: extending `PythonXXXClinicBuiltinNode` (e.g.,
91+
`PythonBinaryClinicBuiltinNode`), using `@ArgumentClinic` annotations
92+
on the builtin node class, and overriding the `getArgumentClinic` method
93+
to return the class that will be generated from the annotations (it will be
94+
named the same as the node class plus `ClinicProviderGen` suffix).
95+
8996
Sometimes, you will not easily find what exactly happens for a given piece of
9097
code when that involves more than just a simple built-in call. The `dis` module
9198
on CPython can often help get an angle on what a particular piece of code is

‎graalpython/com.oracle.graal.python.annotations/src/com/oracle/graal/python/annotations/ArgumentClinic.java

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
/*
2+
* Copyright (c) 2020, 2020, Oracle and/or its affiliates. All rights reserved.
3+
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* The Universal Permissive License (UPL), Version 1.0
6+
*
7+
* Subject to the condition set forth below, permission is hereby granted to any
8+
* person obtaining a copy of this software, associated documentation and/or
9+
* data (collectively the "Software"), free of charge and under any and all
10+
* copyright rights in the Software, and any and all patent rights owned or
11+
* freely licensable by each licensor hereunder covering either (i) the
12+
* unmodified Software as contributed to or provided by such licensor, or (ii)
13+
* the Larger Works (as defined below), to deal in both
14+
*
15+
* (a) the Software, and
16+
*
17+
* (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
18+
* one is included with the Software each a "Larger Work" to which the Software
19+
* is contributed by such licensors),
20+
*
21+
* without restriction, including without limitation the rights to copy, create
22+
* derivative works of, display, perform, and distribute the Software and make,
23+
* use, sell, offer for sale, import, export, have made, and have sold the
24+
* Software and the Larger Work(s), and to sublicense the foregoing rights on
25+
* either these or other terms.
26+
*
27+
* This license is subject to the following condition:
28+
*
29+
* The above copyright notice and either this complete permission notice or at a
30+
* minimum a reference to the UPL must be included in all copies or substantial
31+
* portions of the Software.
32+
*
33+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
34+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
35+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
36+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
37+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
38+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
39+
* SOFTWARE.
40+
*/
41+
package com.oracle.graal.python.annotations;
42+
43+
import java.lang.annotation.ElementType;
44+
import java.lang.annotation.Repeatable;
45+
import java.lang.annotation.Target;
46+
47+
@Target(ElementType.TYPE)
48+
@Repeatable(value = ArgumentsClinic.class)
49+
public @interface ArgumentClinic {
50+
/**
51+
* Name of the argument. It must match one of the argument names specified in the
52+
* {@code Builtin} annotation.
53+
*/
54+
String name();
55+
56+
/**
57+
* Specifies a predefined conversion routine to use. Other fields of this annotation specify
58+
* configuration for the conversion routine. Note that not all routines support all the
59+
* configuration options.
60+
*
61+
* Conversion routines are implemented in {@code ArgumentClinicModel#BuiltinConvertor}. It
62+
* creates Java code snippets that instantiate the actual cast nodes, which should implement
63+
* {@code ArgumentCastNode}.
64+
*/
65+
ClinicConversion conversion() default ClinicConversion.None;
66+
67+
/**
68+
* Overrides the {@link #conversion()} value. Name of a method of the builtin class that should
69+
* be used as a factory to create the conversion node. When this value is set, then other
70+
* conversion options are ignored.
71+
*/
72+
String customConversion() default "";
73+
74+
/**
75+
* The boxing optimized execute method variants will not attempt to cast the listed primitive
76+
* types and will just pass them directly to the specializations. This does not apply to
77+
* primitive values that are already boxed: those are always passed to the convertor.
78+
*
79+
* It is not necessary to set this when using a builtin conversion. Built-in convertors provide
80+
* their own list of short circuit types, which is applied if this field is set to its default
81+
* value.
82+
*/
83+
PrimitiveType[] shortCircuitPrimitive() default {};
84+
85+
/**
86+
* The string should contain valid Java constant value expression, for example, {@code true}, or
87+
* {@code \"some string\"}. You may have to update the annotation processor to include import of
88+
* necessary packages or use fully qualified names.
89+
*/
90+
String defaultValue() default "";
91+
92+
/**
93+
* Whether to use the default value also for {@code PNone.NONE} values. Otherwise, it is used
94+
* only for {@code PNone.NO_VALUE}.
95+
*/
96+
boolean useDefaultForNone() default false;
97+
98+
enum PrimitiveType {
99+
Boolean,
100+
Int,
101+
Long,
102+
Double,
103+
}
104+
105+
enum ClinicConversion {
106+
/**
107+
* No builtin convertor will be used.
108+
*/
109+
None,
110+
/**
111+
* Corresponds to CPython's {@code bool} convertor. Supports {@link #defaultValue()}.
112+
* {@code PNone.NONE} is, for now, always converted to {@code false}.
113+
*/
114+
Boolean,
115+
/**
116+
* GraalPython specific convertor that narrows any String representation to Java String.
117+
* Supports {@link #defaultValue()}, and {@link #useDefaultForNone()}.
118+
*/
119+
String,
120+
/**
121+
* Corresponds to CPython's {@code int} convertor. Supports {@link #defaultValue()}, and
122+
* {@link #useDefaultForNone()}.
123+
*/
124+
Int,
125+
/**
126+
* Corresponds to CPython's {@code Py_ssize_t} convertor. Supports {@link #defaultValue()},
127+
* and {@link #useDefaultForNone()}.
128+
*/
129+
Index,
130+
}
131+
}

‎graalpython/com.oracle.graal.python.annotations/src/com/oracle/graal/python/annotations/ArgumentsClinic.java

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
/*
2+
* Copyright (c) 2020, 2020, Oracle and/or its affiliates. All rights reserved.
3+
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* The Universal Permissive License (UPL), Version 1.0
6+
*
7+
* Subject to the condition set forth below, permission is hereby granted to any
8+
* person obtaining a copy of this software, associated documentation and/or
9+
* data (collectively the "Software"), free of charge and under any and all
10+
* copyright rights in the Software, and any and all patent rights owned or
11+
* freely licensable by each licensor hereunder covering either (i) the
12+
* unmodified Software as contributed to or provided by such licensor, or (ii)
13+
* the Larger Works (as defined below), to deal in both
14+
*
15+
* (a) the Software, and
16+
*
17+
* (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
18+
* one is included with the Software each a "Larger Work" to which the Software
19+
* is contributed by such licensors),
20+
*
21+
* without restriction, including without limitation the rights to copy, create
22+
* derivative works of, display, perform, and distribute the Software and make,
23+
* use, sell, offer for sale, import, export, have made, and have sold the
24+
* Software and the Larger Work(s), and to sublicense the foregoing rights on
25+
* either these or other terms.
26+
*
27+
* This license is subject to the following condition:
28+
*
29+
* The above copyright notice and either this complete permission notice or at a
30+
* minimum a reference to the UPL must be included in all copies or substantial
31+
* portions of the Software.
32+
*
33+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
34+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
35+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
36+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
37+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
38+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
39+
* SOFTWARE.
40+
*/
41+
package com.oracle.graal.python.annotations;
42+
43+
import java.lang.annotation.ElementType;
44+
import java.lang.annotation.Target;
45+
46+
@Target(ElementType.TYPE)
47+
public @interface ArgumentsClinic {
48+
ArgumentClinic[] value();
49+
}

‎graalpython/com.oracle.graal.python.processor/src/META-INF/services/javax.annotation.processing.Processor

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
com.oracle.graal.python.processor.ArgumentClinicProcessor

0 commit comments

Comments
 (0)