amaranth.hdl: start all private names with an underscore.

This change completes commit 9dc0617 and makes all the tests pass.
It corresponds with the ongoing langauge reference documentation effort.

Fixes #781.

Author: whitequark

amaranth/asserts.py

@@ -1,4 +1,4 @@
-from .hdl.ast import AnyConst, AnySeq, Initial, Assert, Assume, Cover
+from .hdl._ast import AnyConst, AnySeq, Initial, Assert, Assume, Cover
 
 
 __all__ = ["AnyConst", "AnySeq", "Initial", "Assert", "Assume", "Cover"]

amaranth/back/rtlil.py

@@ -1,5 +1,5 @@
 from .._toolchain.yosys import *
-from ..hdl import ast, ir
+from ..hdl import _ast, _ir
 from ..lib import wiring
 from . import rtlil
 
@@ -49,12 +49,12 @@ def convert(elaboratable, name="top", platform=None, *, ports=None, emit_src=Tru
             isinstance(elaboratable.signature, wiring.Signature)):
         ports = []
         for path, member, value in elaboratable.signature.flatten(elaboratable):
-            if isinstance(value, ast.ValueCastable):
+            if isinstance(value, _ast.ValueCastable):
                 value = value.as_value()
-            if isinstance(value, ast.Value):
+            if isinstance(value, _ast.Value):
                 ports.append(value)
     elif ports is None:
         raise TypeError("The `convert()` function requires a `ports=` argument")
-    fragment = ir.Fragment.get(elaboratable, platform).prepare(ports=ports, **kwargs)
+    fragment = _ir.Fragment.get(elaboratable, platform).prepare(ports=ports, **kwargs)
     verilog_text, name_map = convert_fragment(fragment, name, emit_src=emit_src, strip_internal_attrs=strip_internal_attrs)
     return verilog_text

amaranth/back/verilog.py

@@ -9,7 +9,7 @@
 from .. import __version__
 from .._toolchain import *
 from ..hdl import *
-from ..hdl.xfrm import DomainLowerer
+from ..hdl._xfrm import DomainLowerer
 from ..lib.cdc import ResetSynchronizer
 from ..back import rtlil, verilog
 from .res import *

amaranth/build/plat.py

@@ -1,7 +1,7 @@
 from collections import OrderedDict
 import warnings
 
-from ..hdl.ast import *
+from ..hdl._ast import *
 with warnings.catch_warnings():
     warnings.filterwarnings(action="ignore", category=DeprecationWarning)
     from ..hdl.rec import *

amaranth/build/res.py

@@ -1,6 +1,6 @@
 import argparse
 
-from .hdl.ir import Fragment
+from .hdl._ir import Fragment
 from .back import rtlil, cxxrtl, verilog
 from .sim import Simulator
 

amaranth/cli.py

@@ -1,24 +1,29 @@
-import warnings
-
-from .ast import Shape, unsigned, signed
-from .ast import Value, Const, C, Mux, Cat, Repl, Array, Signal, ClockSignal, ResetSignal
-from .dsl import Module
-from .cd import ClockDomain
-from .ir import Elaboratable, Fragment, Instance
-from .mem import Memory
-with warnings.catch_warnings():
-    warnings.filterwarnings(action="ignore", category=DeprecationWarning)
-    from .rec import Record
-from .xfrm import DomainRenamer, ResetInserter, EnableInserter
+from ._ast import Shape, unsigned, signed, ShapeCastable, ShapeLike
+from ._ast import Value, ValueCastable, ValueLike
+from ._ast import Const, C, Mux, Cat, Repl, Array, Signal, ClockSignal, ResetSignal
+from ._dsl import SyntaxError, SyntaxWarning, Module
+from ._cd import DomainError, ClockDomain
+from ._ir import UnusedElaboratable, Elaboratable, DriverConflict, Fragment, Instance
+from ._mem import Memory, ReadPort, WritePort, DummyPort
+from ._rec import Record
+from ._xfrm import DomainRenamer, ResetInserter, EnableInserter
 
 
 __all__ = [
-    "Shape", "unsigned", "signed",
-    "Value", "Const", "C", "Mux", "Cat", "Repl", "Array", "Signal", "ClockSignal", "ResetSignal",
-    "Module",
-    "ClockDomain",
-    "Elaboratable", "Fragment", "Instance",
-    "Memory",
+    # _ast
+    "Shape", "unsigned", "signed", "ShapeCastable", "ShapeLike",
+    "Value", "ValueCastable", "ValueLike",
+    "Const", "C", "Mux", "Cat", "Repl", "Array", "Signal", "ClockSignal", "ResetSignal",
+    # _dsl
+    "SyntaxError", "SyntaxWarning", "Module",
+    # _cd
+    "DomainError", "ClockDomain",
+    # _ir
+    "UnusedElaboratable", "Elaboratable", "DriverConflict", "Fragment", "Instance",
+    # _mem
+    "Memory", "ReadPort", "WritePort", "DummyPort",
+    # _rec
     "Record",
+    # _xfrm
     "DomainRenamer", "ResetInserter", "EnableInserter",
 ]

