Repository: pytorch/ignite

Issue:
rename ignite.engines -> ignite.engine
@jasonkriss @vfdev-5  was there a reason we didn't do this when we merged the engines into one?

Discussion:
alykhantejani: yeah, or the alternative is to put the things in `__init__.py` into
`ignite/engine.py` :shrug:

On Wed, Apr 25, 2018 at 4:03 PM, vfdev <notifications@github.com> wrote:

> *@vfdev-5* commented on this pull request.
> ------------------------------
>
> In ignite/engine/__init__.py
> <https://github.com/pytorch/ignite/pull/158#discussion_r184094172>:
>
> > @@ -1,4 +1,4 @@
> -from ignite.engines.engine import Engine, Events, State
> +from .engine import Engine, State, Events
>
> from ignite.engine.engine import Engine
> we should have called the package engine to complete the similarity :)
>
> Otherwise, if you put Engine, State, Event into ignite.__init__.py it
> could be nicer, what do you think ?
>
> —
> You are receiving this because you authored the thread.
> Reply to this email directly, view it on GitHub
> <https://github.com/pytorch/ignite/pull/158#discussion_r184094172>, or mute
> the thread
> <https://github.com/notifications/unsubscribe-auth/AAp8WiE-ZzzH_f7Ip6HE30aEM14dqXNKks5tsJAkgaJpZM4TjaUB>
> .
>

