gh-126349 Add context managers to turtle for fill, poly and no_animation

Doc/library/turtle.rst

@@ -213,6 +213,32 @@ useful when working with learners for whom typing is not a skill.
     use turtle graphics with a learner.
 
 
+Automatically begin and end filling
+-----------------------------------
+
+If you have Python 3.14 or later, you don't need to call :func:`begin_fill` and
+:func:`end_fill` for filling. Instead, you can use the :func:`fill`
+:term:`context manager` to automatically begin and end fill. Here is an
+example::
+
+   with fill():
+       for i in range(4):
+           forward(100)
+           right(90)
+
+   forward(200)
+
+The code above is equivalent to::
+
+   begin_fill()
+   for i in range(4):
+       forward(100)
+       right(90)
+   end_fill()
+
+   forward(200)
+
+
 Use the ``turtle`` module namespace
 -----------------------------------
 
@@ -351,6 +377,7 @@ Pen control
 
    Filling
       | :func:`filling`
+      | :func:`fill`
       | :func:`begin_fill`
       | :func:`end_fill`
 
@@ -381,6 +408,7 @@ Using events
    | :func:`ondrag`
 
 Special Turtle methods
+   | :func:`poly`
    | :func:`begin_poly`
    | :func:`end_poly`
    | :func:`get_poly`
@@ -403,6 +431,7 @@ Window control
    | :func:`setworldcoordinates`
 
 Animation control
+   | :func:`no_animation`
    | :func:`delay`
    | :func:`tracer`
    | :func:`update`
@@ -1275,6 +1304,29 @@ Filling
       ... else:
       ...    turtle.pensize(3)
 
+.. function:: fill()
+
+   Fill the shape drawn in the ``with turtle.fill():`` block.
+
+   .. doctest::
+      :skipif: _tkinter is None
+
+      >>> turtle.color("black", "red")
+      >>> with turtle.fill():
+      ...     turtle.circle(80)
+
+   Using ``fill``  is equivalent to adding the :func:`begin_fill` before the
+   fill-block and :func:`end_fill` after the fill-block:
+
+   .. doctest::
+      :skipif: _tkinter is None
+
+      >>> turtle.color("black", "red")
+      >>> turtle.begin_fill()
+      >>> turtle.circle(80)
+      >>> turtle.end_fill()
+
+   .. versionadded:: next
 
 
 .. function:: begin_fill()
@@ -1648,6 +1700,23 @@ Using events
 Special Turtle methods
 ----------------------
 
+
+.. function:: poly()
+
+   Record the vertices of a polygon drawn in the ``with turtle.poly():`` block.
+   The first and last vertices will be connected.
+
+   .. doctest::
+      :skipif: _tkinter is None
+
+      >>> with turtle.poly():
+      ...     turtle.forward(100)
+      ...     turtle.right(60)
+      ...     turtle.forward(100)
+
+   .. versionadded:: next
+
+
 .. function:: begin_poly()
 
    Start recording the vertices of a polygon.  Current turtle position is first
@@ -1925,6 +1994,25 @@ Window control
 Animation control
 -----------------
 
+.. function:: no_animation()
+
+   Temporarilly disable turtle animation. The code written inside the
+   ``no_animation`` block will not be animated, and once the code block is
+   exited, the drawing will appear.
+
+   .. doctest::
+      :skipif: _tkinter is None
+
+      >>> with screen.no_animation():
+      ...     dist = 2
+      ...     for i in range(200):
+      ...         fd(dist)
+      ...         rt(90)
+      ...         dist += 2
+
+   .. versionadded:: next
+
+
 .. function:: delay(delay=None)
 
    :param delay: positive integer

Doc/whatsnew/3.14.rst

@@ -438,6 +438,12 @@ sys
   which only exists in specialized builds of Python, may now return objects
   from other interpreters than the one it's called in.
 
+turtle
+------
+
+* Add context managers for :func:`turtle.fill`, :func:`turtle.poly`
+  and :func:`turtle.no_animation`.
+  (Contributed by Marie Roald and Yngve Mardal Moe in :gh:`126350`.)
 
 unicodedata
 -----------

Lib/test/test_turtle.py

@@ -1,9 +1,11 @@
 import os
 import pickle
 import re
+import sys
+import tempfile
 import unittest
 import unittest.mock
-import tempfile
+from contextlib import contextmanager
 from test import support
 from test.support import import_helper
 from test.support import os_helper
