pydraw package

Submodules

pydraw.color module

class pydraw.color.Color(*args)

Bases: object

An immutable class that contains a color values, usually by name or RGB.

NONE
static all()

Get all color values that have a string-name. :return: a tuple (immutable list) of all Colors.

blue()

Get the blue property :return: b

clone()

Clone this color! :return: a clone.

green()

Get the green property :return: g

hex()

Get the hex of the color (only if defined) :return: hex_value or None

name()

Get the name of the color (only if defined) :return: color or None

static random()

Retrieve a random Color. :return: returns

red()

Get the red property. :return: r

rgb()

Get the RGB tuple :return: tuple (R, G, B)

pydraw.errors module

exception pydraw.errors.InvalidArgumentError

Bases: ValueError

exception pydraw.errors.PydrawError

Bases: NameError

exception pydraw.errors.UnsupportedError

Bases: NameError

pydraw.location module

class pydraw.location.Location(*args, **kwargs)

Bases: object

clone()

Clone the Location :return: a new Location with the same x and y as this one.

distance(location) float

Returns the distance between this location and another :param location: the Location to get the distance to :return: a float

move(*args, **kwargs)

Moves the location by a specified difference.

Can take two numbers (dx, dy), a tuple, or a Location :param dx: the dx to move by :param dy: the dy to move by :return: the location (after change)

moveto(*args, **kwargs)

Moves the location to a new location!

Can take two coordinates (x, y), a tuple, or a Location :param x: the x to move to :param y: the y to move to :return: the location (after change)

x(new_x: float | None = None) float
y(new_y: float | None = None) float

pydraw.objects module

Objects in the PyDraw library

(Author: Noah Coetsee)

class pydraw.objects.CustomPolygon(screen: Screen, vertices: list, color: Color = black, border: Color | None = None, fill: bool = True, rotation: float = 0, visible: bool = True)

Bases: CustomRenderable

An Irregular Polygon that is passed a list of vertices that can be rotated and translated!

center(*args, **kwargs) Location

Returns the location of the center :param move_to: if defined, Move the center to a new Location (Easily center objects!) :param x: if defined, move the center x-coordinate to the specified value :param y: if defined, move the center y-coordinate to the specified value :return: Location object representing centroid of CustomRenderable

clone()

Clone this CustomPolygon! :return: a CustomPolygon

height(height: float | None = None) float

Get the height of the Polygon :param height: Unsupported. :return: the height of the object

move(*args, **kwargs)

Can take either a tuple, Location, or two numbers (dx, dy) :return: None

moveto(*args, **kwargs)

Move to a new location takes a Location, tuple, or two numbers (x, y) :return: None

rotate(angle_diff: float = 0) None

Rotate the angle of the object by a difference, in degrees :param angle_diff: the angle difference to rotate by :return: None

rotation(angle: float | None = None) float

Get or set the rotation of the object. :param angle: the angle to set the rotation to in degrees, if any :return: the angle of the object’s rotation in degrees

transform(transform: tuple | None = None) tuple

Get or set the transform of the Renderable. Transforms represent the width, height, and rotation of Renderables.

You can retrieve a Transform from a Renderable with this method and set the transform the same way. :param transform: the transform to set to, if any. :return: the transform

update()

To be overriden.

vertices() list

Returns the list of vertices for the Renderable. (The vertices will be returned clockwise, starting from the top-leftmost point) :return: a list of Locations representing the vertices

width(width: float | None = None) float

Get the width of the CustomPolygon :param width: Unsupported. :return: the width of the object

class pydraw.objects.CustomRenderable(screen: ~pydraw.screen.Screen, x: float = 0, y: float = 0, width: float = 10, height: float = 10, color: ~pydraw.color.Color = black, border: ~pydraw.color.Color =, fill: bool = True, rotation: float = 0, visible: bool = True, location: ~pydraw.location.Location | None = None)

Bases: Renderable

A wrapper class to distintify classes that extend Renderable but have some custom functionality.

class pydraw.objects.Image

Bases: Renderable

Image class. Supports basic formats: PNG, GIF, JPG, PPM, images.

NOTE: This class supports the basic displaying of images, but also supports much more, such as image modification (width, height, color, etc) if you have PIL (Pillow) installed! You can install PIL/Pillow by running: pip install pillow in a terminal!

