Skip to content

Commit bd353e3

Browse files
loechelloechel
authored
Add documentation about contributing (#240)
* Add documentation about contributing * more explicite explaination on how to add a new AST Node element
1 parent 695f8f6 commit bd353e3

File tree

5 files changed

+457
-52
lines changed

5 files changed

+457
-52
lines changed

‎README.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,3 +78,8 @@ This example directly executed in Python could harm your system.
7878
>>> exec(byte_code, safe_globals, {})
7979
Traceback (most recent call last):
8080
ImportError: __import__ not found
81+
82+
Contributing to RestrictedPython
83+
--------------------------------
84+
85+
If you want to help maintain RestrictedPython and contribute, please refere to `Contributing <https://restrictedpython.readthedocs.io/en/latest/contributing/index.html>`.

‎docs/conf.py

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@
4848
# General information about the project.
4949
project = 'RestrictedPython'
5050
copyright = '2017-2022, Zope Foundation and Contributors'
51-
author = 'The Zope developer community'
51+
author = 'The Zope & Plone developer community'
5252

5353
# The version info for the project you're documenting, acts as replacement for
5454
# |version| and |release|, also used in various other places throughout the
@@ -64,7 +64,7 @@
6464
#
6565
# This is also used if you do content translation via gettext catalogs.
6666
# Usually you set "language" from the command line for these cases.
67-
language = None
67+
language = 'en'
6868

6969
# There are two options for replacing |today|: either, you set today to some
7070
# non-false value, then it is used:
@@ -113,6 +113,10 @@
113113
'python36': ('https://docs.python.org/3.6', None),
114114
'python37': ('https://docs.python.org/3.7', None),
115115
'python38': ('https://docs.python.org/3.8', None),
116+
'python39': ('https://docs.python.org/3.9', None),
117+
'python310': ('https://docs.python.org/3.10', None),
118+
'python311': ('https://docs.python.org/3.11', None),
119+
'python312': ('https://docs.python.org/3.12', None),
116120
}
117121

118122
# Options for sphinx.ext.todo:
@@ -239,8 +243,13 @@
239243
# (source start file, target name, title,
240244
# author, documentclass [howto, manual, or own class]).
241245
latex_documents = [
242-
(master_doc, 'RestrictedPython.tex', 'RestrictedPython Documentation',
243-
'Alexander Loechel', 'manual'),
246+
(
247+
master_doc,
248+
'RestrictedPython.tex',
249+
'RestrictedPython Documentation',
250+
author,
251+
'manual',
252+
),
244253
]
245254

246255
# The name of an image file (relative to this directory) to place at the top of
@@ -269,8 +278,7 @@
269278
# One entry per manual page. List of tuples
270279
# (source start file, name, description, authors, manual section).
271280
man_pages = [
272-
(master_doc, 'restrictedpython', 'RestrictedPython Documentation',
273-
[author], 1)
281+
(master_doc, 'restrictedpython', 'RestrictedPython Documentation', [author], 1)
274282
]
275283

276284
# If true, show URL addresses after external links.
@@ -283,9 +291,15 @@
283291
# (source start file, target name, title, author,
284292
# dir menu entry, description, category)
285293
texinfo_documents = [
286-
(master_doc, 'RestrictedPython', 'RestrictedPython Documentation',
287-
author, 'RestrictedPython', 'One line description of project.',
288-
'Miscellaneous'),
294+
(
295+
master_doc,
296+
'RestrictedPython',
297+
'RestrictedPython Documentation',
298+
author,
299+
'RestrictedPython',
300+
'One line description of project.',
301+
'Miscellaneous',
302+
),
289303
]
290304

291305
# Documents to append as an appendix to all manuals.

