================================================================================
pyGraphADT 2.0 --
A package of Graph Abstract Data Types and Algorithms implemented in Python3
================================================================================
by Danver Braganza
2020 February 24


0. Contents
----------------------------------------
1. Introduction
2. Requirements and Overview
3. Installing
4. Examples and sample code


1. Introduction
----------------------------------------
pyGraphADT has been developed for use in the Computer Science 220 course over
the summer of 2009-10 by Danver Braganza, supervised by Dr Michael Dinneen, and
based on code originally authored by Dr Michael Dinneen with contributions from
Sonny Dutt.

pyGraphADT offers students the choice of completing their assignments and worked
examples using Python.  pyGraphADT is mostly compatible with the Java code, upon
which it is based, with a number of differences for which the documentation must
be consulted.

pyGraphADT has now been upgraded to Python 3.

2. Requirements and Overview
----------------------------------------
pyGraphADT is designed to work with Python 2.6+.

pyGraphADT makes the 'graphadt' package available to the user for importing. The
graphadt package has the following modules:

graphadt.graphtypes      : Classes to represent different types of graphs, e.g.
		           DirectedAdjListsGraph.  All graphs fulfil a
graphadt.algorithms      : Functions which can be called on various graphs to
			   compute properties such as girth, eccentricity, etc.
graphadt.representations : Classes which contain the internal representations of
			   graphs.  These classes are never meant to be used by
			   the user, but they may be interesting to look at.

3. Installing
----------------------------------------
The specific method you use to install pyGraphADT depends on the operating
system of the target computer, and the privileges you have available during the
installation process.

These installation guides all assume that you have already downloaded the
pyGraphADT.zip file and unzipped it to a temporary folder.

Unix-like with full privileges:
-------------------------------
This should work on any Unix-like system, such as Linux and Mac OS X. Start up
a console, and after the command prompt (here represented by $), type the
following:

$ sudo python setup.py install

This should copy the required files to the right folder in your python
installation so that it can be imported by python later.

Note: The files created and copied by setup.py will have the permissions of
your umask.  Therefore it is important that your umask be set to 022 at least
before installing with sudo.  Otherwise, you will not be able to import from
pyGraphADT with normal user permissions.  You can set your umask with:

$ umask 022

To verify that the installation proceeded correctly, run the following test
program.

$ python3 -m testing.runtests

If pyGraphADT has installed correctly, you should see rows of dots, each one
representing a passed test.  If, on the other hand, pyGraphADT has not been
installed correctly, you should see an error similar to the following:

Traceback (most recent call last):
  File "testing/runtests.py", line 3, in <module>
    import testGraphs
  File
     "/usr/home/documents/2010/summer/python-graph/trunk/testing/testGraphs.py",
                                                             line 8, in <module>
    from graphadt.graphtypes import *
ImportError: No module named graphadt.graphtypes



Windows with full privileges
----------------------------
Start up a command line, and navigate to the pyGraphADT folder.  At the prompt,
(here represented by a >), type:

> setup.py install

This should install pyGraphADT to the right position in your system.  From now on
you can simply import it.

Computers without Privileges
----------------------------
If you do not have sufficient privileges to install pyGraphADT, you must
explicitly tell python to put this folder on the module search path.  The way to
do this is to add the folder where you unzipped pyGraphADT to the PYTHONPATH
environment variable.

In a Unix-like system, use export to set the PYTHONPATH to the pyGraphADT folder,
here represented by <path to folder>:

$ export PYTHONPATH=<path to folder>
$ echo $PYTHONPATH
<path to folder>

In a Windows, use set to do the same thing:

> set PYTHONPATH=<path to folder>
> echo %PYTHONPATH%
<path to folder>

NOTE: if you specify a relative path to the pyGraphADT folder, you must run your
python shell and interpreter from the same point where the relative path was set.

e.g. if PYTHONPATH is set to . (the current folder), since . must refer to the
pyGraphADT folder, you need to make sure that when you run python you are in the
pyGraphADT folder.  For this reason, it's probably best if you use an absolute
path, unless you are very careful.

4. Examples
-----------

>>> from graphadt.graphtypes import *
>>> mygraph = DirectedAdjMatrixGraph()
>>> mygraph.addVertices(10)
>>> mygraph.addEdge(0, 1)
>>> mygraph.addArc(1, 2)
>>> print mygraph
10
0 1 0 0 0 0 0 0 0 0
1 0 1 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0 0 0

>>> from graphadt.algorithms import *
>>> isConnected(mygraph)
False
>>> isAcyclic(mygraph)
True
