Fixed Why LibCST printed example as it was out of date.
Unrolled README example into Why LibCST section to decouple since this page explicitly uses "fn(1, 2)" snippet and the readme is going to change.
Added justification and pros/cons to LibCST.
Added graphviz to render the non-default parts of LibCST tree (identical to how we render non-default parts of the AST).
We pass down the correct default annotation indicator to use in 100% of code rendering places, so this becomes a useless bit of initialization. We already set this to a sentinel by default, and the only thing that having an explicit str gives us is the inability to copy an annotation from a param to a return or vice versa. So, out it goes. This means we can't render Annotation by itself, so the test that was using this behavior is out too.
I haven't gone through every expression and cleaned it up yet, but I
have completed the `Names and Object Attributes`, `Operations and
Comparisons`, `Control Flow`, and `Lambda and Function Calls` sections,
as well as part of the `Literal Values` section.
As written, this makes it a type-checker error if you pass in a value of
other that doesn't match the type of the node you're checking against.
If you want to ask a generic question similar to 'Does this equal
Node("True")', you can't use this function. It calls into a helper that
allows for (and checks as a base case) different types to be passed in,
so lets loosen types here to make this useful.
This adds a __repr__ to various types in the parser config, so that the
generated documentation for functions using these types renders easier
to read.
Groups the expression nodes into much smaller subcategories for improved
readablility.
Some nodes defined in the expression module were grouped with statements
because they made more sense there (from a documentation perspective).
This also adds a local table of contents to the top of the nodes page
which better reveals all of the subcategories.
It also exports and categorizes
`BaseAssignTargetExpression`/`BaseDelTargetExpression`. These nodes were
referenced in type annotations of other nodes, so they need to be
exported if only for documentation reasons.
Removes the leading dot in node references (due to a misunderstanding I had), and uses tilde-based prefixes for restructured text references for consistency with the rest of the docs.
I added this originally because it's part of Python's grammar, but since
we merged parenthesis and friends into expressions instead of forming
separate nodes, BaseAtom doesn't have much use.
This fixes also a few bugs:
- A decorator requires a `dotted_name`, so it can only take a `Name` or
an `Attribute` node, not any atom.
- A `Call` node's function can be any expression, not just a fixed list
of `BaseExpression` subclasses.
This finishes the parser! 🎉
A few related changes were made:
- `DummyNode` was removed, as it's no longer needed.
- `lpar`/`rpar` was removed from `StarredDictElement`, because I found
out that it's not valid syntax while developing the parsing logic.
- Now that we're exporting everything from the top-level libcst package,
automodule makes a mess of things.
- While it does create more boilerplate, using autoclass/autofunction
instead of automodule gives us a lot more control over the order in
which nodes are presented, so we can group them by various categories.
This diff also exports BaseParenthesizableWhitespace, because nodes
refer to it by type, and so it's needed for documentation purposes.
