Document the Python API. about cairosvg

[mbr]

+1

[SimonSapin]

Until we write proper docs:

The cairosvg module has svg2pdf, svg2ps, svg2svg (!) and svg2png functions. Each function expects one of these named arguments for the input: bytestring, url (which I think also accepts filenames) or file_obj. If you provide a write_to argument (which can be either a filename or a file object), the output is written there. Otherwise, the function returns a byte string.

This is basically it for the public API. Everything else is implementation details and could change in future versions.

[waldyrious]

Maybe I'm doing something wrong, but passing a filename to svg2ps didn't work. Instead, I had to do:

cairosvg.svg2ps(open("/path/to/input.svg", "rb").read(), write_to="/tmp/output.ps")

If this is correct, I'd be happy to submit a PR fixing the documentation, so please confirm. Otherwise, let me know why

cairosvg.svg2ps("/path/to/input.svg", write_to="/tmp/output.ps")

didn't work -- I got the following error message:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/local/lib/python3.5/site-packages/cairosvg/__init__.py", line 43, in <lambda>
    surface_type.convert(*args, **kwargs))(_surface_type)
  File "/usr/local/lib/python3.5/site-packages/cairosvg/surface/__init__.py", line 103, in convert
    tree = Tree(**kwargs)
  File "/usr/local/lib/python3.5/site-packages/cairosvg/parser.py", line 270, in __init__
    tree = ElementTree.fromstring(bytestring)
  File "/usr/local/Cellar/python3/3.5.1/Frameworks/Python.framework/Versions/3.5/lib/python3.5/xml/etree/ElementTree.py", line 1320, in XML
    parser.feed(text)
  File "<string>", line None
xml.etree.ElementTree.ParseError: not well-formed (invalid token): line 1, column 0
not well-formed (invalid token): line 1, column 0

At the very least, the error could be more informative -- again, happy to submit a PR if you let me know where / what to change.

[waldyrious]

By the way, I also tried navigating to the folder where the input file is and running the script there passing only the filename, without the path, and also adding "file://" to the path (using both the full path and the filename only). None of this worked, so it seems to me a filename isn't actually accepted as input.

[liZe]

As described in the documentation:

The cairosvg module offers 4 functions:

svg2pdf,
svg2png,
svg2ps, and
svg2svg.

These functions expect one of these parameters:

bytestring, a byte string containing SVG, or
url, an URL or a filename, or
file_obj, a file-like object.

You can use:

• cairosvg.svg2ps(file_obj=open("/path/to/input.svg", "rb"), write_to="/tmp/output.ps"), or
• cairosvg.svg2ps(url="/path/to/input.svg", write_to="/tmp/output.ps")

[SimonSapin]

file_obj without .read(), right?

[liZe]

Of course, I've changed the comment.