Convert examples and testing to be more namespace friendly.

Author: HexDecimal

.github/workflows/python-package.yml

@@ -191,7 +191,7 @@ jobs:
           pip install tcod-*.tar.gz
       - name: Confirm package import
         run: |
-          python -c "import tcod"
+          python -c "import tcod.context"
 
   linux-wheels:
     needs: [black, isort, mypy]
@@ -232,7 +232,7 @@ jobs:
             yum-config-manager --enable epel &&
             yum install -y SDL2-devel
           CIBW_BEFORE_TEST: pip install numpy
-          CIBW_TEST_COMMAND: python -c "import tcod"
+          CIBW_TEST_COMMAND: python -c "import tcod.context"
           # Skip test on emulated architectures
           CIBW_TEST_SKIP: "*_aarch64"
       - name: Archive wheel
@@ -267,7 +267,7 @@ jobs:
           CIBW_ARCHS_MACOS: x86_64 arm64 universal2
           CIBW_BEFORE_BUILD_MACOS: pip install --upgrade delocate
           CIBW_BEFORE_TEST: pip install numpy
-          CIBW_TEST_COMMAND: python -c "import tcod"
+          CIBW_TEST_COMMAND: python -c "import tcod.context"
           CIBW_TEST_SKIP: "pp* *-macosx_arm64 *-macosx_universal2:arm64"
       - name: Archive wheel
         uses: actions/upload-artifact@v3

docs/installation.rst

@@ -50,9 +50,9 @@ You can then verify that ``tcod`` is importable from the Python interpreter::
 
     >python
 
-    >>> import tcod
+    >>> import tcod.context
 
-If ``import tcod`` doesn't throw an ``ImportError`` then ``tcod`` has been installed correctly to your system libraries.
+If ``import tcod.context`` doesn't throw an ``ImportError`` then ``tcod`` has been installed correctly to your system libraries.
 
 Some IDE's such as PyCharm will create a virtual environment which will ignore your system libraries and require tcod to be installed again in that new environment.
 

docs/tcod/getting-started.rst

@@ -23,7 +23,10 @@ Example::
 
     #!/usr/bin/env python3
     # Make sure 'dejavu10x10_gs_tc.png' is in the same directory as this script.
-    import tcod
+    import tcod.console
+    import tcod.context
+    import tcod.event
+    import tcod.tileset
 
     WIDTH, HEIGHT = 80, 60  # Console width and height in tiles.
 
@@ -35,7 +38,7 @@ Example::
             "dejavu10x10_gs_tc.png", 32, 8, tcod.tileset.CHARMAP_TCOD,
         )
         # Create the main console.
-        console = tcod.Console(WIDTH, HEIGHT, order="F")
+        console = tcod.console.Console(WIDTH, HEIGHT, order="F")
         # Create a window based on this console and tileset.
         with tcod.context.new(  # New window for a console of size columns×rows.
             columns=console.width, rows=console.height, tileset=tileset,
@@ -87,7 +90,8 @@ clearing the console every frame and replacing it only on resizing the window.
 Example::
 
     #!/usr/bin/env python3
-    import tcod
+    import tcod.context
+    import tcod.event
 
     WIDTH, HEIGHT = 720, 480  # Window pixel resolution (when not maximized.)
     FLAGS = tcod.context.SDL_WINDOW_RESIZABLE | tcod.context.SDL_WINDOW_MAXIMIZED

examples/distribution/PyInstaller/main.py

@@ -7,7 +7,10 @@
 import sys
 from pathlib import Path
 
-import tcod
+import tcod.console
+import tcod.context
+import tcod.event
+import tcod.tileset
 
 WIDTH, HEIGHT = 80, 60
 

examples/distribution/cx_Freeze/main.py

@@ -1,6 +1,9 @@
 #!/usr/bin/env python3
 """cx_Freeze main script example."""
-import tcod
+import tcod.console
+import tcod.context
+import tcod.event
+import tcod.tileset
 
 WIDTH, HEIGHT = 80, 60
 console = None

examples/eventget.py

@@ -6,7 +6,8 @@
 """An demonstration of event handling using the tcod.event module."""
 from typing import List, Set
 
-import tcod
+import tcod.context
+import tcod.event
 import tcod.sdl.joystick
 import tcod.sdl.sys
 

examples/sdl-hello-world.py

@@ -4,7 +4,7 @@
 import numpy as np
 from PIL import Image, ImageDraw, ImageFont  # type: ignore  # pip install Pillow
 
-import tcod
+import tcod.event
 import tcod.sdl.render
 import tcod.sdl.video
 

examples/thread_jobs.py

@@ -20,7 +20,7 @@
 import timeit
 from typing import Callable, List, Tuple
 
-import tcod
+import tcod.map
 
 THREADS = multiprocessing.cpu_count()
 

examples/ttf.py

@@ -14,7 +14,10 @@
 import numpy as np
 from numpy.typing import NDArray
 
-import tcod
+import tcod.console
+import tcod.context
+import tcod.event
+import tcod.tileset
 
 FONT = "VeraMono.ttf"
 
@@ -60,7 +63,7 @@ def load_ttf(path: str, size: Tuple[int, int]) -> tcod.tileset.Tileset:
 
 def main() -> None:
     """True-type font example script."""
-    console = tcod.Console(16, 12, order="F")
+    console = tcod.console.Console(16, 12, order="F")
     with tcod.context.new(
         columns=console.width,
         rows=console.height,

tcod/console.py

@@ -1087,7 +1087,7 @@ def draw_frame(
 
         Example::
 
-            >>> console = tcod.Console(12, 6)
+            >>> console = tcod.console.Console(12, 6)
             >>> console.draw_frame(x=0, y=0, width=3, height=3)
             >>> console.draw_frame(x=3, y=0, width=3, height=3, decoration="╔═╗║ ║╚═╝")
             >>> console.draw_frame(x=6, y=0, width=3, height=3, decoration="123456789")
@@ -1272,7 +1272,8 @@ def load_xp(path: str | PathLike[str], order: Literal["C", "F"] = "C") -> tuple[
     Example::
 
         import numpy as np
-        import tcod
+        import tcod.console
+        import tcod.tileset
 
         path = "example.xp"  # REXPaint file with one layer.
 
@@ -1321,9 +1322,10 @@ def save_xp(
     Example::
 
         import numpy as np
-        import tcod
+        import tcod.console
+        import tcod.tileset
 
-        console = tcod.Console(80, 24)  # Example console.
+        console = tcod.console.Console(80, 24)  # Example console.
 
         # Convert from Unicode to REXPaint's encoding.
         # Required to load this console correctly in the REXPaint tool.