Graphtik

======================================================================
Actually it contains just what was destined for v7.1.1.

+ FIX(op): v7.0.0 promise that ``op.__call__`` delegates to ``compute()`` was a fake;
now it is fixed.
+ fix(config): endurance flags were miss-behaving.
+ refact(net): factor out a :meth:`._reschedule()` method for both endurance & rescheduled ops.
+ feat(build): +script to launch pytest on a local clone repo before pushing.

--------------------------------------------------------------------------------
(removed from PyPi/RTD, new features by mistake were removed from v7.1.2)

====================================================================================
|v440-flowchart|

Should have been a MAJOR BUMP due to breaking renames, but just out of
another 6.x --> 7.x major bump.

NET: fix rescheduled, cancelable sfx, improve compute API
---------------------------------------------------------
+ FIX: rescheduled operations were not canceling all downstream deps & operations.
+ FEAT: Cancelable sideffects: a :term:`reschedule`\s operation may return
a "falsy" sideffect to cancel downstream operations.

+ ``NO_RESULT`` constant cancels also sideffects.

+ ENH(OP): more intuitive API, ``compute()`` may be called with no args,
or a single string as `outputs` param. Operation's ``__call__`` now delegates
to ``compute()`` - to quickly experiment with function, access it from the
operation's :attr:`.FnOp.fn` attribute

MODIFIERS: modifier combinations, rename sol_sideffects
-------------------------------------------------------
+ BREAK: renamed modifiers ``sol_sideffect --> sideffected``, to reduce terminology
mental load for the users.
+ ENH: support combinations of modifiers (e.g. optional sideffects).
+ REFACT: convert modifiers classes --> factory functions, producing :class:`._Modifier`
instances (normally not managed by the user).

PLOT: them-ize all, convey user-attrs, draw nest clusters, click SVGs to open in tab, ...
-----------------------------------------------------------------------------------------
+ ENH: Theme-ize all; expand callables (beyond Refs and templates).
+ BREAK: rename ``Theme.with_set()`` --> :meth:`.Theme.withset()`.
+ break: pass verbatim any `nx-attrs` starting with ``'graphviz.'`` into
plotting process (instead of passing everything but private attributes).
+ break: rename graph/node/edge control attributes:

+ ``_no_plot --> no_plot``.
+ ``_alias_of --> alias_of``.

+ FEAT: draw combined pipelines as clusters
+ enh: corrected and richer styles for data nodes.
+ enh: unify op-badges on plot with diacritics in their string-representation.
+ ENH(sphinxext): clicking on an SVG opens the diagram in a new tab.
+ fix(sphinxext): don't choke on duplicate ``:name:`` in :rst:dir:`graphtik` directives.
+ fix(sphinxext): fix deprecation of sphinx ``add_object()`` with ``note_object()``.

Various: raise TypeErrors, improve "operations" section
-------------------------------------------------------
+ break: raise ``TypeError`` instead of ``ValueError`` wherever it must.
+ DOC(operations): heavily restructured chapter - now might stand alone.
Started using the `pipeline` name more often.
+ doc: use as sample diagram in the project opening an "endured" one (instead of
an outdated plain simple on).
+ doc: renamed document: ``composition.py --> pipelines.py``

.. |v440-flowchart| raw:: html
:file: docs/source/images/GraphtikFlowchart-v4.4.0.svg

=======================================================================================
+ BREAK: stacking of solution results changed to the more natural "chronological" one
(outputs written later in the solution override previous ones).

Previously it was the opposite during `execution` while reading intermediate
solution values (1st result or user-inputs won), and it was "reversed" to regular
chronological right before the solution was finalized.

+ FEAT(op, netop): add ``__name__`` attribute to operations, to disguise as functions.

+ BREAK(op): The :func:`.operation` factory function (used to be *class*) now behave
like a regular decorator when `fn` given in the first call, and constructs
the :class:`.FnOp` without a need to call again the factory.

Specifically the last empty call at the end ``()`` is not needed (or possible)::

operation(str, name=...)()

became simply like that::

operation(str, name=...)

+ DROP(NET): ``_DataNode`` and use str + modifier-classes as data-nodes;