TKINTER_TYPES = ['.png', '.gif', '.ppm']
border(color: Color | None = None) Color

Add or get the border of the image :param color: the color to set the border too, set to Color.NONE to remove border :return: The Color of the border

center(*args, **kwargs) Location

Returns the location of the center :param move_to: if defined, Move the center to a new Location (Easily center objects!) :param x: if defined, move the center x-coordinate to the specified value :param y: if defined, move the center y-coordinate to the specified value :return: Location object representing center of Image

clone() Image

Clone this renderable! :return: a Renderable

color(color: Color | None = None, alpha: int = 123) Color

Retrieves or applies a color-mask to the image :param color: the color to mask to, if any :param alpha: The alpha level of the mask, defaults to 123 (half of 255) :return: the mask-color of the object

fill(fill: bool | None = None) bool

Unsupported: This doesn’t make sense for images.

flip(axis: str = 'y')
frame(frame: int | None = None) int

Set the current frame. :param frame: the frame-index to set to :return: the current frame

frames() int

Returns how many frames there are, returns -1 if not animated, 0 if corrupted file. :return:

height(height: float | None = None) float

Get or set the height of the image :param height: the height to set to, if any :return: the height

load() None

Load animated GIF (reads frames) :return: None

next() None

Changes frame to the next frame (Can only be used with animated GIFs) :return:

rotate(angle_diff: float) None

Rotate the angle of the image by a difference, in degrees :param angle_diff: the angle difference to rotate by :return: None

rotation(angle: float | None = None) float

Get or set the rotation of the image. :param angle: the angle to set the rotation to in degrees, if any :return: the angle of the image’s rotation in degrees

update(updated: bool = False)

To be overriden.

vertices() list

Returns the list of vertices for the Renderable. (The vertices will be returned clockwise, starting from the top-leftmost point) :return: a list of Locations representing the vertices

width(width: float | None = None) float

Get or set the width of the image (REQUIRES: PIL or Pillow) :param width: the width to set to, if any :return: None

class pydraw.objects.Line(screen: Screen, *args, color: Color = black, thickness: int = 1, dashes=None, visible: bool = True)

Bases: Object

clone()

Clone a new line! :return: A clone of this line

color(color: Color | None = None) Color

Get or set the color of the line :param color: the color to set to, if any :return: the color of the line

dashes(dashes: int | tuple | None = None) int | tuple

Retrieve or enable/disable the dashes for the line

On systems which support only a limited set of dash patterns, the dash pattern will be displayed as the closest dash pattern that is available. For example, on Windows only a few dash patterns are available, most of which do not allow for special dash-spacing (if passing in a tuple).

Parameters:

dashes – the visibility to set to, if any

Returns:

the toggle-state of dashes

intersects(obj) bool

Check if a line intersects with another line or Renderable :param obj: Line, Renderable, or List/Tuple :return: Whether the line intersects with the object

length() float

Get the length of the line :return: the length of the line

location() tuple

Returns the locations of both the endpoints :return: the locations of both the endpoints

lookat(*args, **kwargs) None

Make the line look at the given point by moving the second point. :return: None

move(*args, **kwargs) None

Move both endpoints by the same dx and dy

Can take either a tuple, Location, or two numbers (dx, dy)

Parameters:
  • dx – the distance x to move

  • dy – the distance y to move

  • point – affect only one of the endpoints options: (1, 2), default=0 (Must be 1 or 2)

Returns:

None

moveto(*args, **kwargs) None

Move both of the endpoints to new locations. :param args: Either two locations, tuples, or four numbers (x1, y1, x2, y2). :return: None

pos1(*args) Location

Get or set the position of the first endpoint. :param args: Either a location or two numbers (x, y) may be passed here. :return: the position of the first endpoint.

pos2(*args) Location

Get or set the position of the second endpoint. :param args: Either a location or two numbers (x, y) may be passed here. :return: the position of the second endpoint.

rotate(angle_diff: float, point: int = 1) float

Rotate the line around one of its vertices (1 by default) :param angle_diff: the angle to rotate by :param point: the point to serve as the origin. :return: the new angle

rotation(angle: float | None = None)

Get or set the rotation of the line (works via pos2()). :param angle: the angle in degrees to rotate by, if any :return: the angle of the line

thickness(thickness: int | None = None) int

