jupyter-turtle 1.0.1__tar.gz

jupyter_turtle-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Mike Matera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jupyter_turtle-1.0.1/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: jupyter-turtle
+Version: 1.0.1
+Summary: Simplified Turtle graphics for the Jupyter Notebook
+Author-email: Mike Matera <michael.matera@cabrillo.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mike-matera/jupyter-turtle
+Project-URL: Issues, https://github.com/mike-matera/jupyter-turtle/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipycanvas
+Requires-Dist: jupyterlab
+Dynamic: license-file
+
+# Jupyter Turtle 
+
+This is an implementation of simplified Turtle graphics to support my [Python
+for Everyone](https://github.com/mike-matera/python-for-everyone) course.
+[Logo](https://en.wikipedia.org/wiki/Logo_\(programming_language\)) was my first
+programming language. The purpose of this implementation is to give beginners a
+visual experience to help them understand algorithmic reasoning. The module
+contains a `Turtle` class implementation with a full API and a simplified API
+that I use in class. 
+

jupyter_turtle-1.0.1/README.md

@@ -0,0 +1,10 @@
+# Jupyter Turtle 
+
+This is an implementation of simplified Turtle graphics to support my [Python
+for Everyone](https://github.com/mike-matera/python-for-everyone) course.
+[Logo](https://en.wikipedia.org/wiki/Logo_\(programming_language\)) was my first
+programming language. The purpose of this implementation is to give beginners a
+visual experience to help them understand algorithmic reasoning. The module
+contains a `Turtle` class implementation with a full API and a simplified API
+that I use in class. 
+

jupyter_turtle-1.0.1/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "jupyter-turtle"
+authors = [
+    {name = "Mike Matera", email = "michael.matera@cabrillo.edu"},
+]
+description = "Simplified Turtle graphics for the Jupyter Notebook"
+readme = "README.md"
+requires-python = ">=3.9"
+version = "1.0.1"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+dependencies = [
+    "ipycanvas",
+    "jupyterlab",
+]
+
+[project.urls]
+Homepage = "https://github.com/mike-matera/jupyter-turtle"
+Issues = "https://github.com/mike-matera/jupyter-turtle/issues"
+
+[tool.setuptools.package-data]
+jupyter_turtle = ["*.png"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+line-length = 79
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true

jupyter_turtle-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jupyter_turtle-1.0.1/src/jupyter_turtle/__init__.py

@@ -0,0 +1,201 @@
+import contextlib
+from typing import Sequence, Tuple, Union
+
+from IPython.display import display
+
+from .turtle import DimPoint, Turtle
+
+_turtle = None
+
+# The simplified API.
+
+
+def _check_turtle():
+    global _turtle
+    if _turtle is None:
+        _turtle = Turtle()
+        _turtle.stats = {
+            "moves": 0,
+            "jumps": 0,
+            "strokes": 0,
+            "turns": 0,
+            "words": [],
+            "_last_down": 0,
+        }
+        display(_turtle)
+    return _turtle
+
+
+def clear():
+    """Clear the canvas."""
+    tu = _check_turtle()
+    _turtle.stats = {
+        "moves": 0,
+        "jumps": 0,
+        "strokes": 0,
+        "turns": 0,
+        "words": [],
+        "_last_down": 0,
+    }
+    tu.clear()
+
+
+def move(distance: float):
+    """Move the turtle by distance pixels."""
+    tu = _check_turtle()
+    tu.stats["moves"] += 1
+    tu.move(distance)
+
+
+def turn(degrees: float):
+    """Turn the pen by degrees. Positive numbers turn left, negative numbers
+    turn right."""
+    tu = _check_turtle()
+    tu.stats["turns"] += 1
+    tu.turn(degrees)
+
+
+def pen_up():
+    """Pick the pen up. Movements won't make lines."""
+    tu = _check_turtle()
+    if tu.stats["moves"] > tu.stats["_last_down"]:
+        tu.stats["strokes"] += 1
+    tu.pen_up()
+
+
+def pen_down():
+    """Put the pen down. Movements will make lines."""
+    tu = _check_turtle()
+    tu.stats["_last_down"] = tu.stats["moves"]
+    tu.pen_down()
+
+
+def show_turtle():
+    """Show the turtle in the scene."""
+    tu = _check_turtle()
+    tu.show()
+
+
+def hide_turtle():
+    """Hide the turtle in the scene."""
+    tu = _check_turtle()
+    tu.hide()
+
+
+def write(
+    text: str, font: str = "24px sans-serif", text_align: str = "center"
+):
+    """Write text.
+
+    Arguments:
+
+        text: The text to write
+        font: The HTML font specification
+        text_align: The alignment of the text relative to the turtle
+    """
+    tu = _check_turtle()
+    tu.stats["words"].append(text)
+    tu.write(text, font, text_align)
+
+
+def goto(*place: Union[Tuple[int, int], Sequence[int], DimPoint]):
+    """Jump to a point"""
+    tu = _check_turtle()
+    tu.stats["moves"] += 1
+    tu.stats["jumps"] += 1
+    tu.pos = place
+
+
+def set_background(filename: str):
+    """Set the background image"""
+    tu = _check_turtle()
+    tu.background(filename)
+
+
+def set_heading(heading: float):
+    """Set the pen to face heading in degrees."""
+    tu = _check_turtle()
+    tu.stats["turns"] += 1
+    tu.heading = heading
+
+
+def set_color(color: Union[str, int]):
+    """Set the pen color using HTML color notation."""
+    tu = _check_turtle()
+    tu.color = color
+
+
+def set_width(width: int):
+    """Set the line thickness."""
+    tu = _check_turtle()
+    tu.width = width
+
+
+def set_size(width: int, height: int):
+    """Set the size of the arena."""
+    tu = _check_turtle()
+    tu.size = (width, height)
+
+
+@contextlib.contextmanager
+def polygon(
+    *,
+    color: str | None = None,
+    width: int | None = None,
+    fill: str | None = None,
+):
+    """
+    Draw a polygon by connecting moves together.
+
+    Example:
+
+    with tu.polygon():
+        tu.move(30)
+        tu.turn(45)
+        tu.move(30)
+        tu.turn(45)
+        tu.move(30)
+    """
+    tu = _check_turtle()
+    old_color = tu.color
+    old_width = tu.width
+    old_fill = tu.fill
+    try:
+        if color is not None:
+            tu.color = color
+        if fill is not None:
+            tu.fill = fill
+        if width is not None:
+            tu.width = width
+
+        with tu.polygon():
+            yield
+
+    finally:
+        tu.color = old_color
+        tu.fill = old_fill
+        tu.width = old_width
+
+
+def pre_run_cell(info):
+    """
+    Callback before a cell is run.
+    """
+    global _turtle
+    _turtle = None
+
+
+def post_run_cell(result):
+    """
+    Callback after a cell has run.
+    """
+    global _turtle
+    result.turtle = _turtle
+    if _turtle is not None:
+        if _turtle.stats["moves"] > _turtle.stats["_last_down"]:
+            _turtle.stats["strokes"] += 1
+
+
+def load_ipython_extension(ipython):
+    ipython.events.register("pre_run_cell", pre_run_cell)
+    ipython.events.register("post_run_cell", post_run_cell)

jupyter_turtle-1.0.1/src/jupyter_turtle/turtle.py

@@ -0,0 +1,290 @@
+"""
+A simple implementation of turtle graphics for teaching algorithms.
+
+Author: Mike Matera
+"""
+
+import colorsys
+import contextlib
+import math
+import pathlib
+from collections import namedtuple
+from collections.abc import Sequence
+
+import numpy
+import PIL
+from ipycanvas import Canvas, MultiCanvas, hold_canvas
+from IPython.display import display
+
+DimPoint = namedtuple("DimPoint", ["x", "y"])
+
+
+class Turtle:
+    def __init__(self, size: tuple[int, int] = (600, 300), **kwargs):
+        """Create a Turtle drawing canvas.
+
+        Arguments:
+            size: Set the size of the canvas.
+        """
+        # Load the Turtle image
+        turtle = numpy.array(
+            PIL.Image.open(pathlib.Path(__file__).parent / "turtle.png")
+        )
+        self._turtle = Canvas(width=turtle.shape[0], height=turtle.shape[1])
+        self._turtle.put_image_data(turtle)
+
+        # Create a new Canvas
+        self._size = DimPoint(size[0], size[1])
+        self._canvas = MultiCanvas(
+            n_canvases=3,
+            width=self._size.x,
+            height=self._size.y,
+            sync_image_data=True,
+            **kwargs,
+        )
+
+        # Initialize properties
+        self._current = self._to_native(DimPoint(0, 0))
+        self._cur_heading = (3 * math.pi) / 2  # in Canvas Y is negative.
+        self._pendown = True
+        self._show = True
+        self._fill = None
+        self._image = None
+        self._polygon = False
+
+        # Render the turtle
+        with self._do_draw():
+            self._canvas.clear()
+
+    @contextlib.contextmanager
+    def _do_draw(self):
+        """Context manager that combines all drawing operations and re-renders
+        the turtle."""
+        with hold_canvas(self._canvas):
+            yield
+            self._canvas[2].clear()
+            if self._show:
+                # Redraw the Turtle
+                self._canvas[2].save()
+                self._canvas[2].translate(self._current.x, self._current.y)
+                self._canvas[2].rotate(self._cur_heading + math.pi / 2)
+                self._canvas[2].draw_image(
+                    self._turtle, x=-15, y=-15, width=30, height=30
+                )
+                self._canvas[2].restore()
+
+    def _to_native(self, point: tuple[int, int]) -> DimPoint:
+        """Convert Turtle coordinates to native ones."""
+        return DimPoint(
+            x=self._size.x // 2 + point[0], y=self._size.y // 2 - point[1]
+        )
+
+    def _to_turtle(self, point: DimPoint) -> tuple[int, int]:
+        """Convert Turtle coordinates to native ones."""
+        return (point[0] - self._size.x // 2, self._size.y // 2 - point[1])
+
+    def _ipython_display_(self):
+        display(self._canvas)
+
+    def _move(self, to: DimPoint):
+        """Low-level move operation."""
+        start = self._current
+        self._current = to
+        with self._do_draw():
+            if self._polygon:
+                if self._pendown:
+                    self._canvas[1].line_to(*self._current)
+                else:
+                    self._canvas[1].move_to(*start)
+            else:
+                if self._pendown:
+                    self._canvas[1].begin_path()
+                    self._canvas[1].move_to(*start)
+                    self._canvas[1].line_to(*self._current)
+                    self._canvas[1].stroke()
+
+    def clear(self):
+        """Clear all drawing."""
+        self._canvas[1].clear()
+
+    def move(self, distance: float):
+        """Move the turtle by distance pixels."""
+        self._move(
+            DimPoint(
+                x=self._current.x + math.cos(self._cur_heading) * distance,
+                y=self._current.y + math.sin(self._cur_heading) * distance,
+            )
+        )
+
+    def turn(self, degrees: float):
+        """Turn the pen by degrees."""
+        with self._do_draw():
+            self._cur_heading = (self._cur_heading - math.radians(degrees)) % (
+                math.pi * 2
+            )
+
+    def pen_up(self):
+        """Pick the pen up. Movements won't make lines."""
+        self._pendown = False
+
+    def pen_down(self):
+        """Put the pen down. Movements will make lines."""
+        self._pendown = True
+
+    def show(self):
+        """Show the turtle in the scene."""
+        with self._do_draw():
+            self._show = True
+
+    def hide(self):
+        """Hide the turtle in the scene."""
+        with self._do_draw():
+            self._show = False
+
+    def background(self, filename: str):
+        """Set the background image"""
+        self._image = numpy.array(PIL.Image.open(filename))
+        self.size = (self._image.shape[1], self._image.shape[0])
+        self._canvas[0].put_image_data(self._image)
+
+    @contextlib.contextmanager
+    def polygon(self):
+        """Context manager for drawing a polygon."""
+        self._polygon = True
+        self._canvas[1].begin_path()
+        self._canvas[1].move_to(*self._current)
+        try:
+            yield
+        finally:
+            self._canvas[1].close_path()
+            self._canvas[1].stroke()
+            if self._fill is not None:
+                self._canvas[1].fill()
+            self._polygon = False
+
+    def write(
+        self,
+        text: str,
+        font: str = "24px sans-serif",
+        text_align: str = "center",
+    ):
+        """Write text.
+
+        Arguments:
+
+            text: The text to write
+            font: The HTML font specification
+            text_align: The alignment of the text relative to the turtle
+            line_color: The color of the outline of the text (defaults to the pen color)
+            fill_color: The color of the fill of the text (defaults to the pen color)
+        """
+        with self._do_draw():
+            self._canvas[1].translate(self._current.x, self._current.y)
+            self._canvas[1].rotate(self._cur_heading + math.pi / 2)
+            self._canvas[1].font = font
+            self._canvas[1].text_align = text_align
+            self._canvas[1].fill_text(text, 0, 0)
+            self._canvas[1].stroke_text(text, 0, 0)
+            self._canvas[1].reset_transform()
+
+    @property
+    def size(self) -> tuple[int, int]:
+        """Get the size of the canvas' color buffer (not layout size)."""
+        return (self._size.x, self._size.y)
+
+    @size.setter
+    def size(self, newsize: tuple[int, int]):
+        """Resize the canvas element and adjust they layout size."""
+        self._size = DimPoint(x=newsize[0], y=newsize[1])
+        with self._do_draw():
+            self._canvas.width = self._size.x
+            self._canvas.height = self._size.y
+
+            # Move the turtle to the center
+            self._current = self._to_native(DimPoint(0, 0))
+            self._cur_heading = (3 * math.pi) / 2  # in Canvas Y is negative.
+
+            if self._size.x >= 800:
+                self._canvas.layout.width = "90%"
+                self._canvas.layout.max_width = f"{self._size.x}px"
+                self._canvas.layout.min_width = "800px"
+            else:
+                self._canvas.layout.width = "auto"
+                self._canvas.layout.max_width = "auto"
+                self._canvas.layout.min_width = "auto"
+
+    @property
+    def pos(self) -> tuple[int, int]:
+        """Get the current location of the Turtle."""
+        return self._to_turtle(self._current)
+
+    @pos.setter
+    def pos(self, *place: tuple[int, int] | Sequence[int] | DimPoint):
+        """Goto a point in the coordinate space."""
+        if len(place) == 0:
+            raise ValueError("Goto where?")
+        elif isinstance(place[0], DimPoint):
+            p = place[0]
+        elif isinstance(place[0], tuple):
+            p = DimPoint._make(*place)
+        else:
+            p = DimPoint._make(place)
+
+        self._move(self._to_native(p))
+
+    @property
+    def heading(self) -> float:
+        """Get the current heading."""
+        return -math.degrees(self._cur_heading + math.pi / 2) % 360
+
+    @heading.setter
+    def heading(self, heading: float):
+        """Set the pen to face heading in degrees."""
+        with self._do_draw():
+            self._cur_heading = math.radians(-heading - 90) % (math.pi * 2)
+
+    def _hue_to_html(self, hue: int):
+        """Convert a color number from 0 to 365 to HTML"""
+        rgb = colorsys.hsv_to_rgb((hue % 365) / 364, 1, 1)
+        return f"#{round(rgb[0] * 255):02x}{round(rgb[1] * 255):02x}{round(rgb[2] * 255):02x}"
+
+    @property
+    def color(self) -> str:
+        """Set the pen color using HTML color notation."""
+        return self._canvas[1].stroke_style
+
+    @color.setter
+    def color(self, color: str | int):
+        """Set the pen color using HTML color notation."""
+        if color.__class__ in [int, float]:
+            color = self._hue_to_html(color)
+        self._canvas[1].stroke_style = color
+
+    @property
+    def fill(self) -> str:
+        """Set the pen color using HTML color notation."""
+        return self._fill
+
+    @fill.setter
+    def fill(self, color: str):
+        """Set the pen color using HTML color notation."""
+        if color.__class__ in [int, float]:
+            color = self._hue_to_html(color)
+        self._fill = color
+        if color is not None:
+            self._canvas[1].fill_style = color
+
+    @property
+    def width(self) -> int:
+        """The line thickness."""
+        return self._canvas[1].line_width
+
+    @width.setter
+    def width(self, width: int):
+        """Set the line thickness."""
+        self._canvas[1].line_width = width
+
+    @property
+    def image(self) -> PIL.Image:
+        """Return an image of the Canvas."""
+        return PIL.Image.fromarray(self._image)

jupyter_turtle-1.0.1/src/jupyter_turtle.egg-info/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: jupyter-turtle
+Version: 1.0.1
+Summary: Simplified Turtle graphics for the Jupyter Notebook
+Author-email: Mike Matera <michael.matera@cabrillo.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mike-matera/jupyter-turtle
+Project-URL: Issues, https://github.com/mike-matera/jupyter-turtle/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipycanvas
+Requires-Dist: jupyterlab
+Dynamic: license-file
+
+# Jupyter Turtle 
+
+This is an implementation of simplified Turtle graphics to support my [Python
+for Everyone](https://github.com/mike-matera/python-for-everyone) course.
+[Logo](https://en.wikipedia.org/wiki/Logo_\(programming_language\)) was my first
+programming language. The purpose of this implementation is to give beginners a
+visual experience to help them understand algorithmic reasoning. The module
+contains a `Turtle` class implementation with a full API and a simplified API
+that I use in class. 
+

jupyter_turtle-1.0.1/src/jupyter_turtle.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/jupyter_turtle/__init__.py
+src/jupyter_turtle/turtle.png
+src/jupyter_turtle/turtle.py
+src/jupyter_turtle.egg-info/PKG-INFO
+src/jupyter_turtle.egg-info/SOURCES.txt
+src/jupyter_turtle.egg-info/dependency_links.txt
+src/jupyter_turtle.egg-info/requires.txt
+src/jupyter_turtle.egg-info/top_level.txt

jupyter_turtle-1.0.1/src/jupyter_turtle.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jupyter_turtle-1.0.1/src/jupyter_turtle.egg-info/requires.txt

@@ -0,0 +1,2 @@
+ipycanvas
+jupyterlab

jupyter_turtle-1.0.1/src/jupyter_turtle.egg-info/top_level.txt

@@ -0,0 +1 @@
+jupyter_turtle