# 5. Using dot2tex as a module

It is possible to load dot2tex as a module for use in other Python programs. Here is a basic example:

    import dot2tex
    testgraph = """
    digraph G {
        a -> b -> c -> a;
    }
    """
    texcode = dot2tex.dot2tex(testgraph, format='tikz', crop=True)

The `dot2tex` function is the main interface:

    dot2tex(dotsource,**kwargs)

It takes the following input arguments:

> Argument | Description
> --- | ---
> `dotsource` | A string containing a DOT or XDOT graph.
> `**kwargs` | An arbitrary number of conversion options passed as keyword arguments

The function returns the resulting LaTeX code as a string.

The supported options are the same as the command line options (long version). Here are a few examples:

    import dot2tex as d2t
    texcode = d2t.dot2tex(testgraph, format='tikz', crop=True)
    texcode = d2t.dot2tex(testgraph, preproc=True,figonly=True)
    texcode = d2t.dot2tex(testgraph, debug=True)

Option values are either strings or booleans. Note that some of the command line options are not relevant when using dot2tex as a module.

To specify a template you can use the `template` option like this:

    import dot2tex
    mytemplate = "<<drawcommands>>"
    texcode = dot2tex.dot2tex(graph, template = mytemplate)

## 5.1. Debugging

You can set `debug=True` to create a detailed log useful for debugging. To retrieve the content of the log you can use the `get_logstream` function. It will return a `StringIO` instance. You can then use the `getvalue()` class method to get the actual text. Example:

    import dot2tex
    texcode = dot2tex.dot2tex(testgraph, debug=True)
    logstream = dot2tex.get_logstream()
    print logstream.getvalue()

## 5.2. The `positions` output format

When you use dot2tex as a module you have access to the special `positions` output format if you use `format=positions`. The `dot2tex` function will then return dictionary with node name as key and a (x, y) tuple with the center position of the node as value:

    >>> import dot2tex
    >>> testgraph = """
    ... digraph G {
    ...    a -> b -> c -> a;
    ... }
    """
    >>> dot2tex.dot2tex(testgraph, format='positions')
    {'a': [54, 162], 'b': [27, 90], 'c': [54, 18]}