Get or set the thickness of the line :param thickness: the thickness to set to, if any :return: the thickness of the line

transform(transform: tuple | None = None)

Copy the line’s length and angle! :param transform: :return:

update()

To be overriden.

visible(visible: bool | None = None) bool

Get or set the visibility of the line :param visible: the visibility to set to, if any :return: the visibility of the line

class pydraw.objects.Object(screen: Screen, x: float = 0, y: float = 0, location: Location | None = None)

Bases: object

A base object containing a location and screen. This ensures coordinates are done with the root in the top left corner, and not at the center.

back() None

Brings the object to the back of the Screen (Imagine moving backward on the Z axis) :return: None

front() None

Brings the object to the front of the Screen (Imagine moving forward on the Z axis) :return: None

location() Location
move(*args, **kwargs) None

Can take either a tuple, Location, or two numbers (dx, dy) :return: None

moveto(*args, **kwargs) None

Move to a new location takes a Location, tuple, or two numbers (x, y) :return: None

pen(color: Color = black, width: int = 2, top: bool = False)
pen_clear()
pen_stop()
pen_top(top: bool | None = None) bool
pen_width(width: int | None = None) int
remove() None
update() None

To be overriden.

x(x: float | None = None) float
y(y: float | None = None) float
class pydraw.objects.Oval

Bases: Renderable

slices() list

Gets the slices of the Oval based on wedges. Note that this generates slices that are not tied to the oval, these are simply slices of the oval based on its wedges. You can use them how you see fit. :return: a tuple (immutable list) of CustomPolygons

wedges(wedges: int | None = None) int
class pydraw.objects.Pen(screen: Screen, x: float, y: float, color: Color = black, width: int = 2, top: bool = False)

Bases: object

clear()

Clear the line from the screen and all history (coordinates).

color(color: Color | None = None) Color
coordinates(*coords) List[Location]
drawing(drawing: bool | None = None) bool
location() Location
move(*args, **kwargs)

Adds a new coordinate to the pen line with a passed difference from the previous coordinate. Requires coordinates to be len > 0.

Can take two numbers (dx, dy), a tuple, or a Location :param dx: the dx to move by :param dy: the dy to move by :return: the location (after change)

moveto(*args, **kwargs)

Adds a new coordinate to the pen line.

Can take two coordinates (x, y), a tuple, or a Location :param x: the x to move to :param y: the y to move to :return: the location (after change)

start()
stop()
toggle() bool
top(top: bool | None = None) bool
width(width: int | None = None) int
class pydraw.objects.Polygon

Bases: Renderable

update()

To be overriden.

class pydraw.objects.Rectangle

Bases: Renderable

class pydraw.objects.Renderable(screen: ~pydraw.screen.Screen, x: float = 0, y: float = 0, width: float = 10, height: float = 10, color: ~pydraw.color.Color = black, border: ~pydraw.color.Color =, fill: bool = True, rotation: float = 0, visible: bool = True, location: ~pydraw.location.Location | None = None)

Bases: Object

Test class for new itemconfigure-based pyDraw objects.

Update method is now only used for changes in position (and possibly changes that cannot be configured and require the item to be remade)

angleto(obj) float

Retrieve the angle between this object and another (based on 0 degrees at 12 o’clock) :param obj: the Object/Location to get the angle to. :return: the angle in degrees as a float

backward(distance: float) None

Move the Renderable backward by distance at its current heading (rotation/angle) :param distance: the distance to move backward (hypotenuse) :return: None

border(color: Color | None = None, width: float | None = None, fill: bool | None = None) Color

Add or get the border of the object :param color: the color to set the border too, set to Color.NONE to remove border :param width: the width of the border :param fill: whether to fill the polygon. :return: The Color of the border

border_width(width: float | None = None) float

Gets or sets the border width :param width: the border width to set to :return: the border width

bounds() -> (<class 'pydraw.location.Location'>, <class 'float'>, <class 'float'>)

Get the location and dimensions of a bounding box that contains the entire shape :return: a tuple containing the Location, width, and height.

center(*args, **kwargs) Location

Returns the location of the center :param move_to: if defined, Move the center to a new Location (Easily center objects!) :param x: if defined, move the center x-coordinate to the specified value :param y: if defined, move the center y-coordinate to the specified value :return: Location object representing center of Renderable

