_tools: extract most utility methods to a private package.

We don't want to guarantee backwards compatibility for most of them.

nmigen/_tools.py

@@ -0,0 +1,84 @@
+import contextlib
+import functools
+import warnings
+from collections import OrderedDict
+from collections.abc import Iterable
+from contextlib import contextmanager
+
+from .tools import *
+
+
+__all__ = ["flatten", "union" , "log2_int", "bits_for", "memoize", "final", "deprecated"]
+
+
+def flatten(i):
+    for e in i:
+        if isinstance(e, Iterable):
+            yield from flatten(e)
+        else:
+            yield e
+
+
+def union(i, start=None):
+    r = start
+    for e in i:
+        if r is None:
+            r = e
+        else:
+            r |= e
+    return r
+
+
+def memoize(f):
+    memo = OrderedDict()
+    @functools.wraps(f)
+    def g(*args):
+        if args not in memo:
+            memo[args] = f(*args)
+        return memo[args]
+    return g
+
+
+def final(cls):
+    def init_subclass():
+        raise TypeError("Subclassing {}.{} is not supported"
+                        .format(cls.__module__, cls.__name__))
+    cls.__init_subclass__ = init_subclass
+    return cls
+
+
+def deprecated(message, stacklevel=2):
+    def decorator(f):
+        @functools.wraps(f)
+        def wrapper(*args, **kwargs):
+            warnings.warn(message, DeprecationWarning, stacklevel=stacklevel)
+            return f(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def _ignore_deprecated(f=None):
+    if f is None:
+        @contextlib.contextmanager
+        def context_like():
+            with warnings.catch_warnings():
+                warnings.filterwarnings(action="ignore", category=DeprecationWarning)
+                yield
+        return context_like()
+    else:
+        @functools.wraps(f)
+        def decorator_like(*args, **kwargs):
+            with warnings.catch_warnings():
+                warnings.filterwarnings(action="ignore", category=DeprecationWarning)
+                f(*args, **kwargs)
+        return decorator_like
+
+
+def extend(cls):
+    def decorator(f):
+        if isinstance(f, property):
+            name = f.fget.__name__
+        else:
+            name = f.__name__
+        setattr(cls, name, f)
+    return decorator

nmigen/back/pysim.py

@@ -6,7 +6,7 @@ from bitarray import bitarray
 from vcd import VCDWriter
 from vcd.gtkw import GTKWSave
 
-from ..tools import flatten
+from .._tools import flatten
 from ..hdl.ast import *
 from ..hdl.ir import *
 from ..hdl.xfrm import ValueVisitor, StatementVisitor

nmigen/back/rtlil.py

@@ -3,7 +3,7 @@ import textwrap
 from collections import defaultdict, OrderedDict
 from contextlib import contextmanager
 
-from ..tools import bits_for, flatten
+from .._tools import bits_for, flatten
 from ..hdl import ast, rec, ir, mem, xfrm
 
 

nmigen/compat/fhdl/bitcontainer.py

@@ -1,6 +1,6 @@
 from ... import tools
 from ...hdl import ast
-from ...tools import deprecated
+from ..._tools import deprecated
 
 
 __all__ = ["log2_int", "bits_for", "value_bits_sign"]

nmigen/compat/fhdl/module.py

@@ -1,6 +1,6 @@
 from collections.abc import Iterable
 
-from ...tools import flatten, deprecated
+from ..._tools import flatten, deprecated
 from ...hdl import dsl, ir
 
 
@@ -97,7 +97,7 @@ class _CompatModuleClockDomains(_CompatModuleProxy):
 class CompatModule(ir.Elaboratable):
     _Elaboratable__silence = True
 
-    # Actually returns nmigen.fhdl.Module, not a Fragment.
+    # Actually returns another nMigen Elaboratable (nmigen.dsl.Module), not a Fragment.
     def get_fragment(self):
         assert not self.get_fragment_called
         self.get_fragment_called = True

nmigen/compat/fhdl/specials.py

@@ -1,6 +1,6 @@
 import warnings
 
-from ...tools import deprecated, extend
+from ..._tools import deprecated, extend
 from ...hdl.ast import *
 from ...hdl.ir import Elaboratable
 from ...hdl.mem import Memory as NativeMemory

nmigen/compat/fhdl/structure.py

@@ -1,6 +1,6 @@
 from collections import OrderedDict
 
-from ...tools import deprecated, extend
+from ..._tools import deprecated, extend
 from ...hdl import ast
 from ...hdl.ast import (DUID, Value, Signal, Mux, Slice as _Slice, Cat, Repl, Const, C,
                         ClockSignal, ResetSignal,

nmigen/compat/genlib/cdc.py

@@ -1,6 +1,6 @@
 import warnings
 
-from ...tools import deprecated
+from ..._tools import deprecated
 from ...lib.cdc import FFSynchronizer as NativeFFSynchronizer
 from ...hdl.ast import *
 from ..fhdl.module import CompatModule

nmigen/compat/genlib/fifo.py

@@ -1,4 +1,4 @@
-from ...tools import deprecated, extend
+from ..._tools import deprecated, extend
 from ...lib.fifo import (FIFOInterface as NativeFIFOInterface,
   SyncFIFO as NativeSyncFIFO, SyncFIFOBuffered as NativeSyncFIFOBuffered,
   AsyncFIFO as NativeAsyncFIFO, AsyncFIFOBuffered as NativeAsyncFIFOBuffered)

nmigen/compat/genlib/fsm.py

@@ -1,6 +1,6 @@
 from collections import OrderedDict
 
-from ...tools import _ignore_deprecated
+from ..._tools import _ignore_deprecated
 from ...hdl.xfrm import ValueTransformer, StatementTransformer
 from ...hdl.ast import *
 from ..fhdl.module import CompatModule, CompatFinalizeError

nmigen/compat/genlib/resetsync.py

@@ -1,4 +1,4 @@
-from ...tools import deprecated
+from ..._tools import deprecated
 from ...lib.cdc import ResetSynchronizer as NativeResetSynchronizer
 
 

nmigen/hdl/ast.py

@@ -8,7 +8,7 @@ from collections.abc import Iterable, MutableMapping, MutableSet, MutableSequenc
 from enum import Enum
 
 from .. import tracer
-from ..tools import *
+from .._tools import *
 
 
 __all__ = [

nmigen/hdl/dsl.py

@@ -4,7 +4,7 @@ from contextlib import contextmanager
 from enum import Enum
 import warnings
 
-from ..tools import flatten, bits_for, deprecated
+from .._tools import flatten, bits_for, deprecated
 from .. import tracer
 from .ast import *
 from .ir import *

nmigen/hdl/ir.py

@@ -5,7 +5,7 @@ import warnings
 import traceback
 import sys
 
-from ..tools import *
+from .._tools import *
 from .ast import *
 from .cd import *
 

nmigen/hdl/rec.py

@@ -3,7 +3,7 @@ from collections import OrderedDict
 from functools import reduce
 
 from .. import tracer
-from ..tools import union, deprecated
+from .._tools import union, deprecated
 from .ast import *
 
 

nmigen/hdl/xfrm.py

@@ -2,7 +2,7 @@ from abc import ABCMeta, abstractmethod
 from collections import OrderedDict
 from collections.abc import Iterable
 
-from ..tools import flatten, deprecated
+from .._tools import flatten, deprecated
 from .. import tracer
 from .ast import *
 from .ast import _StatementList

nmigen/lib/cdc.py

@@ -1,4 +1,4 @@
-from ..tools import deprecated
+from .._tools import deprecated
 from .. import *
 
 

nmigen/lib/fifo.py

@@ -2,7 +2,7 @@
 
 from .. import *
 from ..asserts import *
-from ..tools import log2_int, deprecated
+from .._tools import log2_int, deprecated
 from .coding import GrayEncoder
 from .cdc import FFSynchronizer
 

nmigen/test/compat/support.py

@@ -1,4 +1,4 @@
-from ...tools import _ignore_deprecated
+from ..._tools import _ignore_deprecated
 from ...compat import *
 from ...compat.fhdl import verilog
 

nmigen/test/compat/test_size.py

@@ -1,6 +1,6 @@
 import unittest
 
-from ...tools import _ignore_deprecated
+from ..._tools import _ignore_deprecated
 from ...compat import *
 
 

nmigen/test/test_sim.py

@@ -1,7 +1,7 @@
 from contextlib import contextmanager
 
 from .tools import *
-from ..tools import flatten, union
+from .._tools import flatten, union
 from ..hdl.ast import *
 from ..hdl.cd import  *
 from ..hdl.mem import *

nmigen/tools.py

@@ -1,30 +1,4 @@
-import contextlib
+__all__ = ["log2_int", "bits_for"]
-import functools
-import warnings
-from collections import OrderedDict
-from collections.abc import Iterable
-from contextlib import contextmanager
-
-
-__all__ = ["flatten", "union", "log2_int", "bits_for", "memoize", "final", "deprecated"]
-
-
-def flatten(i):
-    for e in i:
-        if isinstance(e, Iterable):
-            yield from flatten(e)
-        else:
-            yield e
-
-
-def union(i, start=None):
-    r = start
-    for e in i:
-        if r is None:
-            r = e
-        else:
-            r |= e
-    return r
 
 
 def log2_int(n, need_pow2=True):
@@ -45,58 +19,3 @@ def bits_for(n, require_sign_bit=False):
     if require_sign_bit:
         r += 1
     return r
-
-
-def memoize(f):
-    memo = OrderedDict()
-    @functools.wraps(f)
-    def g(*args):
-        if args not in memo:
-            memo[args] = f(*args)
-        return memo[args]
-    return g
-
-
-def final(cls):
-    def init_subclass():
-        raise TypeError("Subclassing {}.{} is not supported"
-                        .format(cls.__module__, cls.__name__))
-    cls.__init_subclass__ = init_subclass
-    return cls
-
-
-def deprecated(message, stacklevel=2):
-    def decorator(f):
-        @functools.wraps(f)
-        def wrapper(*args, **kwargs):
-            warnings.warn(message, DeprecationWarning, stacklevel=stacklevel)
-            return f(*args, **kwargs)
-        return wrapper
-    return decorator
-
-
-def _ignore_deprecated(f=None):
-    if f is None:
-        @contextlib.contextmanager
-        def context_like():
-            with warnings.catch_warnings():
-                warnings.filterwarnings(action="ignore", category=DeprecationWarning)
-                yield
-        return context_like()
-    else:
-        @functools.wraps(f)
-        def decorator_like(*args, **kwargs):
-            with warnings.catch_warnings():
-                warnings.filterwarnings(action="ignore", category=DeprecationWarning)
-                f(*args, **kwargs)
-        return decorator_like
-
-
-def extend(cls):
-    def decorator(f):
-        if isinstance(f, property):
-            name = f.fget.__name__
-        else:
-            name = f.__name__
-        setattr(cls, name, f)
-    return decorator