Restructure project directory layout and exception hierarchy

[peternowee]

This PR restructures the project directory layout and exception hierarchy to bring them in line with common practices and provide a better foundation for custom exceptions and logging. It follows up on discussions in #171 and #230.

See the individual commit messages and new ChangeLog entries for additional remarks. I won't copy them here.

Reviews/comments welcome. I won't merge it before 2021-07-26 anyway, later if necessary to resolve any comments.

---

@ankostis: In response to some of your comments of last year:

The Exceptions should be definitely defined in the package-module.

I now define them in exceptions.py and in __init__.py do from pydot.exceptions import *. That comes down to the same as what you meant, right?

It is tempting to copy-paste the whole pydot.py contents on the package-module
but i would recommend against it.

Hmm, I am not sure if I followed up this advice completely. Taken literally, at least I did not copy-paste everything into __init__.py. Only __author__, __version__ and __license__. However, I did rename pydot.py to core.py and then added from pydot.core import * to __init__.py, which basically comes down to importing "the whole pydot.py" after all. Not sure if you meant to advise against that as well, but I do not really see how we can avoid that without breaking things. See example below.

TIP1:
When a user imports a module further into a package, the package-module gets import
in its entirety - so if it is "heavy" it delays the import. That is important when
the different functionality is split in multiple submodules of the package.
Example:
A package contains 3 sub-modules: base.py, sphinx_extension.py
If base.py contains also code for irrelevant http-server communications,
whenever from <package> import sphinx_extension code is trun,
it has to pay the price for this never-to-be-used http-server functionality.

TIP2
The modules are split based on the 3rd-party imports. If a module is completely disparate,
it might become an "extras" in the setup.py.

I have been thinking about how to apply this to pydot, but run into objections regarding backwards compatibility and user-friendliness.

• The obvious candidate to be split off from core is the parser-related code, which includes a dependency on PyParsing. Most of it is already in a separate module (dot_parser.py). There are only two functions in core.py that depend on dot_parser: graph_from_dot_data() and graph_from_dot_file(). If we would move those out of core.py and drop the import of dot_parser, the loading time for pydot would be cut by 46% (from 89 ms to 48 ms, as measured by python -X importtime -c "import pydot", Python 3.7.3, Celeron N3350, lowest of multiple runs). This reduction is mostly (98%) attributable to not importing pyparsing anymore.

  However, I am not very eager to remove parsing from the standard functionality offered by pydot. I mean, currently import pydot means you get access to all its functionality immediately. If we take the parsing functionality out, users would need to start thinking about how to import which part of pydot. To use the parsing functions they would need to do import pydot.dot_parser, from pydot import dot_parser or from pydot.dot_parser import graph_from_dot_data, graph_from_dot_file. This is not only a breaking change for existing scripts (we could at best smooth the transition by adding a deprecation warning in pydot 2.0 and postponing the removal from core to pydot 3.0), but it is also inconvenient for new users and new scripts. An additional import would be needed, different prefixes need to be used (e.g. pydot.dot_parser.graph_from_dot_data()) and in the interactive interpreter, using tab completion on pydot. would not show these functions anymore for easy discovery of what pydot offers.

  So, I was thinking if instead we could maybe just turn it around: Keep the parsing as default functionality of pydot, but offer users that are looking to reduce load time a way to manually import only the (core) modules they need. However, I am getting the impression that this is simply impossible, because __init__.py always gets executed, even if the user only imports a specific module inside the package. We need __init__.py to carry the parsing stuff if we want to offer that as default functionality of pydot, but then we do not want that to load when a user chooses to import only the core and exceptions modules for example. Those two wishes are simply incompatible with each other, right? Hope you understand what I am trying to say and please correct me if I am wrong.

  Alternatively, if making pydot lighter is the goal, we could just "lazy import" dot_parser by moving the import to inside the function graph_from_dot_data(). A lot can be said about this practice, see this SO question for example. I think we can get over the style objections, and as I understand the performance overhead of repeated import statements for an already imported module is minimal. However, a more important issue may be that any problems met during the import will only show up once the function is called. On the other hand, I assume parsing is one of the first steps in most user scripts, so any import problems should still show up early on. Hope to hear your thoughts. This can also be done separate of this PR.

• One might also consider splitting off the functions related to calling Graphviz to a separate module. However, when it comes to offering users the option not to load that module, similar questions as for splitting off the parsing will come up. Calling Graphviz is the reason most people use pydot and the core pydot class Dot has methods Dot.create() and Dot.write() that depend heavily on those functions. Again, we could move the import to inside Dot.create(), but in this case that would really make import problems show up much too late, because users will likely call Graphviz only at the end of their scripts. Finally, the performance benefit is not as strong here: Not loading Graphviz output functions and not importing os and subprocess reduces pydot load time by around 6%.

Again, hope to hear your thoughts. In both cases, we can also decide about it later. No need to do everything in this PR already.

[peternowee]

@ankostis I will merge this now already, because I want to keep things moving, but feel free to still comment on it later. Thank you for all your help and hope you are doing well.