amaranth/hdl/__init__.py

@@ -1,5 +1,5 @@
 from .. import tracer
-from .ast import Signal
+from ._ast import Signal
 
 
 __all__ = ["ClockDomain", "DomainError"]

amaranth/hdl/_cd.py

@@ -8,10 +8,10 @@
 from .._utils import flatten
 from ..utils import bits_for
 from .. import tracer
-from .ast import *
-from .ir import *
-from .cd import *
-from .xfrm import *
+from ._ast import *
+from ._ir import *
+from ._cd import *
+from ._xfrm import *
 
 
 __all__ = ["SyntaxError", "SyntaxWarning", "Module"]

amaranth/hdl/_dsl.py

@@ -6,8 +6,8 @@
 from .. import tracer
 from .._utils import *
 from .._unused import *
-from .ast import *
-from .cd import *
+from ._ast import *
+from ._cd import *
 
 
 __all__ = ["UnusedElaboratable", "Elaboratable", "DriverConflict", "Fragment", "Instance"]
@@ -263,7 +263,7 @@ def flatten_subfrags_if_needed(subfrags):
         return SignalSet(driver_subfrags.keys())
 
     def _propagate_domains_up(self, hierarchy=("top",)):
-        from .xfrm import DomainRenamer
+        from ._xfrm import DomainRenamer
 
         domain_subfrags = defaultdict(set)
 
@@ -327,7 +327,7 @@ def _propagate_domains_down(self):
             subfrag._propagate_domains_down()
 
     def _create_missing_domains(self, missing_domain, *, platform=None):
-        from .xfrm import DomainCollector
+        from ._xfrm import DomainCollector
 
         collector = DomainCollector()
         collector(self)
@@ -507,7 +507,7 @@ def lca_of(fragu, fragv):
                 self.add_ports(sig, dir="i")
 
     def prepare(self, ports=None, missing_domain=lambda name: ClockDomain(name)):
-        from .xfrm import DomainLowerer
+        from ._xfrm import DomainLowerer
 
         new_domains = self._propagate_domains(missing_domain)
         fragment = DomainLowerer()(self)

amaranth/hdl/_ir.py

@@ -2,8 +2,8 @@
 from collections import OrderedDict
 
 from .. import tracer
-from .ast import *
-from .ir import Elaboratable, Instance, Fragment
+from ._ast import *
+from ._ir import Elaboratable, Instance, Fragment
 
 
 __all__ = ["Memory", "ReadPort", "WritePort", "DummyPort"]

amaranth/hdl/_mem.py

@@ -6,7 +6,7 @@
 
 from .. import tracer
 from .._utils import union
-from .ast import *
+from ._ast import *
 from ..lib import wiring
 
 

amaranth/hdl/_rec.py

@@ -36,7 +36,7 @@ def format(self, value):
 
 class Repr:
     def __init__(self, format, value, *, path=()):
-        from .ast import Value # avoid a circular dependency
+        from ._ast import Value # avoid a circular dependency
         assert isinstance(format, Format)
         assert isinstance(value, Value)
         assert isinstance(path, tuple) and all(isinstance(part, (str, int)) for part in path)

amaranth/hdl/_repr.py

@@ -5,11 +5,11 @@
 
 from .._utils import flatten, _ignore_deprecated
 from .. import tracer
