Skip to content

Commit f1a002b

Browse files
terrencepreillyakaihola
terrencepreilly
authored and
akaihola
committed
Add high-level overview.
1 parent 16dcdae commit f1a002b

File tree

4 files changed

+157
-88
lines changed

4 files changed

+157
-88
lines changed

‎Design.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,21 @@
1-
# Design Overview
1+
## Overview
2+
3+
Below is a high level overview of darglint.
4+
5+
![High-level overview](static/Overview.png)
6+
7+
A source file is first parsed by darglint's parser (described below), and also
8+
parsed by Python's `ast` module in the wrapper class, `FunctionDefinition`.
9+
The resulting docstring AST and the `FunctionDefinition` are passed to the class,
10+
`IntegrityChecker`, which checks the integrity of the docstring against the
11+
actual function, and issues a resulting `ErrorReport`.
12+
13+
### Scheduling
14+
15+
The `IntegrityChecker` can have multiple functions passed to it from multiple
16+
files. To increase throughput, `IntegrityChecker` runs checks against the
17+
`FunctionDescription` asynchronously using a `ThreadPoolExecutor`. When
18+
`IntegrityChecker.get_error_report` is called, the async tasks are executed.
219

320
## Parsing
421

@@ -14,7 +31,7 @@ be automatically converted to CNF. Darglint's `bin/` folder contains a utility,
1431
`bnf_to_cnf` which takes a custom BNF representation and converts it to a Python
1532
source file containing grammars.
1633

17-
![Parsing Overview](static/Overview.png)
34+
![Parsing Overview](static/Parsing.png)
1835

1936
### Optimising CYK
2037

‎static/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
dotfiles = Overview.png ExampleAST.png
1+
dotfiles = Parsing.png Overview.png ExampleAST.png
22

33
all: $(dotfiles)
44

‎static/Overview.dot‎

