Graphviz

--------------

Fix undecoded ``CalledProcessError.stdout`` and ``.stderr`` when ``.pipe()`` call
with an ``encoding`` different from ``self.encoding`` fails.

Fix missing project root ``conftest.py`` in source distribution.

Extend ``examples/graphviz-escapes.ipynb``.

Improve test coverage.

Increase build scripts verbosity.

------------

Add ``PendingDeprecationWarning`` to calls using positional arguments
that will be **deprecated in a later version**.
The future API will allow from one to three positional arguments
depending on the method or function.
Keyword-only arguments where not around when this library was created.
This signals dependents and in general users to start updating
or pinning to the wanted version (or range).
Crucially, this helps new users with a safer API
that allows to avoid some common mistakes.
Warnings reported in tests.

Add keyword-only ``outfile`` argument to ``.render()``
and stand-alone ``graphviz.render()``.
Allows to override the rendered output file name:
``.render(filename='spam.gv', outfile='spam.pdf')``
Allows to derive the ``format`` and the ``filename``
from the rendered ``outfile`` name:
``.render(outfile='spam.svg')``
Tries to infer default ``format`` from the ``outfile`` suffix.
You can override by setting ``format`` explicitly.
Warns with a ``graphviz.FormatSuffixMismatchWarning``
if there is a mismatch between given ``format``
and the inferred format from ``outfile`` suffix.
Warns with a ``graphviz.UnknownSuffixWarning``
if ``format`` is given and ``outfile`` uses a suffix
that cannot be mapped to a supported format.

Add ``graphviz.set_jupyter_format()`` to set the output ``format``
used by the Jupyter visualization of ``graphviz.Graph``, ``graphviz.Digraph``,
and ``graphviz.Source`` (supported formats: ``'svg'``, ``'png'``, ``'jpeg'``).
Replace ``_repr_svg_()`` internally with ``_repr_mimebundle_(include, exclude)``
returning a mimebundle ``{'image/svg+xml', '<?xml version=...'}`` by default.
Adds support for ``IPython.display.display_png()``.
Adds support for ``IPython.display.display_jpeg()``.
PR `150 <https://github.com/xflr6/graphviz/pull/150>`_ Christoph Boeddeker.

Add keyword-only ``raise_if_result_exists`` argument to ``.render()``
and stand-alone ``graphviz.render()``.
Raises ``graphviz.FileExistsError`` if the rendered file already exists.

Add support to for ``.render()`` and stand-alone ``.render()``
to overwrite the input source file with the rendered output
when using the ``outfile`` keyword-only argument.
This probably only makes sense for text-based Graphviz formats
such as ``dot`` or ``plain``.
You need to specify ``overwrite_filepath=True`` to enable this.

Add ``graphviz.CalledProcessError`` derived from ``subprocess.CalledProcessError``
so users can choose either one in their excepts.

Add ``graphviz.FileExistsError`` derived from ``FileExistsError``
so users can choose either one in their excepts.

Add ``--only-exe`` flag to ``run-tests.py`` (overrides ``--skip-exe``).

Add ``--no-open`` and ``--open`` flags to ``build-docs.py``.

Add ``lint-code.py`` and use in build job.

Increase doctest coverage.

Extend type annotations.
Accept path-like objects for ``filename``, ``directory``, and ``filepath``.

Extend and improve documentation.

Improve build tests.

--------------

Fix ``filepath`` fallback to ``name`` of ``Graph/Digraph`` for
when filepath is not present (restore
``graphviz.Graph('spam').filename == 'spam.gv'`` broken in 0.18).

Fix unintended API docs reference to internal ``backend`` name for
``DOT_BINARY`` and ``UNFLATTEN_BINARY``. Moved to public API
as ``graphviz.DOT_BINARY`` and ``graphviz.UNFLATTEN_BINARY``.

Fix broken documentation links.

Docs: re-render most SVGs and notebooks with upstream Graphviz 2.49.3.

--------------