jasonkriss: LGTM!
vfdev-5: @alykhantejani as you are working on this, could you fix also logger messages in `Engine` as it is not trainer anymore:
- ["Training starting with max_epochs={}"](https://github.com/pytorch/ignite/blob/master/ignite/engines/engine.py#L132), maybe, by "Engine run starting with max_epochs={}"
- ["Training complete. Time taken %02d:%02d:%02d"](https://github.com/pytorch/ignite/blob/master/ignite/engines/engine.py#L147) by "Engine run complete. Time taken %02d:%02d:%02d"
- ["Training is terminating due to exception: %s"](https://github.com/pytorch/ignite/blob/master/ignite/engines/engine.py#L150) by "Engine run is terminating due to exception: %s"
thanks


alykhantejani: @vfdev-5 sure thing. Was waiting to merge the other PRs so others don't have to fix  merge conflicts :) 

Patch:
diff --git a/docs/source/concepts.rst b/docs/source/concepts.rst
index 171965bb..325d2aeb 100644
--- a/docs/source/concepts.rst
+++ b/docs/source/concepts.rst
@@ -4,7 +4,7 @@ Concepts
 Engine
 ------
 
-The **essence** of the framework is the class :class:`ignite.engines.Engine`, an abstraction that loops a given number of times over
+The **essence** of the framework is the class :class:`ignite.engine.Engine`, an abstraction that loops a given number of times over
 provided data, executes a processing function and returns a result:
 
 .. code-block:: python
@@ -36,14 +36,14 @@ For example, model trainer for a supervised task:
 Events and Handlers
 -------------------
 
-To improve the :class:`ignite.engines.Engine`'s flexibility, an event system is introduced that facilitates interaction on each step of
+To improve the :class:`ignite.engine.Engine`'s flexibility, an event system is introduced that facilitates interaction on each step of
 the run:
 
 - *engine is started/completed*
 - *epoch is started/completed*
 - *batch iteration is started/completed*
 
-Complete list of events can be found `here <https://github.com/pytorch/ignite/blob/master/ignite/engines/engine.py#L8>`_.
+Complete list of events can be found `here <https://github.com/pytorch/ignite/blob/master/ignite/engine/engine.py#L8>`_.
 
 Thus, user can execute a custom code as an event handler. Let us consider in more detail what happens when :meth:`Engine.run` is called:
 
@@ -89,7 +89,8 @@ Attaching an event handler is simple using method :meth:`Engine.add_event_handle
 
 State
 -----
-A state is introduced in :class:`ignite.engines.Engine` to store the output of the `process_function`, current epoch, iteration and other
+A state is introduced in :class:`ignite.engine.Engine` to store the output of the `process_function`, current epoch,
+ iteration and other
 helpful information. For example, in case of supervised trainer, we can log computed loss value, completed iterations and
 epochs:
 
@@ -107,7 +108,7 @@ epochs:
 
 .. Note ::
 
-   A good practice is to use :class:`ignite.engines.State` also as a storage of user data created in update or handler functions.
+   A good practice is to use :class:`ignite.engine.State` also as a storage of user data created in update or handler functions.
    For example, we would like to save `new_attribute` in the `state`:
 
    .. code-block:: python
diff --git a/docs/source/engines.rst b/docs/source/engine.rst
similarity index 70%
rename from docs/source/engines.rst
rename to docs/source/engine.rst
index 298ac1b0..307d5003 100644
--- a/docs/source/engines.rst
+++ b/docs/source/engine.rst
@@ -1,7 +1,7 @@
-ignite.engines
+ignite.engine
 ==============
 
-.. currentmodule:: ignite.engines
+.. currentmodule:: ignite.engine
 
 .. autoclass:: Engine
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index ac8cb517..5790bddb 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -15,7 +15,7 @@ PyTorch.
    :maxdepth: 2
    :caption: Package Reference
 
-   engines
+   engine
    handlers
    metrics
    exceptions
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
index 62b7fec1..a7fc35a2 100644
--- a/docs/source/quickstart.rst
+++ b/docs/source/quickstart.rst
@@ -10,7 +10,7 @@ Code
 
 .. code-block:: python
 
-    from ignite.engines import Events, create_supervised_trainer, create_supervised_evaluator
+    from ignite.engine import Events, create_supervised_trainer, create_supervised_evaluator
 
     model = Net()
     train_loader, val_loader = get_data_loaders(train_batch_size, val_batch_size)
@@ -53,7 +53,7 @@ datasets (as :class:`torch.utils.data.DataLoader`), optimizer and loss function:
     optimizer = torch.optim.SGD(model.parameters(), lr=0.01, momentum=0.8))
     loss = torch.nn.NLLLoss()
 
-Next we define trainer and evaluator engines. The main component of Ignite is the :class:`Engine`, an abstraction over your
+Next we define trainer and evaluator engines. The main component of Ignite is the :class:`ignite.engine.Engine`, an abstraction over your
 training loop. Getting started with the engine is easy, the constructor only requires one things:
 
 - `update_function`: a function which is passed the engine and a batch and it passes data through and updates your model
diff --git a/examples/mnist.py b/examples/mnist.py
index 74e6cf79..ab78c69f 100644
--- a/examples/mnist.py
+++ b/examples/mnist.py
@@ -9,7 +9,7 @@ import torch.nn.functional as F
 from torchvision.transforms import Compose, ToTensor, Normalize
 from torchvision.datasets import MNIST
 
-from ignite.engines import Events, create_supervised_trainer, create_supervised_evaluator
+from ignite.engine import Events, create_supervised_trainer, create_supervised_evaluator
 from ignite.metrics import CategoricalAccuracy, Loss
 
 
diff --git a/examples/mnist_with_tensorboardx.py b/examples/mnist_with_tensorboardx.py
index 5b80c726..92c3e71c 100644
--- a/examples/mnist_with_tensorboardx.py
+++ b/examples/mnist_with_tensorboardx.py
@@ -30,7 +30,7 @@ try:
 except ImportError:
     raise RuntimeError("No tensorboardX package is found. Please install with the command: \npip install tensorboardX")
 
-from ignite.engines import Events, create_supervised_trainer, create_supervised_evaluator
+from ignite.engine import Events, create_supervised_trainer, create_supervised_evaluator
 from ignite.metrics import CategoricalAccuracy, Loss
 
 
diff --git a/examples/mnist_with_visdom.py b/examples/mnist_with_visdom.py
index 8114bfcd..e6e994b4 100644
--- a/examples/mnist_with_visdom.py
+++ b/examples/mnist_with_visdom.py
@@ -14,7 +14,7 @@ try:
 except ImportError:
     raise RuntimeError("No visdom package is found. Please install it with command: \n pip install visdom")
 
-from ignite.engines import Events, create_supervised_trainer, create_supervised_evaluator
+from ignite.engine import Events, create_supervised_trainer, create_supervised_evaluator
 from ignite.metrics import CategoricalAccuracy, Loss
 
 
diff --git a/ignite/engines/__init__.py b/ignite/engine/__init__.py
similarity index 96%
rename from ignite/engines/__init__.py
rename to ignite/engine/__init__.py
index 1a45aea9..6f9aefeb 100644
--- a/ignite/engines/__init__.py
+++ b/ignite/engine/__init__.py
@@ -1,6 +1,6 @@
 import torch
 
-from ignite.engines.engine import Engine, Events, State
+from ignite.engine.engine import Engine, State, Events
 from ignite._utils import convert_tensor
 
 
diff --git a/ignite/engines/engine.py b/ignite/engine/engine.py
similarity index 94%
rename from ignite/engines/engine.py
rename to ignite/engine/engine.py
index 30802762..191fb704 100644
--- a/ignite/engines/engine.py
+++ b/ignite/engine/engine.py
@@ -10,7 +10,7 @@ IS_PYTHON2 = sys.version_info[0] < 3
 
 
 class Events(Enum):
-    """Events that are fired by the :class:`ignite.engines.Engine` during execution"""
+    """Events that are fired by the :class:`ignite.engine.Engine` during execution"""
     EPOCH_STARTED = "epoch_started"
     EPOCH_COMPLETED = "epoch_completed"
     STARTED = "started"
@@ -71,7 +71,7 @@ class Engine(object):
         """Add an event handler to be executed when the specified event is fired
 
         Args:
-            event_name (Events): event from ignite.engines.Events to attach the handler to
+            event_name (Events): event from ignite.engine.Events to attach the handler to
             handler (Callable): the callable event handler that should be invoked
             *args: optional args to be passed to `handler`
             **kwargs: optional keyword args to be passed to `handler`
@@ -194,7 +194,7 @@ class Engine(object):
         self.state = State(dataloader=data, epoch=0, max_epochs=max_epochs, metrics={})
 
         try:
-            self._logger.info("Training starting with max_epochs={}".format(max_epochs))
+            self._logger.info("Engine run starting with max_epochs={}".format(max_epochs))
             start_time = time.time()
             self._fire_event(Events.STARTED)
             while self.state.epoch < max_epochs and not self.should_terminate:
@@ -209,10 +209,10 @@ class Engine(object):
             self._fire_event(Events.COMPLETED)
             time_taken = time.time() - start_time
             hours, mins, secs = _to_hours_mins_secs(time_taken)
-            self._logger.info("Training complete. Time taken %02d:%02d:%02d" % (hours, mins, secs))
+            self._logger.info("Engine run complete. Time taken %02d:%02d:%02d" % (hours, mins, secs))
 
         except BaseException as e:
-            self._logger.error("Training is terminating due to exception: %s", str(e))
+            self._logger.error("Engine run is terminating due to exception: %s", str(e))
             self._handle_exception(e)
 
         return self.state
diff --git a/ignite/handlers/checkpoint.py b/ignite/handlers/checkpoint.py
index 48cabde7..f515bf36 100644
--- a/ignite/handlers/checkpoint.py
+++ b/ignite/handlers/checkpoint.py
@@ -9,7 +9,7 @@ class ModelCheckpoint(object):
     """ ModelCheckpoint handler can be used to periodically save objects to disk.
 
     This handler accepts two arguments:
-        - an `ignite.engines.Engine` object
+        - an `ignite.engine.Engine` object
         - a `dict` mapping names (`str`) to objects that should be saved to disk.
             See Notes and Examples for further details.
 
@@ -24,7 +24,7 @@ class ModelCheckpoint(object):
             Exactly one of (`save_interval`, `score_function`) arguments must be provided.
         score_function (Callable, optional):
             if not None, it should be a function taking a single argument,
-            an `ignite.engines.Engine` object,
+            an `ignite.engine.Engine` object,
             and return a score (`float`). Objects with highest scores will be retained.
             Exactly one of (`save_interval`, `score_function`) arguments must be provided.
         score_name (str, optional):
@@ -61,7 +61,7 @@ class ModelCheckpoint(object):
 
     Examples:
         >>> import os
-        >>> from ignite.engines import Engine, Events
+        >>> from ignite.engine import Engine, Events
         >>> from ignite.handlers import ModelCheckpoint
         >>> from torch import nn
         >>> trainer = Engine(lambda batch: None)
diff --git a/ignite/handlers/early_stopping.py b/ignite/handlers/early_stopping.py
index 1a747db1..1f89985a 100644
--- a/ignite/handlers/early_stopping.py
+++ b/ignite/handlers/early_stopping.py
@@ -1,6 +1,6 @@
 import logging
 
-from ignite.engines import Engine
+from ignite.engine import Engine
 
 
 class EarlyStopping(object):
@@ -10,14 +10,14 @@ class EarlyStopping(object):
         patience (int):
             Number of events to wait if no improvement and then stop the training
         score_function (Callable):
-            It should be a function taking a single argument, an `ignite.engines.Engine` object,
+            It should be a function taking a single argument, an `ignite.engine.Engine` object,
             and return a score `float`. An improvement is considered if the score is higher.
 
     Examples:
 
     .. code-block:: python
 
-        from ignite.engines import Engine, Events
+        from ignite.engine import Engine, Events
         from ignite.handlers import EarlyStopping
 
         def score_function(engine):
diff --git a/ignite/handlers/timing.py b/ignite/handlers/timing.py
index d4083df2..1a45367f 100644
--- a/ignite/handlers/timing.py
+++ b/ignite/handlers/timing.py
@@ -1,4 +1,4 @@
-from ignite.engines import Events
+from ignite.engine import Events
 
 try:
     from time import perf_counter
@@ -64,8 +64,7 @@ class Timer:
         0.10016545779653825
 
         Using the Timer to measure average time it takes to process a single batch of examples
-
-        >>> from ignite.engines import Engine, Events
+        >>> from ignite.engine import Engine, Events
         >>> from ignite.handlers import Timer
         >>> trainer = Engine(training_update_function)
         >>> timer = Timer(average=True)
@@ -88,15 +87,15 @@ class Timer:
         """ Register callbacks to control the timer.
 
         Args:
-            engine (ignite.engines.Engine):
+            engine (ignite.engine.Engine):
                 Engine that this timer will be attached to
-            start (ignite.engines.Events):
+            start (ignite.engine.Events):
                 Event which should start (reset) the timer
-            pause (ignite.engines.Events):
+            pause (ignite.engine.Events):
                 Event which should pause the timer
-            resume (ignite.engines.Events, optional):
+            resume (ignite.engine.Events, optional):
                 Event which should resume the timer
-            step (ignite.engines.Events, optional):
+            step (ignite.engine.Events, optional):
                 Event which should call the `step` method of the counter
 
         Returns:
diff --git a/ignite/metrics/metric.py b/ignite/metrics/metric.py
index 33ddc14f..f65e91d2 100644
--- a/ignite/metrics/metric.py
+++ b/ignite/metrics/metric.py
@@ -1,6 +1,6 @@
 from abc import ABCMeta, abstractmethod
 
-from ignite.engines import Events
+from ignite.engine import Events
 
 
 class Metric(object):


Test patch:
diff --git a/tests/ignite/engines/test_engine.py b/tests/ignite/engines/test_engine.py
index a5cae67d..a77fc4d2 100644
--- a/tests/ignite/engines/test_engine.py
+++ b/tests/ignite/engines/test_engine.py
@@ -10,7 +10,7 @@ from torch.nn import Linear
 from torch.nn.functional import mse_loss
 from torch.optim import SGD
 
-from ignite.engines import Engine, Events, State, create_supervised_trainer, create_supervised_evaluator
+from ignite.engine import Engine, Events, State, create_supervised_trainer, create_supervised_evaluator
 from ignite.metrics import MeanSquaredError
 
 
diff --git a/tests/ignite/handlers/test_checkpoint.py b/tests/ignite/handlers/test_checkpoint.py
index 043500a3..c6126af8 100644
--- a/tests/ignite/handlers/test_checkpoint.py
+++ b/tests/ignite/handlers/test_checkpoint.py
@@ -6,7 +6,7 @@ import torch
 import torch.nn as nn
 import shutil
 
-from ignite.engines import Engine, Events
+from ignite.engine import Engine, Events
 from ignite.handlers import ModelCheckpoint
 
 _PREFIX = 'PREFIX'
diff --git a/tests/ignite/handlers/test_early_stopping.py b/tests/ignite/handlers/test_early_stopping.py
index 0044e024..db1b8b9f 100644
--- a/tests/ignite/handlers/test_early_stopping.py
+++ b/tests/ignite/handlers/test_early_stopping.py
@@ -1,7 +1,7 @@
 
 import pytest
 
-from ignite.engines import Engine, Events
+from ignite.engine import Engine, Events
 from ignite.handlers import EarlyStopping
 
 
diff --git a/tests/ignite/handlers/test_timing.py b/tests/ignite/handlers/test_timing.py
index ab0dc606..1044054d 100644
--- a/tests/ignite/handlers/test_timing.py
+++ b/tests/ignite/handlers/test_timing.py
@@ -1,6 +1,6 @@
 import time
 
-from ignite.engines import Engine, Events
+from ignite.engine import Engine, Events
 from ignite.handlers import Timer
 
 
diff --git a/tests/ignite/metrics/test_metric.py b/tests/ignite/metrics/test_metric.py
index 4ee6d0e6..070fea20 100644
--- a/tests/ignite/metrics/test_metric.py
+++ b/tests/ignite/metrics/test_metric.py
@@ -1,5 +1,5 @@
 from ignite.metrics import Metric
-from ignite.engines import State
+from ignite.engine import State
 import torch
 from mock import MagicMock