simplify the API

[mgaitan]

Dmitry, in first place, let me say that this project could be very useful for many people.

However, I don't understand (or like?) the current API. Let me show what it's an obvious use pattern for me:

In [40]: !cat test.rst
* Hey
* I'm a restructuredtextfile
In [38]: markup =  markups.get_markup_for_file_name("test.rst")
Out[38]: <markups.restructuredtext.ReStructuredTextMarkup at 0x7f9dad301310>
In [39]: markup.get_document_body()
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
<ipython-input-39-71c6c4c0bcf0> in <module>()
----> 1 markup.get_document_body()

TypeError: get_document_body() missing 1 required positional argument: 'text'

Every markup method (to get body, title, etc,) needs the document source as parameter, which is too verbose and (IMHO) not DRY. Why not to read the content of the given filename/path and store it as an instance attribute?

I would like that the mandatory parameter be a path (or a file-handler like object) or the raw source content. For example:

text = """* Hey
* I'm a restructuredtextfile
"""
In [41]: markup =  markups.ReStructuredTextMarkup(text)   # or markups.get_markup(text, markup='rst')
Out[41]: <markups.restructuredtext.ReStructuredTextMarkup at 0x7f9dad301310>
In [42]: markup.get_document_body()
Out[42]'<ul class="simple">\n<li>Hey</li>\n<li>I\'m a restructuredtextfile</li>\n</ul>\n'

let me know what do you think. I'll be glad to send a PR if you are interested

[mitya57]

Hi,

As you probably know, I wrote pymarkups library with ReText in mind, and ReText is the main consumer of this library.

In ReText, there is a file name associated with a document, but the text of the document does not necessarily match the file contents. For example, user can open a file, change something and click "Preview", then change something again and click "Preview" again. Because of this,

• PyMarkups does not read text from file. It leaves it to the application to do that. The file name is only used to guess the format (using the file extension).
• I don't see any point in storing text in markup itself. Your app probably stores the text anyway, so why have two copies?
• Creating a new instance of markup object every time the text changes seems too expensive for me,

That said, you should probably fork this library for yourself if you want a different behaviour. I can also accept pull requests, but they should not break compatibility with the current version or have worse performance.