‎docs/contributing/ast/python3_12.ast

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
-- Python 3.12 AST
2+
-- ASDL's 4 builtin types are:
3+
-- identifier, int, string, constant
4+
5+
module Python version "3.12"
6+
{
7+
mod = Module(stmt* body, type_ignore* type_ignores)
8+
| Interactive(stmt* body)
9+
| Expression(expr body)
10+
| FunctionType(expr* argtypes, expr returns)
11+
12+
stmt = FunctionDef(identifier name,
13+
arguments args,
14+
stmt* body,
15+
expr* decorator_list,
16+
expr? returns,
17+
string? type_comment)
18+
| AsyncFunctionDef(identifier name,
19+
arguments args,
20+
stmt* body,
21+
expr* decorator_list,
22+
expr? returns,
23+
string? type_comment)
24+
25+
| ClassDef(identifier name,
26+
expr* bases,
27+
keyword* keywords,
28+
stmt* body,
29+
expr* decorator_list)
30+
| Return(expr? value)
31+
32+
| Delete(expr* targets)
33+
| Assign(expr* targets, expr value, string? type_comment)
34+
| AugAssign(expr target, operator op, expr value)
35+
-- 'simple' indicates that we annotate simple name without parens
36+
| AnnAssign(expr target, expr annotation, expr? value, int simple)
37+
38+
-- use 'orelse' because else is a keyword in target languages
39+
| For(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
40+
| AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
41+
| While(expr test, stmt* body, stmt* orelse)
42+
| If(expr test, stmt* body, stmt* orelse)
43+
| With(withitem* items, stmt* body, string? type_comment)
44+
| AsyncWith(withitem* items, stmt* body, string? type_comment)
45+
46+
| Match(expr subject, match_case* cases)
47+
48+
| Raise(expr? exc, expr? cause)
49+
| Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
50+
| TryStar(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
51+
| Assert(expr test, expr? msg)
52+
53+
| Import(alias* names)
54+
| ImportFrom(identifier? module, alias* names, int? level)
55+
56+
| Global(identifier* names)
57+
| Nonlocal(identifier* names)
58+
| Expr(expr value)
59+
| Pass
60+
| Break
61+
| Continue
62+
63+
-- col_offset is the byte offset in the utf8 string the parser uses
64+
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
65+
66+
-- BoolOp() can use left & right?
67+
expr = BoolOp(boolop op, expr* values)
68+
| NamedExpr(expr target, expr value)
69+
| BinOp(expr left, operator op, expr right)
70+
| UnaryOp(unaryop op, expr operand)
71+
| Lambda(arguments args, expr body)
72+
| IfExp(expr test, expr body, expr orelse)
73+
| Dict(expr* keys, expr* values)
74+
| Set(expr* elts)
75+
| ListComp(expr elt, comprehension* generators)
76+
| SetComp(expr elt, comprehension* generators)
77+
| DictComp(expr key, expr value, comprehension* generators)
78+
| GeneratorExp(expr elt, comprehension* generators)
79+
-- the grammar constrains where yield expressions can occur
80+
| Await(expr value)
81+
| Yield(expr? value)
82+
| YieldFrom(expr value)
83+
-- need sequences for compare to distinguish between
84+
-- x < 4 < 3 and (x < 4) < 3
85+
| Compare(expr left, cmpop* ops, expr* comparators)
86+
| Call(expr func, expr* args, keyword* keywords)
87+
| FormattedValue(expr value, int conversion, expr? format_spec)
88+
| JoinedStr(expr* values)
89+
| Constant(constant value, string? kind)
90+
91+
-- the following expression can appear in assignment context
92+
| Attribute(expr value, identifier attr, expr_context ctx)
93+
| Subscript(expr value, expr slice, expr_context ctx)
94+
| Starred(expr value, expr_context ctx)
95+
| Name(identifier id, expr_context ctx)
96+
| List(expr* elts, expr_context ctx)
97+
| Tuple(expr* elts, expr_context ctx)
98+
99+
-- can appear only in Subscript
100+
| Slice(expr? lower, expr? upper, expr? step)
101+
102+
-- col_offset is the byte offset in the utf8 string the parser uses
103+
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
104+
105+
expr_context = Load
106+
| Store
107+
| Del
108+
109+
boolop = And
110+
| Or
111+
112+
operator = Add
113+
| Sub
114+
| Mult
115+
| MatMult
116+
| Div
117+
| Mod
118+
| Pow
119+
| LShift
120+
| RShift
121+
| BitOr
122+
| BitXor
123+
| BitAnd
124+
| FloorDiv
125+
126+
unaryop = Invert
127+
| Not
128+
| UAdd
129+
| USub
130+
131+
cmpop = Eq
132+
| NotEq
133+
| Lt
134+
| LtE
135+
| Gt
136+
| GtE
137+
| Is
138+
| IsNot
139+
| In
140+
| NotIn
141+
142+
comprehension = (expr target, expr iter, expr* ifs, int is_async)
143+
144+
excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)
145+
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
146+
147+
arguments = (arg* posonlyargs,
148+
arg* args,
149+
arg? vararg,
150+
arg* kwonlyargs,
151+
expr* kw_defaults,
152+
arg? kwarg,
153+
expr* defaults)
154+
155+
arg = (identifier arg, expr? annotation, string? type_comment)
156+
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
157+
158+
-- keyword arguments supplied to call (NULL identifier for **kwargs)
159+
keyword = (identifier? arg, expr value)
160+
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
161+
162+
-- import name with optional 'as' alias.
163+
alias = (identifier name, identifier? asname)
164+
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
165+
166+
withitem = (expr context_expr, expr? optional_vars)
167+
168+
match_case = (pattern pattern, expr? guard, stmt* body)
169+
170+
pattern = MatchValue(expr value)
171+
| MatchSingleton(constant value)
172+
| MatchSequence(pattern* patterns)
173+
| MatchMapping(expr* keys, pattern* patterns, identifier? rest)
174+
| MatchClass(expr cls, pattern* patterns, identifier* kwd_attrs, pattern* kwd_patterns)
175+
176+
| MatchStar(identifier? name)
177+
-- The optional "rest" MatchMapping parameter handles capturing extra mapping keys
178+
179+
| MatchAs(pattern? pattern, identifier? name)
180+
| MatchOr(pattern* patterns)
181+
182+
attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
183+
184+
type_ignore = TypeIgnore(int lineno, string tag)
185+
}

‎docs/contributing/changes_from311to312.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Changes from Python 3.11 to Python 3.12
2+
---------------------------------------
3+
4+
.. literalinclude:: ast/python3_12.ast
5+
:diff: ast/python3_11.ast

0 commit comments

Comments
 (0)