Unexpected keyword argument 'default_semicolon' when attempting to use FlattenSentinel

[jakemwood]

Hello!

I have the following minimum reproducible example of this error:

from typing import Union
import libcst
from libcst import Decorator, Arg, Name, SimpleString, FlattenSentinel, RemovalSentinel, AssignEqual, SimpleWhitespace, \
    BaseSmallStatement, Assign, AssignTarget

statement_a = libcst.parse_module("x = 12 + 23")
statement_b = libcst.parse_module("y = 24 + 12")


class ExampleTransformer(libcst.CSTTransformer):
    def leave_Assign(
            self, original_node: "Assign", updated_node: "Assign"
    ) -> Union[
        "BaseSmallStatement", FlattenSentinel["BaseSmallStatement"], RemovalSentinel
    ]:
        return FlattenSentinel((updated_node, statement_b))


results = statement_a.visit(ExampleTransformer())

print(results.code)

If I am understanding the documentation of FlattenSentinel correctly, I would expect results.code to output something like...

x = 12 + 23
y = 24 + 12

Of course this is a simpler view of what I'm trying to do, which is adding a node after a node (aka attempting to insert an adjacent node after leaving a node).

However, it does not work, and instead produces this stack trace:

Traceback (most recent call last):
  File "/Users/jake/.pyenv/versions/3.10.0/lib/python3.10/contextlib.py", line 153, in __exit__
    self.gen.throw(typ, value, traceback)
  File "/Users/jake/Library/Caches/pypoetry/virtualenvs/service-migrations-gjE7jW9P-py3.10/lib/python3.10/site-packages/libcst/_nodes/internal.py", line 70, in record_syntactic_position
    yield
  File "/Users/jake/Library/Caches/pypoetry/virtualenvs/service-migrations-gjE7jW9P-py3.10/lib/python3.10/site-packages/libcst/_nodes/statement.py", line 404, in _codegen_impl
    stmt._codegen(state, default_semicolon=(idx != laststmt))
  File "/Users/jake/Library/Caches/pypoetry/virtualenvs/service-migrations-gjE7jW9P-py3.10/lib/python3.10/site-packages/libcst/_nodes/base.py", line 301, in _codegen
    self._codegen_impl(state, **kwargs)
TypeError: Module._codegen_impl() got an unexpected keyword argument 'default_semicolon'

Is there a better way to accomplish my goal, or is this a bona fide bug? Thank you!

[jakemwood]

Going to close this. I played around with this a bit more and I think this is a misunderstanding on my part from the documentation.

[zsol]

Is there anything we can do to make the docs clearer?

[jakemwood]

I think it would be helpful to show an example that the FlattenSentinel actually combines two statements into line of code and separates them with a semi-colon. The documentation here reads: For example to insert a print **before** every return: To me, the "before" implies that it would insert a new line. Unfortunately I think both interpretations of the sentence are correct, so a clarifying example of the output from the code sample in the docs would be really useful.

What helped me was this Stack Overflow post. It makes total sense that the FlattenSentinel just needs to be used higher in the tree that I'd previously expected in order to accomplish my goal.