MODIFIERS: Sideffecteds; arg--> mapped
---------------------------------------
+ BREAK: rename `arg --> mapped``, which conveys the correct meaning.

+ FEAT: Introduced :term`sideffected`\s, to allow for certain dependencies
to be produced & consumed by function to apply "sideffects, without creating
"cycles":

+ feat(op): introduce ``_fn_needs``, ``op_needs`` & ``op_provides`` on
:class:`.FnOp`, used when matching Inps/Outs and when pruning
graph.
+ FEAT(op): print detailed deps when DEBUG enabled.

PLOT: Badges, StyleStacks, refact Themes, fix style mis-classifications, don't plot steps
-----------------------------------------------------------------------------------------
+ ENH: recursively merge Graphviz-styles attributes, with expanding jinja2-template
and extending lists while preserving theme-provenance, for debugging.

+ BREAK: rename class & attributes related to ``Style --> Theme``,
to distinguish them from styles (stacks of dictionaries).

+ UPD: dot no plot Steps by default; use this :ref:`plot-customizations` to re-enable them::

plottable.plot(plotter=Plotter(show_steps=True))

+ FEAT: now `operations` are also :term:`plottable`.

+ FEAT: Operation BADGES to distinguish endured, rescheduled, parallel, marshalled,
returns_dict.

+ FIX: Cancel/Evict styles were misclassified.

+ feat(plot): change label in sol_sideffects; add exceptions as tooltips on
failed operations, etc.

+ enh: improve plot theme, e.g. prunes are all grey, sideffects all blue,
"evictions" are colored closer to steps, etc. Add many neglected styles.

Sphinx extension:
-----------------

+ enh: Save DOTs if DEBUG; save it before...
+ fix: save debug-DOT before rendering images, to still get those files
as debug aid in case of errors.
+ fix: workaround missing *lineno* on doctest failures, an incomplete solution
introduced upstream by sphinx-doc/sphinx4584.

Configurations:
---------------
+ BREAK: rename context-manager configuration function `debug --> debug_enabled`.
+ FEAT: respect :envvar:`GRAPHTIK_DEBUG` for enabling `is_debug()` configuration.

DOC:
----
+ feat: new sections about composing pipelines with :term:`reschedule` / :term:`endured`
operations & :term:`alias`\es.
+ enh: Clarified relation and duties of the new term :term:`dependency`.
+ enh: Linked many terms from quick-start section.
+ enh(site): support for `Sphinx's standard colored-text
<https://stackoverflow.com/a/61389938/548792>`_ roles.

====================================================================================
+ PLOT:

+ DEPRECATE(plot): `show` argument in plot methods & functions; dropped completely
from the args of the younger class :class:`Plotter`.

It has merged with `filename` param (the later takes precedence if both given).
+ ENH: apply more styles on data-nodes; distinguish between Prune/Cancel/Evict
data Styles and add tooltips for those cases (ie data nodes without values).

+ DROP: do not plot wth ``splines=ortho``, because it `crashes with some shapes
<https://gitlab.com/graphviz/graphviz/issues/1408>`_;
explain in docs how to re-enables this (x2 ways).
+ FIX: node/edge attributes were ignored due to `networkx` API misuse - add TCs
on that.
+ FIX: Networks were not plotting Inps/Outs/Name due to forgotten ``namedtuple._replace()``
assignment.
+ feat: introduce ``_no_plot`` nx-attribute to filter out nodes/edges.

+ ENH(base): improve auto-naming of operations, descending *partials* politely and
handling better builtins.

+ FEAT(net): add :meth:`.Network.find_ops()` & :meth:`.Network.find_op_by_name()`
utility methods.

+ enh(build, site, doc): graft Build Ver/Date as gotten from Git in PyPi landing-page.

==========================================================
Should have been a MAJOR BUMP due to breaking renames, but...no clients yet
(and just out of to 5.x --> 6.x major bump).

+ REFACT/BREAK(plot): rename ``installed_plotter --> active_plotter``.
+ REFACT/BREAK(config): denote context-manager functions by adding a ``"_plugged"`` suffix.
+ FEAT(plot): offer ``with_XXX()`` cloning methods on Plotter/Style instances.
+ FIX(plot): Style cstor were had his methods broken due to eager copying them
from its parent class.


v6.0.0 (13 Apr 2020, ankostis): New Plotting Device...
=======================================================
**--((superseded by v6.1.0 due to installed_potter --> active_plotter))--**

+ ENH/REFACT(PLOT):

+ REFACT/BREAK: plots are now fully configurable with :term:`plot theme`
through the use of :term:`installed plotter <active plotter>`.
+ ENH: Render operation nodes with Graphviz *HTML-Table Labels*.

.. graphtik::
:hide:

>>> from graphtik import operation, varargs
>>> from graphtik.plot import get_active_plotter
>>> op = operation(print, name='print-something', needs=varargs("any"), provides="str")
>>> dot = op.plot(plotter=get_active_plotter().with_styles(kw_legend={}))

+ ENH: Convey graph, node & edge ("non-private") attributes from the *networkx* graph
given to the :term:`plotter`.
+ FEAT: Operation node link to docs (hackish, based on a URL formatting).
+ Improved plotting documentation & +3 new terms.

* FIX: ReadTheDice deps

+ drop(plot): don't suppress the grafting of the title in netop images.