Problems with OFFLINE+ conversion (mistune) about github-flavored-markdown-to-html

[phseiff]

Also something like this would perhaps prevent some errors, too:

# core_converter.py
try:
    import mistune
except ImportError:
    raise Exception('OFFLINE conversion needs "mistune" package >= 2.0.0rc1!\n\trun: pip install mistune>=2.0.0rc1')

This might also be a good idea, since it softens the user's realization process from
conversion fails -> install mistune -> still fails -> install mistune>=2.0.0rc1
to
conversion fails -> install mistune>=2.0.0rc1

[phseiff]

To be honest I actually did not understand the wording in

                        md-to-html-converter using mistune. This requires the
                        optional dependencies for "offline_conversion" to be   <-----
                        satisfied.

until now, when I saw the contents of the setup.py. Something like

This requires the gh-md-to-html to be installed with the optional 
offline_conversion dependencies; you have to install gh-md-to-html with 
"pip install gh-md-to-html[offline_conversion]", or install the requirements 
(e.g. mistune) manually.

maybe? :)

That might be a good idea, especially since many people might use gh-md-to-html from its command line interface and therefore not be native in the Python ecosystem. I will probably go with something like

                        * OFFLINE as a value to indicate that gh-md-to-html
                        should imitate the output of their builtin
                        md-to-html-converter using mistune. This requires the
                        optional dependencies for "offline_conversion" to be
                        satisfied (`pip3 install gh-md-to-html[offline_conversion]`),
                        or "mistune>=v2.0.0rc1" to be installed manually.

[phseiff]

I made a new release (v1.7.1) which should fix the things you mentioned.
Thanks again for pointing them out to me!

[phseiff]

Hi, and thanks for telling me about this issue!

Did you try out OFFLINE, and did you encounter the same problem when doing so?
EDIT: I just looked at the code, and it appears the issue arises no matter whether one uses OFFLINE or OFFLINE+.

I wasn't aware I had this specific version of mistune installed, and just assumed I had the newest version from PyPi installed. I probably installed it from their GitHub repository, since they have a somewhat strange release scheme on PyPi (no new major version for a long time). Their documentation is, to my awareness, also up to date with v2.0.2rc1 rather than the old 0.8 version.

Maybe it would be worth mentioning in the REAME?

That would probably be one way to fix this, but I can also specify the version to use in setup.py, by changing this line from

    extras_require={
        'pdf_export': ["pdfkit"],
        'offline_conversion': ["mistune", "pygments"]
    },

to

    extras_require={
        'pdf_export': ["pdfkit"],
        'offline_conversion': ["mistune>=2.0.0rc1", "pygments"]
    },

so the correct version is used in any case.

[phseiff]

I subscribed to new mistune releases now, so I will be notified when v2.0.2rc1 become v2.0.whatever and I will test whether the feature still works when v2.0 when it comes out, to be sure that v2.0 does not remove the features of v2.0.2rc1 that gh-md-to-html depends on.

I will change the dependency to "mistune>=2.0.0rc1" sometime around this evening.

[fohrloop]

Yeah I think changing the requirement in the setup.py is a good idea. I did not install the gh-md-to-html with the [offline_conversion] flag, but afterwards installed mistune manually when I figured out it is needed. I think it would be perhaps good to add a check in core_converter.py with:

from pkg_resources import packaging 
from pkg_resources import get_distribution

parse = packaging.version.parse

if not parse(get_distribution('mistune').version) >= parse('2.0.0rc1'):
    raise Exception('"mistune" package version should be >= 2.0.0rc1')

or to have a regular try .. except when trying to import from mistune.scanner import escape_html. This way users that install mistune manually would get helpful error message, rather than the cryptic

ModuleNotFoundError: No module named 'mistune.scanner'; 'mistune' is not a package

[phseiff]

That would probably be a good idea (and also, I could also mention this in the help text, by changing

                        * OFFLINE as a value to indicate that gh-md-to-html
                        should imitate the output of their builtin
                        md-to-html-converter using mistune. This requires the
                        optional dependencies for "offline_conversion" to be
                        satisfied.

to

                        * OFFLINE as a value to indicate that gh-md-to-html
                        should imitate the output of their builtin
                        md-to-html-converter using mistune. This requires the
                        optional dependencies for "offline_conversion" to be
                        satisfied, or "mistune>=v2.0.0rc1" to be installed
                        manually.

)

[fohrloop]

Also something like this would perhaps prevent some errors, too:

# core_converter.py
try:
    import mistune
except ImportError:
    raise Exception('OFFLINE conversion needs "mistune" package >= 2.0.0rc1!\n\trun: pip install mistune>=2.0.0rc1')

[fohrloop]

To be honest I actually did not understand the wording in

                        md-to-html-converter using mistune. This requires the
                        optional dependencies for "offline_conversion" to be   <-----
                        satisfied.

until now, when I saw the contents of the setup.py. Something like

This requires the gh-md-to-html to be installed with the optional 
offline_conversion dependencies; you have to install gh-md-to-html with 
"pip install gh-md-to-html[offline_conversion]", or install the requirements 
(e.g. mistune) manually.

maybe? :)

[phseiff]

The mistune GitHub repository also mentions that one should install mistune as mistune==2.0.0rc1, so 2.0.0rc appears to be considered a staple version.