-from .ast import *
-from .ast import _StatementList
-from .cd import *
-from .ir import *
-from .mem import MemoryInstance
+from ._ast import *
+from ._ast import _StatementList
+from ._cd import *
+from ._ir import *
+from ._mem import MemoryInstance
 
 
 __all__ = ["ValueVisitor", "ValueTransformer",
@@ -286,7 +286,7 @@ def on_fragment(self, fragment):
         if isinstance(fragment, MemoryInstance):
             new_fragment = MemoryInstance(fragment.memory, [], [])
             self.map_memory_ports(fragment, new_fragment)
-        elif isinstance(fragment, Instance):            
+        elif isinstance(fragment, Instance):
             new_fragment = Instance(fragment.type, src_loc=fragment.src_loc)
             new_fragment.parameters = OrderedDict(fragment.parameters)
             self.map_named_ports(fragment, new_fragment)

amaranth/hdl/_xfrm.py

@@ -6,7 +6,7 @@
 from amaranth._utils import final
 from amaranth.hdl import *
 from amaranth.hdl._repr import *
-from amaranth.hdl.ast import ShapeCastable, ValueCastable
+from amaranth.hdl._ast import ShapeCastable, ValueCastable
 
 
 __all__ = [

amaranth/lib/data.py

@@ -2,7 +2,7 @@
 import warnings
 import operator
 
-from ..hdl.ast import Value, ValueCastable, Shape, ShapeCastable, Const
+from ..hdl._ast import Value, ValueCastable, Shape, ShapeCastable, Const
 from ..hdl._repr import *
 
 

amaranth/lib/enum.py

@@ -4,8 +4,8 @@
 import warnings
 
 from .. import tracer
-from ..hdl.ast import Shape, ShapeCastable, Const, Signal, Value, ValueCastable
-from ..hdl.ir import Elaboratable
+from ..hdl._ast import Shape, ShapeCastable, Const, Signal, Value, ValueCastable
+from ..hdl._ir import Elaboratable
 from .._utils import final
 
 

amaranth/lib/wiring.py

@@ -1,7 +1,7 @@
 import inspect
 
 from ..hdl import *
-from ..hdl.ast import Statement, SignalSet, ValueCastable
+from ..hdl._ast import Statement, SignalSet, ValueCastable
 from .core import Tick, Settle, Delay, Passive, Active
 from ._base import BaseProcess
 from ._pyrtl import _ValueCompiler, _RHSValueCompiler, _StatementCompiler

amaranth/sim/_pycoro.py

@@ -4,8 +4,8 @@
 import sys
 
 from ..hdl import *
-from ..hdl.ast import SignalSet
-from ..hdl.xfrm import ValueVisitor, StatementVisitor, LHSGroupFilter
+from ..hdl._ast import SignalSet
+from ..hdl._xfrm import ValueVisitor, StatementVisitor, LHSGroupFilter
 from ._base import BaseProcess
 
 

amaranth/sim/_pyrtl.py

@@ -2,8 +2,8 @@
 import warnings
 
 from .._utils import deprecated
-from ..hdl.cd import *
-from ..hdl.ir import *
+from ..hdl._cd import *
+from ..hdl._ir import *
 from ._base import BaseEngine
 
 
@@ -130,7 +130,7 @@ def add_clock(self, period, *, phase=None, domain="sync", if_exists=False):
         if domain in self._clocked:
             raise ValueError("Domain {!r} already has a clock driving it"
                              .format(domain.name))
-        
+
         # We represent times internally in 1 ps units, but users supply float quantities of seconds
         period = int(period * 1e12)
 

amaranth/sim/core.py

@@ -6,7 +6,7 @@
 
 from ..hdl import *
 from ..hdl._repr import *
-from ..hdl.ast import SignalDict, Slice, Operator
+from ..hdl._ast import SignalDict, Slice, Operator
 from ._base import *
 from ._pyrtl import _FragmentCompiler
 from ._pycoro import PyCoroProcess

amaranth/sim/pysim.py

@@ -86,8 +86,8 @@ Like the standard Python :class:`enum.IntEnum` and :class:`enum.IntFlag` classes
 .. doctest::
 
    >>> a = Signal(TransparentEnum)
-   >>> type(a)
-   <class 'amaranth.hdl.ast.Signal'>
+   >>> type(a) is Signal
+   True
 
 It is also possible to define a custom view class for a given enum:
 

docs/stdlib/enum.rst

@@ -1,7 +1,7 @@
 import warnings
 from enum import Enum, EnumMeta
 
-from amaranth.hdl.ast import *
+from amaranth.hdl._ast import *
 from amaranth.lib.enum import Enum as AmaranthEnum
 
 from .utils import *
@@ -1024,10 +1024,10 @@ class MyValue(ValueCastable):
             @ValueCastable.lowermethod
             def as_value(self):
                 return Signal()
-            
+
             def shape():
                 return unsigned(1)
-        
+
         a = Array([1,2,3])
         a[MyValue()]
 

tests/test_hdl_ast.py

@@ -1,4 +1,4 @@
-from amaranth.hdl.cd import *
+from amaranth.hdl._cd import *
 
 from .utils import *
 

tests/test_hdl_cd.py

@@ -3,9 +3,9 @@
 import sys
 from collections import OrderedDict
 
-from amaranth.hdl.ast import *
-from amaranth.hdl.cd import *
-from amaranth.hdl.dsl import *
+from amaranth.hdl._ast import *
+from amaranth.hdl._cd import *
+from amaranth.hdl._dsl import *
 from amaranth.lib.enum import Enum
 
 from .utils import *

tests/test_hdl_dsl.py

@@ -2,10 +2,10 @@
 
 from collections import OrderedDict
 
-from amaranth.hdl.ast import *
-from amaranth.hdl.cd import *
-from amaranth.hdl.ir import *
-from amaranth.hdl.mem import *
+from amaranth.hdl._ast import *
+from amaranth.hdl._cd import *
+from amaranth.hdl._ir import *
+from amaranth.hdl._mem import *
 
 from .utils import *
 

tests/test_hdl_ir.py

@@ -1,7 +1,7 @@
 # amaranth: UnusedElaboratable=no
 
-from amaranth.hdl.ast import *
-from amaranth.hdl.mem import *
+from amaranth.hdl._ast import *
+from amaranth.hdl._mem import *
 
 from .utils import *
 

tests/test_hdl_mem.py

@@ -2,7 +2,7 @@
 
 from enum import Enum
 
-from amaranth.hdl.ast import *
+from amaranth.hdl._ast import *
 with warnings.catch_warnings():
     warnings.filterwarnings(action="ignore", category=DeprecationWarning)
     from amaranth.hdl.rec import *