clone()

Clone this renderable! :return: a Renderable

color(color: Color | None = None) Color

Get or set the color of the object :param color: the color to set to, if any :return: the color of the object

contains(*args) bool

Returns whether a Location is contained within the object. :param args: You may pass in either two numbers, a Location, or a tuple containing and x and y point. :return: a boolean value representing whether the point is within the vertices of the object.

distance(obj) float

Returns the distance between two objs or locations in pixels (center to center) :param obj: the Renderable/location to check distance between :return: the distance between this obj and the passed Renderable/Location.

fill(fill: bool | None = None) bool

Returns or sets the current fill boolean :param fill: a new fill value, whether to fill the polygon :return: the fill value

forward(distance: float) None

Move the Renderable forward by distance at its current heading (rotation/angle) :param distance: the distance to move forward (hypotenuse) :return: None

height(height: float | None = None) float

Get or set the height of the object :param height: the height to set to in pixels, if any :return: the height of the object

location() Location
lookat(obj) None

Look at another object (Objects or Locations) :param obj: the Object/Location to look at. :return: None

move(*args, **kwargs) None

Can take either a tuple, Location, or two numbers (dx, dy) :return: None

moveto(*args, **kwargs) None

Move to a new location takes a Location, tuple, or two numbers (x, y) :return: None

overlaps(other: Renderable) bool

Returns if this object is overlapping with the passed object. :param other: another Renderable instance. :return: true if they are overlapping, false if not.

rotate(angle_diff: float = 0) None

Rotate the angle of the object by a difference, in degrees :param angle_diff: the angle difference to rotate by :return: None

rotation(angle: float | None = None) float

Get or set the rotation of the object. :param angle: the angle to set the rotation to in degrees, if any :return: the angle of the object’s rotation in degrees

transform(transform: tuple | None = None) tuple

Get or set the transform of the Renderable. Transforms represent the width, height, and rotation of Renderables.

You can retrieve a Transform from a Renderable with this method and set the transform the same way. :param transform: the transform to set to, if any. :return: the transform

update()

To be overriden.

vertices() list

Returns the list of vertices for the Renderable. (The vertices will be returned clockwise, starting from the top-leftmost point) :return: a list of Locations representing the vertices

visible(visible: bool | None = None) bool

Get or set the visibility of the renderable. :param visible: the new visibility value, if any :return: the visibility value

width(width: float | None = None) float

Get or set the width of the object. :param width: the width to set to in pixels, if any :return: the width of the object

x(x: float | None = None) float
y(y: float | None = None) float
class pydraw.objects.RoundedRectangle

Bases: CustomRenderable

CustomRenderable that creates a rounded rectangle utilizing the border system. As a result borders are unavailable and immutable in this Object.

property border

(!) Disallowed inherited

radius(radius: float | None = None) float

Set the border radius of the rounded shape. :param radius: the radius to set to (not pixel accurate) :return: the radius

update()

To be overriden.

class pydraw.objects.Text

Bases: CustomRenderable

align(align: str | None = None) str

Get or set the alignment of the text, if a new value is passed it must be ‘left’, ‘center’, or ‘right’. :param align: the alignment to set to, if any :return: the alignment of the text

bold(bold: bool | None = None) bool

Get or set the bold status of the text :param bold: the bold status to set to, if any :return: the bold status of the text

center(*args, **kwargs) Location

Returns the location of the center :param move_to: if defined, Move the center to a new Location (Easily center objects!) :param x: if defined, move the center x-coordinate to the specified value :param y: if defined, move the center y-coordinate to the specified value :return: Location object representing center of Renderable

clone()

Clone this text! :return: A cloned text object!

color(color: Color | None = None) Color

Get or set the color of the text :param color: the color to set to, if any :return: the color of the text

font(font: str | None = None) str

Get or set the font of the text :param font: the font to set to, if any :return: the font of the text

height() float

Get the height of the text, (cannot be modified, although technically the font-size is the text’s height) :return: the height of the text.

italic(italic: bool | None = None) bool

Get or set the italic status of the text :param italic: the italic status to set to, if any :return: the italic status of the text

lookat(obj)

Look at another object (Objects or Locations) :param obj: the Object/Location to look at. :return: None

move(*args, **kwargs) None

