Metadata-Version: 2.5
Name: ColabTurtle
Version: 2.2.0
Summary: An HTML based Turtle implementation, in order to work in Google Colab
Project-URL: Homepage, https://github.com/tolgaatam/ColabTurtle
Author-email: Tolga Atam <atam@sabanciuniv.edu>
License-Expression: MIT
License-File: LICENSE
Classifier: Framework :: IPython
Classifier: Framework :: Jupyter
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: ipython>=6.0
Description-Content-Type: text/markdown

Turtle for Google Colab notebooks
===================

Module for drawing classic Turtle figures on Google Colab notebooks (and other IPython supported environments like Jupyter Lab)
It uses HTML capabilities of IPython library to draw svg shapes inline.
Looks of the figures are inspired from [Blockly Games / Turtle](https://blockly-games.appspot.com/turtle).

Installation for Google Colab:
----
Create an empty code cell and type:

    !pip3 install ColabTurtle

Run the code cell. Google Colab will install the library.


Usage
----
In any code cell, import like following:

    from ColabTurtle.Turtle import *

As Colab stores the declared variables in the runtime, call this before using: 

    initializeTurtle()

Example
----

The following code illustrates some usages of the library. For all functions available in this library, please check the API documentation below.

```
from ColabTurtle.Turtle import *
initializeTurtle(initial_speed=4, initial_window_size=(800,500))

color('mediumblue')
penup()
goto(100, 250)
pendown()
forward(100)
left(90)
forward(40)
right(180)
forward(80)
penup()
right(90)
forward(50)
left(90)
forward(50)
left(90)
backward(10)
pendown()
speed(10)
for i in range(18):
    forward(17)
    right(20)
penup()
shape('circle')
color(230, 90, 120)
speed(7)
right(90)
forward(160)
left(90)
forward(60)
right(180)
pendown()
forward(100)
left(90)
forward(80)
penup()
shape('turtle')
forward(50)
left(90)
forward(40)
pendown()
for i in range(5):
    forward(17)
    right(20)
left(200)
for i in range(13):
    forward(17)
    left(20)
left(90)
forward(50)
penup()
backward(100)
left(90)
forward(40)
pendown()
left(155)
forward(105)
right(130)
forward(105)
backward(45)
right(115)
forward(50)
bgcolor("#efefef")
penup()
backward(70)
left(90)
forward(100)
right(90)
pencolor('black')
pensize(7)
pendown()
forward(650)
left(180)
speed(12)
for i in range(90):
    forward(7)
    right(0.2)
speed(2)
left(18+180)
penup()
forward(300)
setheading(270)
write("ColabTurtle", align="center", font=(25, "Arial", "italic"))
color('rgb(70 110 70)')
backward(40)
```

This code ends up with the following drawing:

![Drawing that reads "Tolga"](https://raw.githubusercontent.com/tolgaatam/ColabTurtle/master/sample_image.jpg "Example Code's Final Look")


API
----
This module's API is mostly identical to the traditional turtle API. There are some differences, most notably: the angles are handled differently. 0 angle is east and the angles increase clockwise. Some functions from the traditional turtle library is missing here; however almost all the main functionality is implemented. The functions that this library implements are explained below:


`forward(units) | fd(units)` -> Moves the turtle in the direction it is facing, by `units` pixels

`backward(units) | bk(units) | back(units)` -> Moves the turtle in the opposite of the direction it is facing, by `units` pixels

<br/>

`right(degrees) | rt(degrees)` -> Turns the turtle to right by the given `degrees` many degrees.

`face(degrees) | heading(degrees) | setheading(degrees)` -> Turns the turtle to the direction given as `degrees`

`left(degrees) | lt(degrees)` -> Turns the turtle to left by the given `degrees` many degrees.

<br/>

`penup() | pu() | up()` -> Lifts the pen, turtles movement will not draw anything after this function is called.

`pendown() | pd()` -> Puts the pen down, causing the turtle movements to start drawing again.

<br/>

`speed(s)` -> Sets the speed of turtle's movements. `s` can be a value in interval [1,13] where 1 is the slowest and 13 is the fastest. If `s` is omitted, the function returns the current speed.

<br/>

`setx(x)` -> Moves the turtle to the given `x` position, the y coordinate of the turtle stays the same.

`sety(y)` -> Moves the turtle to the given `y` position, the x coordinate of the turtle stays the same.

`home()` -> Takes the turtle to the beginning position and angle. The turtle will continue drawing during this operation if the pen is down.

<br/>

`getx() | xcor()` -> Returns the current x coordinate of the turtle.

`gety() | ycor()` -> Returns the current y coordinate of the turtle.

`position() | pos()` -> Returns the current x,y coordinates of the turtle as a tuple.

`heading() | getheading()` -> Returns the direction that the turtle is looking at right now, in degrees.

<br/>

<br/>

```
goto(x,y) | setpos(x,y) | setposition(x,y)` 
goto((x,y)) | setpos((x,y)) | setposition((x,y))` 
```
Moves the turtle to the point defined by x,y. The coordinates can be given separately, or in a single tuple.

<br/>

<br/>

`showturtle() | st()` -> Makes the turtle visible.

`hideturtle() | ht()` -> Makes the turtle invisible.

`isvisible()` -> Returns whether turtle is currently visible as boolean.

<br/>

<br/>

```
bgcolor()
bgcolor(r,g,b)
bgcolor((r,g,b))
bgcolor(colorstring)
```
If no parameter given, returns the current background color as string. Else, changes the background color of the drawing area. The color can be given as three separate color arguments as in the RGB color encoding: red,green,blue. These three numbers can be given in a single tuple as well. The color can be given as a single color string, too! The following formats are accepted for this color string:
- HTML standard color names: 140 color names defined as standard ( https://www.w3schools.com/colors/colors_names.asp ) . Examples: `"red"`, `"black"`, `"magenta"`, `"cyan"` etc.
- Hex string with 3 or 6 digits, like `"#fff"`, `"FFF"`, `"#dfdfdf"`, `"#DFDFDF"`
- RGB string, like `"rgb(10 20 30)"`, `"rgb(10, 20, 30)"`

<br/>

<br/>

```
color() | pencolor()
color(r,g,b) | pencolor(r,g,b)
color((r,g,b)) | pencolor((r,g,b))
color(colorstring) | pencolor(colorstring)
```
The same as `bgcolor` but works with the turtle's pen's color.

<br/>

<br/>

`width(w) | pensize(w)` -> Changes the width of the pen. If the parameter is omitted, returns the current pen width.

<br/>

<br/>

```
distance(x,y)
distance((x,y))
```
Returns the turtle's distance to a given point x,y. The coordinates can be given separately or as a single tuple.

<br/>

<br/>

`clear()` -> Clear any drawing on the screen.

`write(obj, align=, font=)` -> Writes the string equivalent of any value to the screen. `align` and `font` **named** parameters can be given as arguments optionally. `align` must be one of `"left","center","right"`. It specifies where to put the text with respect to the turtle. `font` must be a tuple of three values like `(20, "Arial", "bold")`. The first value is the size, second value is the font family (only the ones that your browser natively supports must be used), the third value is font style that must be one of `"normal","bold","italic","underline"`.

`shape(sh)` -> Takes a shape name `sh` and transforms the main character's look. This library only has `'circle'` and `'turtle'` shapes available. If no argument is supplied, this function returns the name of the current shape.

`window_width()` -> Return the width of the turtle window.

`window_height()` -> Return the height of the turtle window.

Release History
----
- **v2.2.0** (3rd November 2026): Docstrings and type hints for all functions (the package ships a `py.typed` marker), so Python 3.10+ is now required. Fixes `distance()` and the invalid escape sequence warning on Python 3.12+, and validates `rgb(...)` color strings more strictly. Packaging moved to `pyproject.toml`.
- **v2.1.0** (19th March 2021): Better compatibility with the original turtle API: aliases like `fd`, `rt` and `pu`, new functions such as `face()`, `home()`, `getx()`/`gety()`, `distance()`, `write()`, `shape()` and `window_width()`/`window_height()`, all 140 HTML color names plus hex and rgb colors, speed range extended to [1,13], and moves by floating point units.
- **v2.0.0** (7th November 2018): Switched from a class-based API to module-level functions for simpler usage, like the procedural interface of Python's built-in turtle module. `initializeTurtle()` replaces creating a `ColabTurtle` object.
- **v1.0.0** (7th November 2018): Initial release by Tolga Atam.

<br/>

<br/>

<br/>

HAVE FUN DRAWING!