Lines changed: 47 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,49 @@
11
digraph G {
2-
label="Darglint Parsing\n ";
3-
labelloc="top";
4-
5-
/* ============= GRAMMAR GENERATION =========================== */
6-
node [shape="rect", style="filled", fillcolor="#f5f5f5"];
7-
bnf_to_cnf [shape="none", fontcolor="#9f0000", style=""];
8-
subgraph bnf_cluster {
9-
google_arguments_section [shape="tab", label=<
10-
<table border="0" cellborder="0" cellspacing="0">
11-
<tr><td>google_arguments_grammar.bnf</td></tr>
12-
<tr><td border="1" bgcolor="#ffffff">ArgumentsGrammar</td></tr>
13-
</table>>];
14-
15-
sphinx_arguments_section [shape="tab", label=<
16-
<table border="0" cellborder="0" cellspacing="0">
17-
<tr><td>sphinx_arguments_grammar.bnf</td></tr>
18-
<tr><td border="1" bgcolor="#ffffff">ArgumentsGrammar</td></tr>
19-
</table>>];
20-
21-
dots [style="", label="...", shape="none", height="0.1", width="0.1"];
22-
}
23-
subgraph cnf_cluster {
24-
google_arguments_section1 [shape="tab", label=<
25-
<table border="0" cellborder="0" cellspacing="0">
26-
<tr><td>google_arguments_grammar.py</td></tr>
27-
<tr><td border="1" bgcolor="#ffffff">ArgumentsGrammar</td></tr>
28-
</table>>];
29-
30-
sphinx_arguments_section1 [shape="tab", label=<
31-
<table border="0" cellborder="0" cellspacing="0">
32-
<tr><td>sphinx_arguments_grammar.py</td></tr>
33-
<tr><td border="1" bgcolor="#ffffff">ArgumentsGrammar</td></tr>
34-
</table>>];
35-
36-
dots1 [style="", label="...", shape="none", height="0.1", width="0.1"];
37-
}
38-
39-
/* ============= LEXING ======================================= */
40-
node [fillcolor="#ffffff"];
41-
source [shape="tab", label="source.py"];
42-
lex [shape="none", label="lex()"];
43-
condense [shape="none", label="condense()"];
44-
45-
/* ============= PARSING ====================================== */
46-
parse [shape="none", label="parse()"];
47-
48-
BaseGrammar;
49-
Identifier;
50-
Token;
51-
CykNode;
52-
53-
// Input-Output
54-
edge [style="dashed", arrowhead="vee"];
55-
{ BaseGrammar, Token } -> parse -> CykNode;
56-
57-
_blank0 [shape="none", label="", width="0.1", height="0.1"];
58-
{ google_arguments_section, sphinx_arguments_section, dots } -> _blank0 [arrowhead="none"];
59-
_blank0 -> bnf_to_cnf;
60-
61-
_blank1 [shape="none", label="", width="0.1", height="0.1"];
62-
bnf_to_cnf -> _blank1 [arrowhead="none"];
63-
_blank1 -> {google_arguments_section1, sphinx_arguments_section1, dots1};
64-
65-
source -> lex -> condense -> Token;
66-
67-
// Is-a
68-
edge [style="solid", arrowhead="onormal"];
69-
{ dots1, google_arguments_section1, sphinx_arguments_section1 } -> BaseGrammar;
70-
// Has-a
71-
edge [dir="both", arrowhead="none", arrowtail="odiamond"];
72-
BaseGrammar -> Identifier;
73-
74-
// Association
75-
edge [style="dotted", arrowhead="none", arrowtail="none"];
76-
Identifier -> CykNode;
77-
78-
// Misc Shaping. (Delete after every addition/removal above.)
79-
80-
{
81-
rank="same";
82-
node [label="", shape="none"];
83-
edge [color="white"];
84-
// Force token to be in line with the source, lex, condense chain.
85-
Token -> empty0 -> empty1 -> empty2 -> empty3 -> BaseGrammar;
86-
}
2+
node [shape="rect"];
3+
source [label="source", shape="tab"];
4+
parse [label="Parse", shape="oval"];
5+
CykNode;
6+
Identifier;
7+
DarglintError;
8+
IntegrityChecker [shape="plaintext", label=<
9+
<table border="0" cellborder="1" cellspacing="0">
10+
<tr><td colspan="2">IntegrityChecker</td></tr>
11+
<tr>
12+
<td>
13+
<table border="0" cellborder="0" cellspacing="0">
14+
<tr>
15+
<td align="left">schedule(function: FunctionDescription):</td>
16+
<td></td>
17+
</tr>
18+
<tr>
19+
<td align="left">run_checks(function: FunctionDescription): </td>
20+
<td></td>
21+
</tr>
22+
<tr>
23+
<td align="left">get_error_report(verbosity: int, filename: str, message_template: str):</td>
24+
<td>ErrorReport</td>
25+
</tr>
26+
</table>
27+
</td>
28+
</tr>
29+
</table>
30+
>];
31+
BaseDocstring;
32+
ErrorReport;
33+
FunctionDefinition;
34+
35+
// Input/Output
36+
edge [style="dashed", arrowhead="vee"];
37+
source -> { parse, FunctionDefinition };
38+
parse -> CykNode;
39+
{ BaseDocstring, FunctionDefinition } -> IntegrityChecker -> ErrorReport;
40+
41+
42+
// Is-A
43+
edge [style="solid", arrowhead="onormal"];
44+
45+
// Has-A
46+
edge [dir="both", arrowhead="none", arrowtail="odiamond"];
47+
CykNode -> { Identifier, DarglintError };
48+
BaseDocstring -> CykNode;
8749
}

