Breaking changes / docs out of date

[akissinger]

Describe the bug

After updated from Lark 1.1.5 to 1.1.7, the parser fails with (at least) two problems. These seem to be due to a rename of ParseTree to Tree (contrary to the docs e.g. on parse: https://lark-parser.readthedocs.io/en/stable/classes.html#lark.Lark.parse) and a re-ordering of v_args in the Transformer methods to no longer match what's documented here:

https://lark-parser.readthedocs.io/en/stable/visitors.html#v-args

Also, the docs don't seem to have been building for the past few weeks:

https://readthedocs.org/projects/lark-parser/builds/

To Reproduce

Write a transformer with something like this:

@v_args(meta=True)
def term_ref(self, meta: Meta, items: List[Any]) -> Any:
    s = str(items[0])

and it will fail by saying Meta object not subscriptable. This works fine in 1.1.5, but it looks like 1.1.7 expects this instead:

@v_args(meta=True)
def term_ref(self, items: List[Any], meta: Meta) -> Any:
    s = str(items[0])

[MegaIng]

Considering that v_args(meta=True) is being tested with the order meta, items, and those tests still pass, I don't think that changed:

lark/tests/test_trees.py

Line 209 in ba5ae31

def ab_method(self, meta, children):

Not sure what you mean with the rename?

Are you sure you are actually looking at 1.1.7? Both of these changes are stuff from pre-1.0.0

[akissinger]

Having uninstalled 1.1.5 and installed 1.1.7 again, I can't reproduce the argument order problem, so maybe something funny happened with my pip version locally. If that's the case, the only problems seem to be the reference to ParseTree here: https://lark-parser.readthedocs.io/en/stable/classes.html#lark.Lark.parse (n.b. this is listed as the return type of parse, but it seems to be called Tree now) and the fact that the docs aren't building on ReadTheDocs.

[MegaIng]

No, ParseTree is correct there. It's an alias for Tree['Token'].

[akissinger]

Ah! I found it. I had this (I guess defunct?) package installed in my global site_packages:

https://pypi.org/project/lark-parser/

It's a bit confusing that the readthedocs project is called lark-parser but on pypi its lark. I guess this is because lark was already taken. I don't know if it's possible/desirable to take the pypi lark-parser offline, or at least warn people not to use it.

[erezsh]

I don't want to take lark-parser offline from pypi, because it might break existing projects that use an old version. However, we don't publish any new packages there. What sort of warning do you think I should place, and where?

Yes, https://lark.readthedocs.io/ is occupied by an unmaintained project.

@MegaIng IIRC he willingly relinquished lark on PyPI. Perhaps we can ask him to do the same with readthedocs?

[MegaIng]

Yeah, we should ask.

[akissinger]

Perhaps you could publish a final version under lark-parser that either issues a deprecation warning whenever the module is imported or is just a stub depending on the latest version of lark. There seem to be some reasonable suggestions in this article:

https://www.dampfkraft.com/code/how-to-deprecate-a-pypi-package.html

People should be able to keep the old behaviour if they depend on lark-parser==0.12.0.