@@ -54,6 +56,24 @@
 """
 
 
+@contextmanager
+def patch_screen():
+    """Patch turtle._Screen for testing without a display.
+
+    We must patch the _Screen class itself instead of the _Screen
+    instance because instatiating it requires a display.
+    """
+    m = unittest.mock.MagicMock()
+    m.__class__ = turtle._Screen
+    m.mode.return_value = "standard"
+
+    patch = unittest.mock.patch('turtle._Screen.__new__', return_value=m)
+    try:
+        yield patch.__enter__()
+    finally:
+        patch.__exit__(*sys.exc_info())
+
+
 class TurtleConfigTest(unittest.TestCase):
 
     def get_cfg_file(self, cfg_str):
@@ -526,6 +546,97 @@ def test_save(self) -> None:
             with open(file_path) as f:
                 assert f.read() == "postscript"
 
+    def test_no_animation_sets_tracer_0(self):
+        s = turtle.TurtleScreen(cv=unittest.mock.MagicMock())
+
+        with s.no_animation():
+            assert s.tracer() == 0
+
+    def test_no_animation_resets_tracer_to_old_value(self):
+        s = turtle.TurtleScreen(cv=unittest.mock.MagicMock())
+
+        for tracer in [0, 1, 5]:
+            s.tracer(tracer)
+            with s.no_animation():
+                pass
+            assert s.tracer() == tracer
+
+    def test_no_animation_calls_update_at_exit(self):
+        s = turtle.TurtleScreen(cv=unittest.mock.MagicMock())
+        s.update = unittest.mock.MagicMock()
+
+        with s.no_animation():
+            s.update.assert_not_called()
+        s.update.assert_called_once()
+
+
+class TestTurtle(unittest.TestCase):
+    def setUp(self):
+        with patch_screen():
+            self.turtle = turtle.Turtle()
+
+    def test_begin_end_fill(self):
+        self.assertFalse(self.turtle.filling())
+        self.turtle.begin_fill()
+        self.assertTrue(self.turtle.filling())
+        self.turtle.end_fill()
+        self.assertFalse(self.turtle.filling())
+
+    def test_fill(self):
+        # The context manager behaves like begin_fill and end_fill.
+        self.assertFalse(self.turtle.filling())
+        with self.turtle.fill():
+            self.assertTrue(self.turtle.filling())
+        self.assertFalse(self.turtle.filling())
+
+    def test_fill_resets_after_exception(self):
+        # The context manager cleans up correctly after exceptions.
+        try:
+            with self.turtle.fill():
+                self.assertTrue(self.turtle.filling())
+                raise ValueError
+        except ValueError:
+            self.assertFalse(self.turtle.filling())
+
+    def test_fill_context_when_filling(self):
+        # The context manager works even when the turtle is already filling.
+        self.turtle.begin_fill()
+        self.assertTrue(self.turtle.filling())
+        with self.turtle.fill():
+            self.assertTrue(self.turtle.filling())
+        self.assertFalse(self.turtle.filling())
+
+    def test_begin_end_poly(self):
+        self.assertFalse(self.turtle._creatingPoly)
+        self.turtle.begin_poly()
+        self.assertTrue(self.turtle._creatingPoly)
+        self.turtle.end_poly()
+        self.assertFalse(self.turtle._creatingPoly)
+
+    def test_poly(self):
+        # The context manager behaves like begin_poly and end_poly.
+        self.assertFalse(self.turtle._creatingPoly)
+        with self.turtle.poly():
+            self.assertTrue(self.turtle._creatingPoly)
+        self.assertFalse(self.turtle._creatingPoly)
+
+    def test_poly_resets_after_exception(self):
+        # The context manager cleans up correctly after exceptions.
+        try:
+            with self.turtle.poly():
+                self.assertTrue(self.turtle._creatingPoly)
+                raise ValueError
+        except ValueError:
+            self.assertFalse(self.turtle._creatingPoly)
+
+    def test_poly_context_when_creating_poly(self):
+        # The context manager works when the turtle is already creating poly.
+        self.turtle.begin_poly()
+        self.assertTrue(self.turtle._creatingPoly)
+        with self.turtle.poly():
+            self.assertTrue(self.turtle._creatingPoly)
+        self.assertFalse(self.turtle._creatingPoly)
+
 
 class TestModuleLevel(unittest.TestCase):
     def test_all_signatures(self):