Fix ``TypeError: argument of type 'WindowsPath' is not iterable``
on Windows platform under Python 3.6 and 3.7
(work around https://bugs.python.org/issue41649).

Update outdated examples source links.

Improve mode structure and separation of concerns.

Improve test structure and coverage.

Improve output of ``try-examples.py``.
Add exit status for CI. Disable `view()`.

Add ``build-docs.py`` script for development.

Add ``update-help.py`` script for development.

------------

Change of beaviour:
File endings are now normalized so that all DOT source outputs
end with a final newline (Unix convention, simplifies concatenation).
This includes DOT source files written by ``.render()``, ``.view()``,
or ``.save()`` as well was ``.source`` generated or loaded from ``Source``
(or ``Source.from_file()``).

Change of behaviour:
``Source`` instances created by ``Source.from_file()``
no nonger write the content read into ``.source`` back into the file.
Use ``.save(skip_existing=False)`` before calling ``.render()`` or ``.view()``
if you want to overwrite the file to produce the previous (less safe) behaviour.

Change of undocumented behaviour:
When iterating over a ``Graph``, ``Digraph``, or ``Source`` instance,
the yielded lines now include a final newline (``'\n'``).
This mimics iteration over ``file`` object lines in text mode.

Change of behaviour:
When adding custom DOT statements using the ``body`` argument
of ``Graph`` or ``Digraph`` or appending to the ``body`` attribute
of an instance, the lines now need to include their final newline (``'\n'``).

When passing invalid parameters such as unknown ``engine``, ``format``, etc.,
``.render()`` now raises early before writing the file.
Call ``.save()`` explicitly to produce the previous (less safe) behaviour.

Add optional keyword-only ``encoding`` argument to ``pipe()``.
Returns the decoded stdout from the rendering process
(e.g. ``format='svg'``).
Delegates encoding/decoding to ``subprocess`` in the common case
(input and output encoding are the same, e.g. default ``encoding='utf-8'``).
Used by the Jupyter notebook integration.

Add optional keyword-only ``engine`` argument to ``.pipe()`` and ``.render()``.

Add optional keyword-only ``renderer`` and ``formatter`` arguments to ``Graph()``,
``Digraph()``, ``Source()`` and ``Source.from_file()``
to set default renderers and formatters (similar to ``format``).
Used by ``.pipe()``, ``.render()``, and ``.view()`` if not given as method-argument.

Add ``pipe_string()``, ``pipe_lines()``, and ``pipe_lines_string()``.
Pipe ``input_string``, return ``string``.
Pipe ``input_lines`` incrementally, return ``bytes``.
Pipe ``input_lines`` incrementally, return ``string``.

Add ``set_default_engine()`` and ``set_default_format()``

Add ``DOT_BINARY`` and ``UNFLATTEN_BINARY``.

Restructure the internal class hierarchy using multiple-inheritance
with cooperative ``super()`` calling:
``Graph`` now inherits both from ``Dot`` and from ``Render``,
and both of them inherit from ``Base`` which defines their common interface:
Lines of DOT source code that ``Dot`` generates (also ``Source``)
and rendering iterates over.
This might break some undocumented use of subclassing and require adatation
(e.g. if the methods don't use cooperative ``super()`` calling convention
or if the MRO has conflicts, supposedly rare).

Improve test separation. Improve test coverage of running the tests with ``--skip-exe``.

Add ``pytype`` checking and ``flake8`` to build workflow.

Extend type annotations.

Add https://mybinder.org config with head development environment.
Add launch badge to code repository.

Improve documentation and examples.

Add development docs.

Document release process.

------------

Drop Python 2 support. Tag Python 3.10 support.

Migrate CI to GitHub actions. Add ``pypy3`` to matrix.

Tests: implement ``--skip-exe`` via custom ``pytest`` marker.

Documentation: point Anaconda users to ``conda-forge/python-graphviz``.

Move type hints from docstrings to type annotations. Improve doctests.

Examples: standardize import convention and modernize.

Re-render example notebooks with Graphviz 2.46.1.