Metadata-Version: 2.4
Name: p5-python
Version: 0.9.1
Summary: A package wrapping pygame functionality in p5.js calling conventions.
License: MIT
Author: Grygoriy Gromko
Author-email: gr.gromko@gmail.com
Requires-Python: >=3.8.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: PyOpenGL (>=3.1.0,<4.0.0)
Requires-Dist: pycairo (>=1.20.0,<2.0.0)
Requires-Dist: pygame (>=2.1.2,<3.0.0)
Project-URL: Homepage, https://github.com/gromko/p5-python
Project-URL: Repository, https://github.com/gromko/p5-python
Description-Content-Type: text/markdown

# p5-python

`p5-python` brings the friendly [p5.js](https://p5js.org/) drawing API to
Python. It is a free and open-source library built by an inclusive, nurturing
community and welcomes artists, designers, beginners, educators, and anyone
else.

Sketches are written with familiar p5 conventions (`setup`, `draw`,
`createCanvas`, `background`, `fill`, ...) and rendered with
[pygame](https://www.pygame.org/) and [Cairo](https://cairographics.org/).

## Installation

```sh
pip install p5-python
```

Requirements: Python 3.8+, `pygame >= 2.1.2`, `pycairo >= 1.20.0`.

## Quick start

Create `sketch.py`:

```python
from p5 import *


def setup():
    createCanvas(640, 360)


def draw():
    background(20)
    fill(255, 120, 40)
    noStroke()
    circle(mouseX, mouseY, 60)


run()
```

Run it either directly or through the module runner:

```sh
python sketch.py
python -m p5 sketch.py
```

## What is supported

### Canvas and program flow

`createCanvas`, `resizeCanvas`, `saveCanvas`, `saveFrame`, `background`,
`clear`, `run`, `stop`, `frameRate`, `getFrameRate`, `loop`, `noLoop`,
`redraw`, `isLooping`, `cursor`, `noCursor`, `pixelDensity`, `smooth`,
`noSmooth`, `angleMode`.

Angles are measured in **radians** by default, matching p5.js. Call
`angleMode(DEGREES)` if you prefer degrees.

### Shapes

`point`, `line`, `rect`, `square`, `ellipse`, `circle`, `arc`, `triangle`,
`quad`, `bezier`, `curve`, plus the vertex API:

```python
beginShape()
vertex(100, 100)
vertex(200, 40)
vertex(300, 100)
endShape(CLOSE)
```

`beginShape()` accepts `POINTS`, `LINES`, `LINE_STRIP`, `TRIANGLES`,
`TRIANGLE_STRIP`, `TRIANGLE_FAN`, `QUADS`, and `QUAD_STRIP`. Vertices can be
mixed with `curveVertex()` and `bezierVertex()`; `endShape(CLOSE)` closes and
fills the outline.

Drawing modes: `rectMode`, `ellipseMode`, `imageMode` (`CORNER`, `CORNERS`,
`CENTER`, `RADIUS`).

### Colour

`fill`, `stroke`, `noFill`, `noStroke`, `color`, `colorMode`, `lerpColor`,
and the channel accessors `red`, `green`, `blue`, `alpha`, `hue`,
`saturation`, `brightness`, `lightness`.

`colorMode()` supports `RGB` and `HSB` with custom ranges, plus an optional
alpha range.

### Typography

`text`, `textFont`, `textSize`, `textStyle`, `textAlign`, `textWidth`,
`textLeading`, `textWrap`, `loadFont`.

### Images and pixels

`loadImage`, `image`, `PImage`, `createImage`, `tint`, `noTint`,
`loadPixels`, `updatePixels`, `get`, `set`, `blendMode`. `get()`/`set()` work
on both the whole canvas and rectangular regions, and `pixels` is exposed as a
writable RGBA list. `saveCanvas` and `saveFrame` write PNG files (with a JPG
fallback).

`PImage` objects can be created in memory, edited pixel by pixel, and drawn:

```python
img = createImage(64, 64)
img.loadPixels()
for i in range(0, len(img.pixels), 4):
    img.pixels[i:i + 4] = [255, 128, 0, 255]
img.updatePixels()

tint(255, 150)
image(img, 20, 20)
noTint()
```

`screen.pixels` is an alias for the global `pixels` array, and
`println(...)`/`print(...)` write to standard output.

### Math and randomness

`abs`, `ceil`, `floor`, `round`, `sq`, `sqrt`, `pow`, `exp`, `log`, `log2`,
`log10`, `logb`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`,
`degrees`, `radians`, `dist`, `mag`, `map`, `norm`, `lerp`, `constrain`,
`sign`, `min`, `max`, `random`, `randomSeed`, `randomGaussian`, `noise`,
`noiseSeed`, `noiseDetail`, `shuffle`, `nf`.

### Transforms

`push`, `pop`, `translate`, `rotate`, `scale`, `shearX`, `shearY`,
`applyMatrix`, `resetMatrix`. Transforms use a real affine matrix, so they
compose and nest correctly.

### Vectors

```python
v = createVector(3, 4)
v.add(createVector(1, 2))
print(v.mag())       # 6.324...
print(v.heading())
```

`Vector` (also available as `PVector`) supports `add`, `sub`, `mult`, `div`,
`mag`, `magSq`, `normalize`, `limit`, `heading`, `rotate`, `lerp`, `dist`,
`dot`, `cross`, `copy`, `get`, `set`, `setMag`, and the usual operators.

### Compatibility helpers

For sketches written in a Processing style the following are also available:

- `environment` (`frameCount`, `width`, `height`, `focused`, ...)
- `keyboard` (`key`, `keyCode`, `keyIsPressed`, `keys`)
- `mouse` (`x`, `y`, `px`, `py`, `pressed`, `button`, ...)
- `focused`
- `textAscent()`, `textDescent()`
- `WEBGL` mode renders real 3D geometry with PyOpenGL: `box`, `sphere`,
  `torus`, `cone`, `cylinder`, `ambientLight`, `directionalLight`,
  `rotateX/Y/Z`, and `translate(x, y, z)`.

### Events and live values

Define any of these functions in your sketch and they are called
automatically:

`keyPressed`, `keyReleased`, `mousePressed`, `mouseReleased`,
`mouseClicked`, `doubleClicked`, `mouseMoved`, `mouseDragged`,
`mouseWheel`.

Mouse callbacks may either take no parameters or an `event` argument:

```python
def mousePressed():
    print(mouse.x, mouse.y)

def mouseWheel(event):
    radius += event.delta
```

Mouse events expose `x`, `y`, `button`, `delta`, `dx`, `dy`, and `pos`.
The live `mouse` object groups the same state:

```python
mouse.x, mouse.y       # current position
mouse.px, mouse.py     # previous position
mouse.pressed          # button held down
mouse.button           # LEFT / RIGHT / CENTER
```

Live values are available as bare names (and as attributes such as
`p5.mouseX`):

`width`, `height`, `displayWidth`, `displayHeight`, `windowWidth`,
`windowHeight`, `mouseX`, `mouseY`, `pmouseX`, `pmouseY`, `movedX`,
`movedY`, `mouseButton`, `mouseIsPressed`, `mouseWheelDelta`, `key`,
`keyCode`, `keyIsPressed`, `frameCount`, `deltaTime`, `pixels`,
`is_Looping`.

`mouseX` and `mouseY` can be used either as properties (`mouseX + 10`) or as
functions (`mouseX()`), so both p5.js-style and Processing-style sketches work.

`keyCode` compares equal to the matching constants (`SPACE`, `LEFT_ARROW`,
`A`, ...), while `key` holds the typed character where available. Use
`keyIsDown(...)` for continuous input:

```python
if keyIsDown(LEFT_ARROW):
    x -= 5
```

## Constants

Constants such as `PI`, `TWO_PI`, `HALF_PI`, `TAU`, `CENTER`, `CORNER`,
`CORNERS`, `RADIUS`, `CLOSE`, `OPEN`, `RGB`, `HSB`, `LEFT`, `RIGHT`, `TOP`,
`BOTTOM`, `BASELINE`, arrow keys, letter/number key codes, `BLEND`, `ADD`,
`MULTIPLY`, `SCREEN`, `OVERLAY`, `DARKEST`, `LIGHTEST`, `DIFFERENCE`,
`EXCLUSION`, `REPLACE`, and the shape-kind constants are all exported by
`from p5 import *`.

## Differences from p5.js

- Rendering uses pygame/Cairo instead of an HTML canvas.
- `LEFT`/`RIGHT` are mouse- and text-alignment constants (`"left"`,
  `"right"`). For the arrow keys use `LEFT_ARROW`/`RIGHT_ARROW`.
- `loadFont` accepts a path to a TrueType/OpenType font; system fonts can be
  selected by family name.
- Web-specific APIs (DOM, WEBGL, sound, video) are not implemented.

## Project layout

```
p5/
  color.py        colour parsing, colour modes, fill/stroke
  constants.py    p5 constants, key codes, blend/shape modes
  corefunctions.py  sketch lifecycle, primitives, pixels, images, events
  image.py        PImage, createImage and image pixel helpers
  mathfunctions.py  math, random, noise
  renderer.py     Cairo drawing backend
  settings.py     live sketch state
  timedata.py     date/time helpers
  transform.py    affine transform stack
  vector.py       Vector and createVector
```

## Examples and tests

Runnable sketches live in `examples/`:

```sh
pip install -e .
python examples/basic_shapes.py
python examples/interactive.py
python examples/animation.py
```

The headless test suite runs without a display:

```sh
python -m unittest discover -s tests
```

## License

MIT. See the project page for details and contributions:
<https://github.com/gromko/p5-python>.

