TurtleExtension 2.0.0__tar.gz → 2.2.0__tar.gz

{turtleextension-2.0.0 → turtleextension-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TurtleExtension
-Version: 2.0.0
+Version: 2.2.0
 Summary: A Python utility library providing turtle extensions on top of Python's original turtle feature.
 Author-email: "Miah M. Sabiq" <miah.sabiq@gibs.at>
 Requires-Python: >=3.14

{turtleextension-2.0.0 → turtleextension-2.2.0}/TurtleExtension.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TurtleExtension
-Version: 2.0.0
+Version: 2.2.0
 Summary: A Python utility library providing turtle extensions on top of Python's original turtle feature.
 Author-email: "Miah M. Sabiq" <miah.sabiq@gibs.at>
 Requires-Python: >=3.14

{turtleextension-2.0.0 → turtleextension-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "TurtleExtension"
-version = "2.0.0"
+version = "2.2.0"
 description = "A Python utility library providing turtle extensions on top of Python's original turtle feature."
 readme = "README.md"
 requires-python = ">= 3.14"

turtleextension-2.2.0/turtle_extension/__init__.py

@@ -0,0 +1,63 @@
+"""
+This package is part of the GeometricalDomination project ecosystem.
+
+It contains a chainable turtle class called ChainTurtle and a collection of extra provided features along with it:
+
+1. tls_color -> this function make a list of colored turtles and returns it
+2. get_screen -> turtle screen initializer function
+3. SU -> screen update function
+
+And a lot more.
+
+Author: Miah M. Sabiq
+"""
+
+#* Imports foundational functions across numerous files
+from .foundations import (
+   CUSTOM_SHAPES,       #* [[custom_turtle_shapes.py]]
+   get_UserShape_dict,  #* [[custom_turtle_shapes.py#get_UserShape_dict]]
+
+   get_screen,          #* [[global_functions.py#get_screen]]
+   mainloop,            #* [[global_functions.py#mainloop]]
+   reset_tls,           #* [[global_functions.py#reset_tls]]
+   SU,                  #* [[global_functions.py#SU]]
+   tls_color,           #* [[global_functions.py#tls_color]]
+
+   t_now,               #* [[global_variables.py#t_now]]
+   t_shape,             #* [[global_variables.py#t_shape]]
+   UV,                  #* [[global_variables.py]]
+
+   TurtleFct,           #* [[TurtleFct]]
+   UserShape,           #* [[UserShape]]
+)
+
+#* Imports core mechanisms of this package:
+#*  [[ChainTurtle]] and [[turtle.py]] from [[turtle_skeleton.py]]
+from .turtle_heart import (
+   ChainTurtle,         #* [[ChainTurtle]]
+   tl,                  #* [[turtle.py]]
+)
+
+
+#* Specifies all available functions and dictionaries through wild card import
+__all__ = [
+    "UV",
+    "t_now",
+    "t_shape",
+
+    "get_screen",
+    "SU",
+    "mainloop",
+    "tls_color",
+    "reset_tls",
+
+    "UserShape",
+    "get_UserShape_dict",
+    "CUSTOM_SHAPES",
+
+    "TurtleFct",
+
+
+   "ChainTurtle",
+   "tl",
+]

{turtleextension-2.0.0 → turtleextension-2.2.0}/turtle_extension/foundations/__init__.py

@@ -1,8 +1,11 @@
+#* Imports function, class and dictionary from [[custom_turtle_shapes.py]]
 from .custom_turtle_shapes import (
     CUSTOM_SHAPES,
     UserShape,
     get_UserShape_dict,
 )
+
+#* Imports fundamental turtle functions from [[global_functions.py]]
 from .global_functions import (
     SU,
     get_screen,
@@ -10,15 +13,22 @@ from .global_functions import (
     reset_tls,
     tls_color,
 )
+
+#* Imports universal dictionary and related functions from [[global_variables.py]]
 from .global_variables import (
     UV,
     t_now,
     t_shape,
 )
+
+#* Imports class from [[turtle_functions.py]]
 from .turtle_functions import (
     TurtleFct,
 )
 
+
+#* Specifies functions, classes, and dictionaries available in foundations package
+#* through wild card import
 __all__ = [
     "UV",
     "t_now",

{turtleextension-2.0.0 → turtleextension-2.2.0}/turtle_extension/foundations/custom_turtle_shapes.py

@@ -4,8 +4,8 @@ import uf
 
 from ..turtle_heart import tl
 
-helper = uf.helper
 
+#* Class containing all premade turtle shape functions
 @uf.cls_deco_superposition(staticmethod)
 class UserShape:
     def custom_circle():
@@ -16,7 +16,7 @@ class UserShape:
         return tl.get_poly()
 
     def custom_square():
-        length: Real = helper.length_float()
+        length: Real = uf.helper.length_float()
         tl.begin_poly()
 
         for _ in range(4):
@@ -27,7 +27,7 @@ class UserShape:
         return tl.get_poly()
 
     def custom_triangle():
-        length: Real = helper.length_float()
+        length: Real = uf.helper.length_float()
         tl.begin_poly()
 
         for _ in range(3):
@@ -38,8 +38,8 @@ class UserShape:
         return tl.get_poly()
 
     def custom_poly():
-        length: Real = helper.length_float()
-        sides: int = helper.sides_num()
+        length: Real = uf.helper.length_float()
+        sides: int = uf.helper.sides_num()
 
         radius = length / (2 * uf.sine(180 / sides))
         angle_to_right = (180 - (180 * (sides - 2)) / sides) / 2
@@ -53,7 +53,7 @@ class UserShape:
         return tl.get_poly()
 
     def custom_SOD():
-        side: Real = helper.length_float()
+        side: Real = uf.helper.length_float()
         tl.begin_poly()
 
         for _ in range(6):
@@ -65,15 +65,20 @@ class UserShape:
         tl.end_poly()
         return tl.get_poly()
 
+    #* Creates and returns a dictionary mapping [[UserShape]]
+    #* function names with their corresponding function
     @classmethod
-    def _list_shapes(cls):
+    def list_shapes(cls):
         return uf.classes_to_dict(cls)
 
+#* Creates a customized dictionary mapping [[UserShape]] functions by having the
+#* prefix "custom_" switched with cm
 def get_UserShape_dict():
     return {
         f"cm {name.removeprefix('custom_')}": func
-        for name, func in UserShape._list_shapes().items()
+        for name, func in UserShape.list_shapes().items()
         if not name.startswith("_")
     }
 
+#* [[UserShape]] dictionary storage
 CUSTOM_SHAPES = get_UserShape_dict()

{turtleextension-2.0.0 → turtleextension-2.2.0}/turtle_extension/foundations/custom_turtle_shapes.pyi

@@ -5,8 +5,11 @@ This module contains the class Usershape which contains functions to make a cust
 from collections.abc import Callable, Sequence
 from numbers import Real
 
+
+#* The type returned by each turtle shape changer function from [[UserShape]]
 type ReturnShapeType = Sequence[tuple[Real,Real]] | None
 
+#* The type of the dictionary derived from [[UserShape]]
 type UserShapeDictType = dict[
     str,
     Callable[[], ReturnShapeType]
@@ -21,6 +24,7 @@ class UserShape:
     def custom_circle() -> ReturnShapeType:
         """
         Creates a custom circle turtle shape.
+
         :return: the custom shape
         """
 
@@ -28,6 +32,7 @@ class UserShape:
     def custom_square() -> ReturnShapeType:
         """
         Creates a custom square turtle shape.
+
         :return: the custom shape
         """
 
@@ -35,6 +40,7 @@ class UserShape:
     def custom_triangle() -> ReturnShapeType:
         """
         Creates a custom equilateral triangle turtle shape.
+
         :return: the custom shape
         """
 
@@ -42,6 +48,7 @@ class UserShape:
     def custom_poly() -> ReturnShapeType:
         """
         Creates a custom regular polygon turtle shape.
+
         :return: the custom shape
         """
 
@@ -49,19 +56,22 @@ class UserShape:
     def custom_SOD() -> ReturnShapeType:
         """
         Creates a custom star of David turtle shape.
+
         :return: the custom shape
         """
 
     @classmethod
-    def _list_shapes(cls) -> UserShapeDictType:
+    def list_shapes(cls) -> UserShapeDictType:
         """
-        Creates a dictionary with the functions in UserShape and returns it
+        Creates a dictionary with the functions in UserShape and returns it.
+
         :return: dictionary containing function names -> function
         """
 
 def get_UserShape_dict() -> UserShapeDictType:
     """
-    Takes all custom turtle functions in UserShape and returns a dictionary with them
+    Takes all custom turtle functions in UserShape and returns a dictionary with them.
+
     :return: dictionary mapping function names to functions
     """
 

{turtleextension-2.0.0 → turtleextension-2.2.0}/turtle_extension/foundations/global_functions.py

@@ -9,6 +9,8 @@ from .global_variables import UV, t_shape
 
 _screen = None
 
+#* Retrieves the turtle screen [[turtle.py#Screen]] if one has been made,
+#* else, a new screen is initialized
 def get_screen():
     global _screen
 
@@ -19,13 +21,18 @@ def get_screen():
 
     return _screen
 
+#* Updates the current turtle screen if one exists,
+#* else a new one is created and updated
 def SU():
     get_screen().update()
 
+#* Keeps the turtle window open if one exists,
+#* else a new one is created and kept open
 def mainloop():
     get_screen().mainloop()
 
-
+#* Creates a chosen number of turtles with different modes,
+#* also known as the turtle factory by the developer
 def tls_color(**options):
 
     tl_num_name: Final = "tl_num"
@@ -78,7 +85,8 @@ def tls_color(**options):
         return tls
     return None
 
-
+#* Resets the provided turtle list,
+#* deletes all turtle drawings and the turtles themselves
 def reset_tls(tls_list):
 
     tls_list_name: Final = "tls_list"

{turtleextension-2.0.0 → turtleextension-2.2.0}/turtle_extension/foundations/global_functions.pyi

@@ -5,34 +5,40 @@ colors and get a list with them.
 
 from ..turtle_heart import ChainTurtle, tl
 
+
 def get_screen() -> tl.Screen:
     """
     Initiates the turtle screen when the function is called.
+
     :return: turtle screen object
     """
 
 def SU() -> None:
     """
     This function updates the turtle screen.
+
     :return: None
     """
 
 def mainloop() -> None:
     """
     This function keeps the turtle screen open.
+
     :return: None
     """
 
 type TurtleListType = list[ChainTurtle]
 
 def tls_color(**options) -> int | tuple[TurtleListType, int] | TurtleListType | None:
-    """This function creates a turtle list with their colors or adds newly creates turtles to the UV["tls"] list
+    """
+    This function creates a turtle list with their colors or adds newly creates turtles to the UV["tls"] list
     to be used for the user_drawing_ft()
 
     USERS NOTICE: it is HIGHLY recommended to NOT enter a turtles count of MORE than a few hundred (max. 200) unless required!!!
 
     :param options: tl_num -> number of turtles to create, entry -> input string, index -> number of turtles to be created for user_drawing_ft()
     & it returns the index of the last turtle
+
     :return: tls_num: turtle list with colored turtles, entry: list with colored turtles + number of turtles ,otherwise: index of last turtle
     """
 
@@ -41,6 +47,7 @@ def reset_tls(tls_list: TurtleListType) -> list:
     This function deletes the drawings of given turtle list + turtles
 
     >>> tls = [ChainTurtle(), ChainTurtle()]
+    
     >>> reset_tls(tls)
     []
 

turtleextension-2.2.0/turtle_extension/foundations/global_variables.py

@@ -0,0 +1,15 @@
+#* UV = UNIVERSAL VARIABLES
+UV = {
+    "delay": None,              #* Delay for [[turtle_runner.py#user_drawing_ft]]
+      "t": 0,                   #* user_drawing_ft's current turtle
+      "tls": [],                #* user_drawing_ft's turtle list
+      "tls_shape": "arrow",     #* turtle's current shape
+}
+
+#* Retrieves the current turtle from UV
+def t_now():
+    return UV["tls"][UV["t"]]
+
+#* Retrieves the current turtle shape
+def t_shape():
+    return UV["tls_shape"]

{turtleextension-2.0.0 → turtleextension-2.2.0}/turtle_extension/foundations/global_variables.pyi

@@ -12,6 +12,8 @@ from typing import Any
 
 from ..turtle_heart import ChainTurtle
 
+
+#* The type for the [[global_variables.py]] UV dictionary
 UV: dict[str, Any]
 
 def t_now() -> ChainTurtle:

{turtleextension-2.0.0 → turtleextension-2.2.0}/turtle_extension/foundations/turtle_functions.py

@@ -5,7 +5,9 @@ from .custom_turtle_shapes import CUSTOM_SHAPES
 from .global_variables import UV
 
 
+#* Class containing turtle shape changer functions
 class TurtleFct:
+    #* Main turtle shape changer function, potentially triggers [[TurtleFct#user_tls_shape_ft]]
     @classmethod
     def change_shape(cls, tls_num = None):
         if tls_num is not None:
@@ -32,6 +34,7 @@ class TurtleFct:
             else:
                 return cls.user_tls_shape_ft()
 
+    #* Lets the user choose custom shapes from [[UserShape]]
     @staticmethod
     def user_tls_shape_ft(tls_num = None):
         if tls_num is not None:

{turtleextension-2.0.0 → turtleextension-2.2.0}/turtle_extension/foundations/turtle_functions.pyi

@@ -4,6 +4,7 @@ This module contains the class TurtleFct which lets the user change the turtle s
 
 from ..turtle_heart import ChainTurtle
 
+
 class TurtleFct:
     """
     This class contains a function that lets users change the shape of the turtles that will be created in the future with tls_color.
@@ -12,7 +13,9 @@ class TurtleFct:
     def change_shape(cls, tls_num: ChainTurtle|None = None) -> ChainTurtle | str:
         """
         This function lets the user choose different turtles shapes, including a custom option.
+
         :param tls_num: ChainTurtle() or None
+
         :return: ChainTurtle() if tls_num is a ChainTurtle(), otherwise None
         """
 
@@ -20,6 +23,8 @@ class TurtleFct:
     def user_tls_shape_ft(tls_num: ChainTurtle | None = None) -> ChainTurtle | str:
         """
         This function lets the user create custom turtle shapes.
+
         :param tls_num: ChainTurtle() or None
+        
         :return: ChainTurtle() if tls_num is a ChainTurtle(), otherwise None
-        """
+        """

turtleextension-2.2.0/turtle_extension/turtle_heart/__init__.py

@@ -0,0 +1,8 @@
+#* Imports the [[ChainTurtle]] and [[turtle.py]] from [[turtle_skeleton.py]]
+from .turtle_skeleton import ChainTurtle, tl
+
+#* Specifies the classes found in [[turtle_skeleton.py]]
+__all__ = [
+    "ChainTurtle",
+    "tl",
+]

{turtleextension-2.0.0 → turtleextension-2.2.0}/turtle_extension/turtle_heart/turtle_skeleton.py

@@ -3,6 +3,7 @@ import turtle as tl
 import uf
 
 
+#* Class for chaining the conventional turtle functions [[turtle.py]]
 class ChainTurtle(tl.Turtle):
     def fd(self, distance):
         super().fd(distance)
@@ -96,6 +97,7 @@ class ChainTurtle(tl.Turtle):
         super().ht()
         return self
 
+#* Creates and returns a dictionary with all [[ChainTurtle]] functions
     @classmethod
     def list_methods(cls):
         return uf.classes_to_dict(cls)

{turtleextension-2.0.0 → turtleextension-2.2.0}/turtle_extension/turtle_heart/turtle_skeleton.pyi

@@ -5,97 +5,127 @@ This module contains the class ChainTurtle() which is the foundational object ar
 from collections.abc import Callable
 from numbers import Real
 
+
+tl = tl
+
 class ChainTurtle:
-    """This class adds chaining functionality to turtle.Turtle"""
+    """
+    This class adds chaining functionality to turtle.Turtle
+    
+    """
     def fd(self, distance: Real) -> ChainTurtle:
         """
         Makes the turtle go forward with trace.
+
         :param distance: distance in pixels
+
         :return: ChainTurtle()
         """
 
     def fd_inv(self, distance: Real) -> ChainTurtle:
         """
         Makes the turtle go forward with no trace.
+
         :param distance: distance in pixels
+
         :return: ChainTurtle()
         """
 
     def bk(self, distance: Real) -> ChainTurtle:
         """
         Makes the turtle go backwards with trace.
+
         :param distance: distance in pixels
+
         :return: ChainTurtle()
         """
 
     def bk_inv(self, distance: Real) -> ChainTurtle:
         """
         Makes the turtle go backward with no trace.
+
         :param distance: distance in pixels
+
         :return: ChainTurtle()
         """
 
     def rt(self, angle: Real) -> ChainTurtle:
         """
         Makes the turtle turn right.
+
         :param angle: angle in degrees
+
         :return: ChainTurtle()
         """
 
     def lt(self, angle: Real) -> ChainTurtle:
         """
         Makes the turtle turn left.
+
         :param angle: angle in degrees
+
         :return: ChainTurtle()
         """
 
     def setpos(self, x_val: Real, y_val: Real) -> ChainTurtle:
         """
         Makes the turtle go to a specific position with a trace.
+
         :param x_val: x position in pixels
+
         :param y_val: y position in pixels
+
         :return: ChainTurtle()
         """
 
     def pu(self) -> ChainTurtle:
         """
         Puts the pen down to leave a trace.
+
         :return: ChainTurtle()
         """
 
     def pd(self) -> ChainTurtle:
         """
         Puts the pen up to not leave a trace.
+
         :return: ChainTurtle()
         """
 
     def seth(self, direction: Real) -> ChainTurtle:
         """
         Sets the direction of the turtle starting East, going counterclockwise.
+
         :param direction: direction in degrees
+
+        :return: ChainTurtle()
         """
 
     def home(self) -> ChainTurtle:
         """
         Sets the position of the turtle to home (0, 0) with trace, heading = 0 .
+
         :return: ChainTurtle()
         """
 
     def home_inv(self) -> ChainTurtle:
         """
         Sets the position of the turtle to home (0, 0) without trace, heading = 0 .
+
         :return: ChainTurtle()
         """
 
     def begin_fill(self) -> ChainTurtle:
         """
         Makes the turtle begin fill for a closed shape.
+
         :return: ChainTurtle()
         """
 
     def end_fill(self) -> ChainTurtle:
         """
         Ends the turtle fill for a closed shape, therefore fills the shapes.
+
         :return: ChainTurtle()
         """
 
@@ -105,9 +135,13 @@ class ChainTurtle:
                steps: int | None = None) -> ChainTurtle:
         """
         Makes the turtle draw a circle
+
         :param radius: radius in pixels
+
         :param extent: extent in degrees
+
         :param steps: number of sides
+
         :return: ChainTurtle()
         """
 
@@ -117,51 +151,72 @@ class ChainTurtle:
                     sides: int | None = None) -> ChainTurtle:
         """
         Makes the turtle draw a circle and fills it
+
         :param radius: radius in degrees
+
         :param angle: angle in degrees
+
         :param sides: number of sides
+
+        :return: ChainTurtle()
         """
 
     def dot(self, radius: Real) -> ChainTurtle:
         """
         Makes the turtle draw a colored dot
+
         :param radius: radius in pixels
+
+        :return: ChainTurtle()
         """
 
     def color(self, turtle_color: str) -> ChainTurtle:
         """
         Lets the user change the color of the turtle trace and turtle color itself
+
         :param turtle_color: valid turtle color
+
+        :return: ChainTurtle()
         """
 
     def teleport(self, x: Real, y: Real, *, fill_gap: bool = False) -> ChainTurtle:
         """
         Makes the turtle to go a specific coordinate with no trace
+
         :param x: x position in pixels
+
         :param y: y position in pixels
+
+        :return: ChainTurtle()
         """
 
     def shape(self, shape_name: str) -> ChainTurtle:
         """
         Changes the shape of the turtle shape
+
         :param shape_name: name of the shape
+
+        :return: ChainTurtle()
         """
 
     def undo(self) -> ChainTurtle:
         """
         Undoes the last turtle command.
+
         :return: ChainTurtle()
         """
 
     def clear(self) -> ChainTurtle:
         """
         Deletes the turtles drawings.
+
         :return: ChainTurtle()
         """
 
     def ht(self) -> ChainTurtle:
         """
         Hides the turtle.
+
         :return: ChainTurtle()
         """
 
@@ -169,5 +224,6 @@ class ChainTurtle:
     def list_methods(cls) -> dict[str, Callable]:
         """
         Creates a dictionary with all ChainTurtle methods and returns it
+        
         :return: dictionary
-        """
+        """

turtleextension-2.0.0/turtle_extension/__init__.py

@@ -1,54 +0,0 @@
-"""
-This package is part of the GeometricalDomination project ecosystem.
-
-It contains a chainable turtle class called ChainTurtle and a collection of extra provided features along with it:
-
-1. tls_color -> this function make a list of colored turtles and returns it
-2. get_screen -> turtle screen initializer function
-3. SU -> screen update function
-
-And a lot more.
-
-Author: Miah M. Sabiq
-"""
-
-from .foundations import (
-   CUSTOM_SHAPES,
-   SU,
-   UV,
-   TurtleFct,
-   UserShape,
-   get_screen,
-   get_UserShape_dict,
-   mainloop,
-   reset_tls,
-   t_now,
-   t_shape,
-   tls_color,
-)
-from .turtle_heart import (
-   ChainTurtle,
-   tl,
-)
-
-__all__ = [
-    "UV",
-    "t_now",
-    "t_shape",
-
-    "get_screen",
-    "SU",
-    "mainloop",
-    "tls_color",
-    "reset_tls",
-
-    "UserShape",
-    "get_UserShape_dict",
-    "CUSTOM_SHAPES",
-
-    "TurtleFct",
-
-
-   "ChainTurtle",
-   "tl",
-]

turtleextension-2.0.0/turtle_extension/foundations/global_variables.py

@@ -1,14 +0,0 @@
-# UV = UNIVERSAL VARIABLES
-UV = {
-    "delay": None,            # Delay for user_drawing_ft()
-      "t": 0,                   # user_drawing_ft's current turtle
-      "tls": [],                # user_drawing_ft's turtle list
-      "tls_shape": "arrow",     # user_drawing_ft's turtle's current shape
-      "shape_library": [],      # user_drawing_ft's turtle shapes list
-}
-def t_now():
-    return UV["tls"][UV["t"]]
-
-def t_shape():
-    return UV["tls_shape"]
-

turtleextension-2.0.0/turtle_extension/turtle_heart/__init__.py

@@ -1,6 +0,0 @@
-from .turtle_skeleton import ChainTurtle, tl
-
-__all__ = [
-    "ChainTurtle",
-    "tl",
-]