Can take either a tuple, Location, or two numbers (dx, dy) :return: None

moveto(*args, **kwargs) None

Move to a new location takes a Location, tuple, or two numbers (x, y) :return: None

rotate(angle_diff: float = 0) None

Rotate the angle of the text by a difference, in degrees :param angle_diff: the angle difference to rotate by :return: Nonea

rotation(rotation: float | None = None) float

Get or set the rotation of the text :param rotation: the strikethrough to set to, if any :return: the rotation of the text

size(size: int | None = None) int

Get or set the size of the text :param size: the size to set to, if any :return: the size of the text

strikethrough(strikethrough: bool | None = None) bool

Get or set the strikethrough status of the text :param strikethrough: the strikethrough status to set to, if any :return: the strikethrough status of the text

text(text: str | None = None) str

Get or set the text. Use ‘

‘ to separate lines
param text:

text to set to (str), if any

return:

the text

transform(transform: tuple | None = None) tuple

Retrieve the transform of the text :param transform: Unsupported. :return: a tuple with representing: (width, height, angle)

underline(underline: bool | None = None) bool

Get or set the underline status of the text :param underline: the underline status to set to, if any :return: the underline status of the text

update() None

To be overriden.

vertices() list

Get the vertices of a Rectangle superposed in the same transform of the Text :return: a list of Locations

visible(visible: bool | None = None) bool

Get or set the visibility of the text :param visible: the visibility to set to, if any :return: the visibility of the text

width() float

Get the width of the text (cannot be modified) :return the width of the text

class pydraw.objects.Triangle

Bases: Renderable

pydraw.screen module

class pydraw.screen.Screen(width: int = 800, height: int = 600, title: str = 'pydraw')

Bases: object

A class containing methods and values that can be manipulated in order to affect the window that is created. Sort of like a canvas.

class Key(key: str)

Bases: object

key() str

Returns the string for the key. :return: the key in ascii

add(obj) None

