Added some comments to help navigating within core.py. It’s just gotten too long. :)

simpy/core.py

@@ -14,6 +14,18 @@ if PY2:
     import sys
 
 
+# Contents:
+#
+# - Constants
+# - Helpers and exceptions
+# - Event types
+# - Environments
+# - Internal helpers
+
+###############################################################################
+# Constants
+#
+
 Infinity = float('inf')  #: Convenience alias for infinity
 
 PENDING = object()       #: Unique object to identify pending values of events
@@ -23,6 +35,11 @@ DEFAULT_PRIORITY = 1     #: Default priority used by events
 LOW_PRIORITY = 2         #: Priority of timeouts
 
 
+###############################################################################
+# Helpers and exceptions
+#
+
+
 class BoundClass(object):
     """Allows classes to behave like methods.
 
@@ -80,6 +97,17 @@ class Interrupt(Exception):
         return self.args[0]
 
 
+class EmptySchedule(Exception):
+    """Thrown by the :class:`Environment` if there are no further events to be
+    processed."""
+    pass
+
+
+###############################################################################
+# Event types
+#
+
+
 class Event(object):
     """Base class for all events.
 
@@ -527,10 +555,9 @@ class Process(Event):
         self.env._active_proc = None
 
 
-class EmptySchedule(Exception):
-    """Thrown by the :class:`Environment` if there are no further events to be
-    processed."""
-    pass
+###############################################################################
+# Environments
+#
 
 
 class BaseEnvironment(object):
@@ -691,6 +718,11 @@ class Environment(BaseEnvironment):
             raise event._value
 
 
+###############################################################################
+# Internal helpers
+#
+
+
 def _describe_frame(frame):
     """Print filename, line number and function name of a stack frame."""
     filename, name = frame.f_code.co_filename, frame.f_code.co_name