Metadata-Version: 2.1
Name: asciigraf
Version: 1.0.0
Summary: A python library for making ascii-art into network graphs.
Author: Opus One Solutions
Author-email: rnd@opusonesolutions.com
License: copyright 2017 Anton Lodder
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: repository, https://github.com/opusonesolutions/asciigraf
Keywords: graph,network,testing,parser
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/x-rst
Provides-Extra: test
License-File: LICENSE.txt

asciigraf
=========

.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
    :target: https://opensource.org/licenses/MIT

.. image:: https://badge.fury.io/py/asciigraf.svg
    :target: https://pypi.python.org/pypi/asciigraf

.. image:: https://img.shields.io/pypi/pyversions/asciigraf.svg
    :target: https://pypi.python.org/pypi/asciigraf

.. image:: https://api.codeclimate.com/v1/badges/e7e872f6832da6cf6ab6/maintainability
   :target: https://codeclimate.com/github/opusonesolutions/asciigraf/maintainability
   :alt: Maintainability

Asciigraf is a python library that turns ascii diagrams of networks into
network objects. It returns a `networkx <https://networkx.github.io/>`__
graph of nodes for each alpha-numeric element in the input text; nodes
are connected in the graph to match the edges represented in the diagram
by ``-``, ``/``, ``\`` and ``|``.

Installation
------------

Asciigraf can be installed from pypi using pip:

.. code::

    ~/$ pip install asciigraf

Usage
-----

Asciigraf expects a string containg a 2-d ascii diagram. Nodes can be an
alphanumeric string composed of characters in ``A-Z``, ``a-z``, ``0-9``,
and ``_, {, }``. Edges can be composed of ``-``, ``/``, ``\`` and ``|``.

.. code:: python


    import asciigraf

    network = asciigraf.graph_from_ascii("""
              NodeA-----
                       |
                       |---NodeB
                                         """)

    print(network)
    >>> <networkx.classes.graph.Graph at 0x7f24c3a8b470>

    print(network.edges())
    >>> [('NodeA', 'NodeB')]

    print(network.nodes())
    >>> ['NodeA', 'NodeB']


Networkx provides tools to attach data to nodes and edges, and asciigraf
leverages these in a number of ways; in the example below you can see that
asciigraf uses this to attach a ``x, y`` position tuple to each node
indicating where on the *(x, y)* plane each node
starts ( *0,0* is at the top-left). It also attaches a ``length`` attribute
to each edge which matches the number of characters in that edge, as well
as a list of positions for each character an edge

.. code:: python

    print(network.nodes(data=True))
    >>> [('NodeA', {'position': (10, 1)}), ('NodeB', {'position': (23, 3)})]

    print(network.edges(data=True))
    >>> [('NodeA', 'NodeB', OrderedDict([('length', 10), 'points', [...]))]
    
    print(network.edge['NodeA']['NodeB']['points'])
    >>> [(15, 1), (16, 1), (17, 1), (18, 1),
         (19, 1), (19, 2), (19, 3), (20, 3), (21, 3), (22, 3)]


Asciigraf also lets you annotate the edges of graphs using in-line labels ---
denoted by parentheses. The contents of the label will be attached to the edge
on which it is drawn with the attribute name ``label``.

.. code:: python

    network = asciigraf.graph_from_ascii("""

        A---(nuts)----B----(string)---C
                      |
                      |
                      |
                      D---(string)----E

    """)

    print(network.get_edge_data("A", "B")["label"])
    >>> nuts

    print(network.get_edge_data("B", "C")["label"])
    >>> string

    print(network.get_edge_data("D", "E")["label"])
    >>> string

    print(hasattr(network.get_edge_data("B", "D"), "label"))
    >>> False


Have fun!

.. code:: python

    import asciigraf


    network = asciigraf.graph_from_ascii("""
              s---p----1---nx
             /    |        |
            /     |        0---f
           6l-a   c--
          /   |      \--k
         /   ua         |  9e
        q      \        | /
                \-r7z   jud
                    \    |
                     m   y
                      \  |
                       v-ow
                                 """)