‎static/Parsing.dot‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
digraph G {
2+
label="Darglint Parsing\n ";
3+
labelloc="top";
4+
5+
/* ============= GRAMMAR GENERATION =========================== */
6+
node [shape="rect", style="filled", fillcolor="#f5f5f5"];
7+
bnf_to_cnf [shape="none", fontcolor="#9f0000", style=""];
8+
subgraph bnf_cluster {
9+
google_arguments_section [shape="tab", label=<
10+
<table border="0" cellborder="0" cellspacing="0">
11+
<tr><td>google_arguments_grammar.bnf</td></tr>
12+
<tr><td border="1" bgcolor="#ffffff">ArgumentsGrammar</td></tr>
13+
</table>>];
14+
15+
sphinx_arguments_section [shape="tab", label=<
16+
<table border="0" cellborder="0" cellspacing="0">
17+
<tr><td>sphinx_arguments_grammar.bnf</td></tr>
18+
<tr><td border="1" bgcolor="#ffffff">ArgumentsGrammar</td></tr>
19+
</table>>];
20+
21+
dots [style="", label="...", shape="none", height="0.1", width="0.1"];
22+
}
23+
subgraph cnf_cluster {
24+
google_arguments_section1 [shape="tab", label=<
25+
<table border="0" cellborder="0" cellspacing="0">
26+
<tr><td>google_arguments_grammar.py</td></tr>
27+
<tr><td border="1" bgcolor="#ffffff">ArgumentsGrammar</td></tr>
28+
</table>>];
29+
30+
sphinx_arguments_section1 [shape="tab", label=<
31+
<table border="0" cellborder="0" cellspacing="0">
32+
<tr><td>sphinx_arguments_grammar.py</td></tr>
33+
<tr><td border="1" bgcolor="#ffffff">ArgumentsGrammar</td></tr>
34+
</table>>];
35+
36+
dots1 [style="", label="...", shape="none", height="0.1", width="0.1"];
37+
}
38+
39+
/* ============= LEXING ======================================= */
40+
node [fillcolor="#ffffff"];
41+
source [shape="tab", label="source.py"];
42+
lex [shape="none", label="lex()"];
43+
condense [shape="none", label="condense()"];
44+
45+
/* ============= PARSING ====================================== */
46+
parse [shape="none", label="parse()"];
47+
48+
BaseGrammar;
49+
Identifier;
50+
DarglintError;
51+
Token;
52+
CykNode;
53+
54+
// Input-Output
55+
edge [style="dashed", arrowhead="vee"];
56+
{ BaseGrammar, Token } -> parse -> CykNode;
57+
58+
_blank0 [shape="none", label="", width="0.1", height="0.1"];
59+
{ google_arguments_section, sphinx_arguments_section, dots } -> _blank0 [arrowhead="none"];
60+
_blank0 -> bnf_to_cnf;
61+
62+
_blank1 [shape="none", label="", width="0.1", height="0.1"];
63+
bnf_to_cnf -> _blank1 [arrowhead="none"];
64+
_blank1 -> {google_arguments_section1, sphinx_arguments_section1, dots1};
65+
66+
source -> lex -> condense -> Token;
67+
68+
// Is-a
69+
edge [style="solid", arrowhead="onormal"];
70+
{ dots1, google_arguments_section1, sphinx_arguments_section1 } -> BaseGrammar;
71+
// Has-a
72+
edge [dir="both", arrowhead="none", arrowtail="odiamond"];
73+
BaseGrammar -> Identifier;
74+
BaseGrammar -> DarglintError;
75+
76+
// Association
77+
edge [style="dotted", arrowhead="none", arrowtail="none"];
78+
Identifier -> CykNode;
79+
DarglintError -> CykNode;
80+
81+
// Misc Shaping. (Delete after every addition/removal above.)
82+
83+
{
84+
rank="same";
85+
node [label="", shape="none"];
86+
edge [color="white"];
87+
// Force token to be in line with the source, lex, condense chain.
88+
Token -> empty0 -> empty1 -> empty2 -> empty3 -> BaseGrammar;
89+
}
90+
}

0 commit comments

Comments
 (0)