REFACT: compilation.py (& term) --> planning.py

Author: ankostis

docs/source/arch.rst

@@ -15,7 +15,7 @@ Architecture
         The definition & execution of networked operation is split in 1+2 phases:
 
         - `composition`
-        - `compilation`
+        - `planning`
         - `execution`
 
         ... it is constrained by these IO data-structures:
@@ -38,7 +38,7 @@ Architecture
 
             graphtik.op.FunctionalOperation
             graphtik.pipeline.Pipeline
-            graphtik.network.Network
+            graphtik.planning.Network
             graphtik.execution.ExecutionPlan
             graphtik.execution.Solution
 
@@ -90,7 +90,7 @@ Architecture
             :ref:`hierarchical-data` (example).
 
     compile
-    compilation
+    planning
         The `phase` where the :class:`.Network` creates a new `execution plan`
         by `pruning` all `graph` nodes into a subgraph `dag`, and  deriving
         the `execution steps`.
@@ -116,7 +116,7 @@ Architecture
         During `composition`, the nodes of the graph are connected by repeated calls
         of :meth:`.Network._append_operation()` within ``Network`` constructor.
 
-        During `compilation` the *graph* is `prune`\d based on the given `inputs`,
+        During `planning` the *graph* is `prune`\d based on the given `inputs`,
         `outputs` & `node predicate` to extract the `dag`, and it is ordered,
         to derive the `execution steps`, stored in a new `plan`, which is then
         cached on the ``Network`` class.
@@ -178,15 +178,15 @@ Architecture
 
     prune
     pruning
-        A subphase of `compilation` performed by method :meth:`.Network._prune_graph()`,
+        A subphase of `planning` performed by method :meth:`.Network._prune_graph()`,
         which extracts a subgraph `dag` that does not contain any `unsatisfied operation`\s.
 
         It topologically sorts the `graph`, and *prunes* based on given `inputs`,
         asked `outputs`, `node predicate` and `operation` `needs` & `provides`.
 
     unsatisfied operation
         The core of `pruning` & `rescheduling`, performed by
-        :func:`.network.unsatisfied_operations()` function, which collects
+        :func:`.planning.unsatisfied_operations()` function, which collects
         all `operation`\s with unreachable `dependencies <dependency>`:
 
         - they have `needs` that do not correspond to any of the given `inputs` or
@@ -220,7 +220,7 @@ Architecture
         A memory footprint optimization where intermediate `inputs` & `outputs`
         are erased from `solution` as soon as they are not needed further down the `dag`.
 
-        *Evictions* are pre-calculated during `compilation`, denoted with the
+        *Evictions* are pre-calculated during `planning`, denoted with the
         `dependency` inserted in the `steps` of the `execution plan`.
 
     inputs
@@ -273,7 +273,7 @@ Architecture
           *Operations* are then interlinked together, by matching the *needs* & *provides*
           of all *operations* contained in a `pipeline`.
 
