I discussed the high-level idea here with @DragonMinded a few months
ago, but this isn't set in stone. If people have better ideas for names,
I'd love to hear it.
Publicly-Visible Changes
------------------------
- SyntacticPositionProvider is deprecated. The new name is
PositionProvider.
- BasicPositionProvider is deprecated. The new name is
WhitespaceInclusivePositionProvider.
- Documentation is updated to better explain these renamed providers and
how to use them.
The prefixes "Syntactic" and "Basic" were pretty bad because they're
just concepts that we made up for LibCST.
The idea for the new names is that most users will want the
SyntacticPositionProvider, and so we should name things so that the user
will naturally gravitate towards the correct choice.
There's some argument that we shouldn't even bother exposing
WhitespaceInclusivePositionProvider, but we already need to implement it
as a fallback for PositionProvider, and it might be useful for some
niche use-cases.
Once we have another major version bump, we can remove the old class
names. The old class names have already be removed from the
documentation so that new users aren't tempted to use them.
Internal-Only Changes
---------------------
- `PositionProvider` is now `_PositionProviderUnion`. This type alias
was never a public API (and probably never will be).
- `BasicCodegenState` is now
`WhitespaceInclusivePositionProvidingCodegenState`.
- `SyntacticCodegenState` is now `PositionProvidingCodegenState`.
Explaining the implementation details of scopes to someone unfamiliar
with compilers can be tricky. Hopefully this helps.
- Rephrased the definition of a scope to be more applicable to Python
(remove references to "blocks"), and made it use an example for
(hopefully) better clarity.
- New scopes are also created for comprehensions.
- Set a fixed width (400px) for the scope diagram, since it was too
large before.
- Tweaked some tenses.
- Add a final call to action: "LibCST allows you to inspect these
scopes"
Add a RemoveFromParent() function as a convenience to returning RemovalSentinel.REMOVE.
Introduce a `deep_remove()` on CSTNode analogous to `deep_replace()` but for removing.
These were referred to by other parts of the documentation, and they
provide core parts of our functionality, so we should have explicit
documentation for them.
It doesn't look like we need:
- `sphinx.ext.githubpages`
- `sphinx.ext.todo`
- `sphinx.ext.mathjax`
So I removed these and then sorted the list of extensions.
This commit mostly focuses on f-strings, collections, comprehensions,
and subscripts/slices.
I added intersphinx support to the sphinx config so I could link to
`ast.literal_eval`.
I exported BaseSimpleComp, since I felt it had some documentation value.
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).
