Add docs about (minimal) public API

[z0u]

I use scour as a module in a web app. Previously, I was doing this:

    opts = scour.parse_args(args=[...])[0]
    output = scour.scourString(svg, opts)

But that fails in version 0.35, because parse_args now returns a single object instead of a tuple. The fix is easy; however, it would be nice to have a public API that would remain stable for a given major version number.

[Ede123]

Yes, this is definitely something we want to offer.

To be able to assess this better:

• What would you need/expect from a public API?
• What's your usage scenario that makes you call parse_args() directly? I'd considered this function more or less private since I suspected argument handling is something every Python program does on its own...

My thoughts on what a minimal API should offer at least:

• I guess something equivalent to scourString() is essential, probably we could also expose scourXmlFile()
• For generating an options object we currently have generateDefaultOptions() and sanitizeOptions(). I'd suggest to expose something in the API that's basically a merged version of those two (i.e. a function that can be called without arguments to generate default options or with an existing options object to sanitize them).

[Ede123]

I just created #121. Does this sound reasonable to you guys?

Any complaints @oberstet? Seems these are the parts that are less well documented in the Python world, but the current state looks quite workable from a usability point of view.

[z0u]

Hi @Ede123, thanks for that - yes, that would suit our purposes very well.

What's your usage scenario that makes you call parse_args() directly?

Simply to get an options object; I had just mimicked the operation of run. I didn't know about generateDefaultOptions.

What would you need/expect from a public API?

Your suggestions are fine, and suit us well. The only thing I'd add is it's sometimes nice to have a builder-like API - but don't go to the effort of implementing it on my behalf, because I don't need it:

options = options().with_quiet(True)

[oberstet]

Here is a proposal for a public API in Python 3 type annotated syntax:

from typing import Optional

def create_options(options: Optional[dict]) -> dict:
    """
    Returns a dictionary including attributes for all Scour options, either set to
    (normalized) values from the input options, or set to default values.
    The dictionary is JSON serializable (it only contains simple, serializable types).

    :param options: Any input options to be set.
    :returns: A complete set of options for use with.
    """

def scour_string(doc: str, options: Optional[dict]) -> str
    """
    Clean the SVG given in the string and return the clean SVG. The options must be
    created from `create_options()`.

    :param doc: The SVG document content to optimize.
    :returns: The optimized SVG document content.
    """

[ewerybody]

Oh Hi! Was there any news?

I was also looking for a module way of using scour as there is nothing advertised in the readme. So far I did this:

from scour import scour
options = scour.parse_args()
options.infilename = in_path
options.outfilename = out_path

in_file, out_file = scour.getInOut(options)
scour.start(options, in_file, out_file)

I like the option object a lot already! So I was wondering if it could be available from /scour/__init__.py? Oooops. I see 🙊 already done. kind of. Well I'd offer an explicit function for dictionary input in case its wanted.

But extra methods on the options object are nice! As I use ^ infilename, outfilename I'd then use:

options.start()

which writes to the given outfilename already. In any way the resulting svg code ends up in options.result. If no outfilename is given one can get the code string there as well... 🤔