Add an object back to the Screen after having removed it (with Object.remove() or Screen.remove(object) :param obj: the Object to add back. :return: None

alert(text: str, title: str = 'Alert', accept_text: str = 'Ok', cancel_text: str = 'Cancel') bool

Displays a dialog-box alert, and returns :param text: The text to display in the body of the dialog :param title: The title of the dialog-box :param accept_text: The text displayed on the accept button, defaults to ‘Ok’ :param cancel_text: The text displayed on the cancel button, defaults to ‘Cancel’ :return: True if accept was pressed, False if cancel was pressed

bottom_left() Location

Returns the bottom left corner of the screen :return: Location

bottom_right() Location

Returns the bottom right corner of the screen :return: Location

canvas_location(x, y) Location
center() Location

Gets the center of the screen.

clear() None

Clears the screen. :return: None

color(color: Color | None = None) Color

Set the background color of the screen. :param color: the color to set the background to :return: None

contains(obj) bool

Returns whether or not the passed object exists on the Screen (is in the objects cache) :param obj: the Object to check :return: a boolean

create_location(x, y, canvas: bool = False) Location

Is passed turtle-based coordinates and converts them into normal coordinates :param x: the x component :param y: the y component :param canvas: whether or not the supplied coordinates are from the canvas or input :return: a location comprised of the passed x and y components

exit() None

Called at the end of pydraw programs as an event for succesful program execution and termination. For something similar to turtle.done() see Screen.stop() :return: None

fullscreen(fullscreen: bool | None = None) bool

Get or set the fullscreen state of the application. Note that this will not resize your shapes, nor will it REPOSITION them. It is highly recommended that you call this method before creating any shapes!

!!! EXPERIMENTAL !!! :param fullscreen: the new fullscreen state, if any :return: the current fullscreen state of the Screen

grab(filename: str | None = None) str

Grabs a screenshot of the image and saves it to the directory with the specified filename! Note that if no filename is specified the file will be given a name based on the epoch time. :param filename: the name of the file to save the screenshot to. :return: the name of the file.

grid(rows: int | None = None, cols: int | None = None, cellsize: tuple = (50, 50), helpers: bool = True)
gridlines() tuple

Allows you to retrieve the lines of the grid, but note that you cannot modify them! :return: a tuple (immutable list) of the gridlines.

height() int

Returns the height of the CANVAS within the screen. Important. :return:

listen() None

Reads the file for input functions and registers them as callbacks! The input-type is determined by the name of the function.

Allowed Names:
  • mousedown

  • mouseup

  • mousedrag

  • keydown

  • keyup

  • keypress (deprecated)

Returns:

None

loop() None

Holds the program open and calls screen.update() for you. Must be used at the end of any pyDraw program unless there is a while loop with screen.update() in it instead.

Returns:

None

mouse() Location

Get the current mouse-position :return: the mouse-position in the form of a Location

objects() tuple

Retrieves all objects on the Screen! :return: A tuple (immutable list) of Objects (you will want to check types for certain methods!)

picture(pic: str) None

Set the background picture of the screen. :param pic: the path to said picture from the file :return: None

prompt(text: str, title: str = 'Prompt') str

Prompts the user for keyboard input :param: text the text to prompt the user with :param: title the title of the dialog box :return: None

remove(obj)
reset() None

Resets the screen, removing all objects and input methods. :return: None

resize(width: int, height: int) None

Resize the screen to new dimensions :param width: the width to resize to :param height: the height to resize to :return: None

scene(scene=None)

Apply a new scene to the screen!

Note that this will override ALL previously registered input handlers. :param scene: The Scene to apply! :return: None

size() -> (<class 'int'>, <class 'int'>)

Get the size of the WINDOW (please note this is not the canvas, and those attributes should be retrieved using the width() and height() methods respectively) :return: a tuple containing the width and height of the WINDOW

sleep(delay: float, delta: bool = False) None

Cause the program to sleep by calling time.sleep(delay)

You can enable the ‘deltaTime’ feature by passing in the delta parameter is true, which will allow it to calculate the time between time.sleep(delay), and take that into account, reducing delay by that amount.

Parameters:
  • delay – the delay in seconds to sleep by

  • delta – enable the deltaTime feature which will take processing time into account for sleep time

Returns:

None

stop() None

Deprecated. Use screen.loop instead. :return: None

title(title: str | None = None) str

Get or set the title of the screen. :param title: the title to set to, if any :return: the title

toggle_grid(value=None)
top_left() Location

Returns the top left corner of the screen :return: Location

top_right() Location

Returns the top right corner of the screen :return: Location

update() None

Updates the screen. :return: None

width() int

Returns the width of the CANVAS within the screen. Important. :return: an integer representing the width of the canvas

pydraw.scene module

class pydraw.scene.Scene

Bases: object

An abstraction of the Screen, designed to store the Screen in a certain state while retaining registered input handlers and the positions and attributes of objects registered to it.

You can use Scenes to create multi-screen games or to manage different levels easily. It works exactly like a screen but will not render anything until it is “applied” to a Screen via Screen.scene(some_scene)

activate(screen: Screen) None

Activates the Scene with a Screen (called internally) :param screen: the Screen to display the Scene on :return: None

keydown(key: Key) None

Key event called when a key is pressed :param key: the Key that was pressed :return: None

keyup(key: Key) None

Key event called when a key is released :param key: the Key that was released :return: None

mousedown(location: Location, button: int) None

Mouse event, called when a mouse button is pressed down. :param button: the button pressed (0-2) :param location: the location that was clicked :return: None

mousedrag(location: Location, button: int) None

Mouse event, called when the mouse moves after a mousedown event (without a mouseup event) :param button: the button being held (0-2) :param location: the Location the mouse has moved to :return: None

mousemove(location: Location) None

Mouse event called when the mouse moves over the Screen :param location: the Location the mouse moved to :return: None

mouseup(location: Location, button: int) None

Mouse event, called when a mouse button is released. :param button: the button released (0-2) :param location: the location that was clicked :return: None

run() None

Run the scene (the loop should go here) :return: None

screen()

Retrieve the screen that the scene is tied to :return: a Screen

start() None

Run as the initializer for the scene :return: None

pydraw.sound module

pydraw.util module

pydraw.util.verify(*args)

Takes a list of values and expected types and returns if all objects meet their expected types. :param args: a list of objects and types, ex: (some_number, float, some_location, Location) :return: True if all args meet their expected types, throws an error if not.

pydraw.util.verify_type(obj, required_type)

Verifies an objects type is the passed type :param obj: the object to check :param required_type: the expected type :return: True if required type is present or obj is None, else False