-        - During `compilation` the `graph` is then `prune`\d based on the :term:`reachability
+        - During `planning` the `graph` is then `prune`\d based on the :term:`reachability
           <unsatisfied operation>` of the *dependencies*.
 
         - During `execution` :meth:`.Operation.compute()` performs 2 "matchings":
@@ -345,7 +345,7 @@ Architecture
 
     modifier
     diacritic
-        A `modifier` change `dependency` behavior during `compilation` or `execution`.
+        A `modifier` change `dependency` behavior during `planning` or `execution`.
 
         For instance, a `needs` may be annotated as :func:`.keyword` and/or `optionals`
         function arguments, `provides` and *needs* can be annotated as "ghost" `sideffects`
@@ -403,7 +403,7 @@ Architecture
           denoting modifications on a *real* dependency read from and written to
           the solution.
 
-        Both kinds of sideffects participate in the `compilation` of the graph,
+        Both kinds of sideffects participate in the `planning` of the graph,
         and both may be given or asked in the `inputs` & `outputs` of a `pipeline`,
         but they are never given to functions.
         A function of a `returns dictionary` operation can return a falsy value
@@ -517,14 +517,14 @@ Architecture
     predicate
     node predicate
         A callable(op, node-data) that should return true for nodes to be
-        included in `graph` during `compilation`.
+        included in `graph` during `planning`.
 
     abort run
         A global `configurations` flag that when set with :func:`.abort_run()` function,
         it halts the execution of all currently or future `plan`\s.
 
         It is reset automatically on every call of :meth:`.Pipeline.compute()`
-        (after a successful intermediate :term:`compilation`), or manually,
+        (after a successful intermediate :term:`planning`), or manually,
         by calling :func:`.reset_abort()`.
 
     parallel

docs/source/plotting.rst

@@ -496,7 +496,7 @@ deeply nested stacks is notoriously hard
 Logging
 ^^^^^^^
 Increase the logging verbosity; logging statements have been placed melticulously
-to describe the :term:`execution` flows  (but not :term:`compilation` :-(),
+to describe the :term:`execution` flows  (but not :term:`planning` :-(),
 with each log statement accompanied by the :attr:`solution id <.Solution.solid>` of that flow,
 like the ``(3C40)`` & ``(8697)`` below, important for when running pipelines
 in :term:`parallel`::

docs/source/reference.rst

@@ -8,7 +8,7 @@ API Reference
      graphtik.op
      graphtik.pipeline
      graphtik.modifier
-     graphtik.network
+     graphtik.planning
      graphtik.execution
      graphtik.plot
      graphtik.config
@@ -44,10 +44,10 @@ Module: `modifier`
      :private-members:
      :special-members:
 
-Module: `network`
-=================
+Module: `planning`
+==================
 
-.. automodule:: graphtik.network
+.. automodule:: graphtik.planning
      :members:
      :private-members:
      :special-members:

graphtik/base.py

@@ -421,7 +421,7 @@ class PlotArgs(NamedTuple):
     #: the list of output names .
     outputs: Collection = None
     #: Contains the computed results, which might be different from :attr:`plottable`.
-    solution: "graphtik.network.Solution" = None
+    solution: "graphtik.planning.Solution" = None
     #: Either a mapping of node-names to dot(``.``)-separated cluster-names, or
     #: false/true to enable :term:`plotter`'s default clustering of nodes based
     #: on their dot-separated name parts.
@@ -514,7 +514,7 @@ def plot(
         steps=None,
         inputs=None,
         outputs=None,
-        solution: "graphtik.network.Solution" = None,
+        solution: "graphtik.planning.Solution" = None,
         clusters: Mapping = None,
         jupyter_render: Union[None, Mapping, str] = None,
     ) -> "pydot.Dot":
@@ -794,14 +794,14 @@ def prepare_plot_args(self, plot_args: PlotArgs) -> PlotArgs:
     @property
     def ops(self) -> List["Operation"]:
         """A new list with all :term:`operation`\\s contained in the :term:`network`."""
-        from .network import yield_ops
+        from .planning import yield_ops
 
         return list(yield_ops(self.graph))
 
     @property
     def data(self) -> List[str]:
         """A new list with all :term:`operation`\\s contained in the :term:`network`."""
-        from .network import yield_datanodes
+        from .planning import yield_datanodes
 
         return list(yield_datanodes(self.graph))
 

graphtik/execution.py

@@ -48,7 +48,7 @@
     get_jsonp,
     is_sfx,
 )
-from .network import (
+from .planning import (
     unsatisfied_operations,
     yield_chaindocs,
     yield_node_names,
@@ -432,7 +432,7 @@ class ExecutionPlan(
     """
     A pre-compiled list of operation steps that can :term:`execute` for the given inputs/outputs.
 
-    It is the result of the network's :term:`compilation` phase.
+    It is the result of the network's :term:`planning` phase.
 
     Note the execution plan's attributes are on purpose immutable tuples.
 

graphtik/modifier.py

@@ -1,7 +1,7 @@
 # Copyright 2016, Yahoo Inc.
 # Licensed under the terms of the Apache License, Version 2.0. See the LICENSE file associated with the project for terms.
 """
-:term:`modifier`\\s change :term:`dependency` behavior during :term:`compilation` & :term:`execution`.
+:term:`modifier`\\s change :term:`dependency` behavior during :term:`planning` & :term:`execution`.
 
 The `needs` and `provides` annotated with *modifiers* designate, for instance,
 :term:`optional <optionals>` function arguments, or "ghost" :term:`sideffects`.
@@ -783,7 +783,7 @@ def sfx(name, optional: bool = None) -> _Modifier:
     :term:`sideffects` denoting modifications beyond the scope of the solution.
 
     Both `needs` & `provides` may be designated as *sideffects* using this modifier.
-    They work as usual while solving the graph (:term:`compilation`) but
+    They work as usual while solving the graph (:term:`planning`) but
     they have a limited interaction with the operation's underlying function;
     specifically:
 

graphtik/pipeline.py

@@ -122,7 +122,7 @@ def parent_wrapper(ren_args: RenArgs) -> str:
 
     assert all(bool(n) for n in merge_set)
 
-    from .network import Network  # Imported here not to affect locals() at the top.
+    from .planning import Network  # Imported here not to affect locals() at the top.
 
     return Network(*merge_set)
 
@@ -370,7 +370,7 @@ def compute(
         Compile a plan & :term:`execute` the graph, sequentially or parallel.
 
         .. Attention::
-            If intermediate :term:`compilation` is successful, the "global
+            If intermediate :term:`planning` is successful, the "global
             :term:`abort run` flag is reset before the :term:`execution` starts.
 
         :param named_inputs:

graphtik/network.py renamed to graphtik/planning.py

@@ -309,7 +309,7 @@ def __init__(self, *operations, graph=None):
                 raise TypeError(f"Must be a NetworkX graph, was: {graph}")
 
         #: The :mod:`networkx` (Di)Graph containing all operations and dependencies,
-        #: prior to :term:`compilation`.
+        #: prior to :term:`planning`.
         self.graph = graph
 
         for op in operations:

test/test_base.py

@@ -8,7 +8,7 @@
 
 import pytest
 
-from graphtik import base, network, operation, pipeline
+from graphtik import base, planning, operation, pipeline
 from graphtik.execution import ExecutionPlan, Solution, _OpTask
 from graphtik.base import Operation
 from graphtik.pipeline import Pipeline

test/test_graphtik.py

@@ -7,7 +7,7 @@
 
 import pytest
 
-from graphtik import NO_RESULT, compose, network, operation, optional, vararg
+from graphtik import NO_RESULT, compose, planning, operation, optional, vararg
 from graphtik.base import IncompleteExecutionError
 from graphtik.config import evictions_skipped, operations_endured