Add our first getting started tutorial (#251)

swyddfa · Jul 4, 2020 · 239e636 · 239e636
1 parent d419455
commit 239e636
Show file tree

Hide file tree

Showing 13 changed files with 298 additions and 224 deletions.
diff --git a/.gitignore b/.gitignore
@@ -3,7 +3,6 @@
 .coverage
 .hypothesis
 .ipynb_checkpoints/
-.scratch
 .pytest_cache
 .mypy_cache
 .tox

diff --git a/.scratch/.gitignore b/.scratch/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -9,7 +9,6 @@
         "build": true,
         "dist": true,
         "pip-wheel-metadata": true,
-        ".dev": true,
         "htmlcov": true,
         ".coverage": true,
         "coverage.xml": true,

diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -22,53 +22,34 @@
             }
         },
         {
-            "label": "Build Docs",
+            "label": "Jupyter",
             "type": "shell",
-            "command": "source ${workspaceRoot}/.env/bin/activate && sphinx-autobuild -E -a -b html docs/ docs/_build/",
+            "command": "source ${workspaceRoot}/.env/bin/activate && jupyter-lab ${input:jupyterArgs}",
             "problemMatcher": [],
             "group": "build",
+            "isBackground": true,
             "options": {
-                "cwd": "${workspaceRoot}"
-            }
-        },
-        {
-            "label": "Build Tutorial",
-            "type": "shell",
-            "command": "source ${workspaceRoot}/.env/bin/activate && sphinx-build -M nbtutorial docs/ docs/_build/ -E -a",
-            "problemMatcher": [],
-            "group": "build",
-            "options": {
-                "cwd": "${workspaceRoot}"
+                "cwd": "${input:jupyterWd}"
             }
         },
         {
-            "label": "Edit Gallery",
-            "type": "shell",
-            "command": "source ${workspaceRoot}/.env/bin/activate && jupyter-lab --no-browser",
-            "problemMatcher": [],
-            "group": "build",
-            "options": {
-                "cwd": "${workspaceRoot}/blog/src/gallery"
-            }
-        },
-        {
-            "label": "Edit Gallery (browser)",
+            "label": "Preview Blog",
             "type": "shell",
-            "command": "source ${workspaceRoot}/.env/bin/activate && jupyter-lab",
+            "command": "${config:python.pythonPath} -m http.server 8001",
             "problemMatcher": [],
             "group": "build",
             "options": {
-                "cwd": "${workspaceRoot}/blog/src/gallery"
+                "cwd": "${workspaceRoot}/blog/public"
             }
         },
         {
-            "label": "Preview Blog",
+            "label": "Sphinx",
             "type": "shell",
-            "command": "${config:python.pythonPath} -m http.server 8001",
+            "command": "source ${workspaceRoot}/.env/bin/activate && make ${input:builder}",
             "problemMatcher": [],
             "group": "build",
             "options": {
-                "cwd": "${workspaceRoot}/blog/public"
+                "cwd": "${workspaceRoot}/docs"
             }
         },
         {
@@ -103,36 +84,6 @@
             "options": {
                 "cwd": "${workspaceRoot}"
             }
-        },
-        {
-            "label": "Scratch Notebooks",
-            "type": "shell",
-            "command": "source ${workspaceRoot}/.env/bin/activate && jupyter-lab",
-            "problemMatcher": [],
-            "group": "build",
-            "options": {
-                "cwd": "${workspaceRoot}/.scratch"
-            }
-        },
-        {
-            "label": "Open Tutorial",
-            "type": "shell",
-            "command": "source ${workspaceRoot}/.env/bin/activate && jupyter-lab",
-            "problemMatcher": [],
-            "group": "build",
-            "options": {
-                "cwd": "${workspaceRoot}/docs/_build/nbtutorial/users"
-            }
-        },
-        {
-            "label": "Test File",
-            "type": "shell",
-            "command": "${config:python.pythonPath} -m tox -e py38 -- ${file}",
-            "problemMatcher": [],
-            "group": "test",
-            "options": {
-                "cwd": "${workspaceRoot}"
-            }
         }
     ],
     "inputs": [
@@ -168,10 +119,39 @@
             ],
             "default": "-e py38"
         },
+        {
+            "id": "builder",
+            "description": "Sphinx builders",
+            "type": "pickString",
+            "default": "html",
+            "options": [
+                {
+                    "label": "Build HTML Docs",
+                    "value": "html"
+                },
+                {
+                    "label": "Extract gallery images",
+                    "value": "nbgallery"
+                },
+                {
+                    "label": "Extract tutorial",
+                    "value": "nbtutorial"
+                },
+                {
+                    "label": "Test Examples",
+                    "value": "doctest"
+                },
+                {
+                    "label": "Test Links",
+                    "value": "linkcheck"
+                }
+            ]
+        },
         {
             "id": "blogArgs",
             "description": "Blog Arguments",
             "type": "pickString",
+            "default": "--local",
             "options": [
                 {
                     "label": "Local",
@@ -189,8 +169,39 @@
                     "label": "Local, debug, skipping errors",
                     "value": "-vv --local --skip-failures"
                 }
-            ],
-            "default": "--local"
+            ]
+        },
+        {
+            "id": "jupyterArgs",
+            "description": "Jupyter Arguments",
+            "type": "pickString",
+            "default": "",
+            "options": [
+                {
+                    "label": "Headless",
+                    "value": "--no-browser"
+                },
+                {
+                    "label": "In Browser",
+                    "value": ""
+                }
+            ]
+        },
+        {
+            "id": "jupyterWd",
+            "description": "Working directory for jupyter",
+            "type": "pickString",
+            "default": ".scratch",
+            "options": [
+                {
+                    "label": "Scratch Folder",
+                    "value": ".scratch"
+                },
+                {
+                    "label": "Gallery",
+                    "value": "blog/src/gallery"
+                }
+            ]
         }
     ]
 }
diff --git a/arlunio/image.py b/arlunio/image.py
@@ -98,12 +98,35 @@ def thumbnail(self, *args, **kwargs):
         self.img.thumbnail(*args, **kwargs)
 
 
-def new(*args, **kwargs):
-    """Creates a new image with the given mode and size
+def new(size, *args, mode="RGBA", **kwargs) -> Image:
+    """Creates a new image with the given size.
+
+    This function by default will return a new :code:`RGBA` image with the given
+    dimensions. Dimensions can be specified either using a tuple :code:`(width, height)`
+    or by passing in :code:`width` and :code:`height` individually as positional
+    parameters.
+
+    This makes use of pillow's :func:`pillow:PIL.Image.new` function, additional keyword
+    arguments passed to this function will be passed onto it.
+
+    Parameters
+    ----------
+    size:
+        The dimensions of the image, :code:`(width, height)`
+    mode:
+        The type of image to create, default :code:`RGBA`. See
+        :ref:`pillow:concept-modes` for more details.
 
-    See :func:`pillow:PIL.Image.new`
     """
-    return Image(PImage.new(*args, **kwargs))
+
+    if isinstance(size, int):
+        if len(args) == 0:
+            raise ValueError("You must specify a width and a height")
+
+        height, args = args[0], args[1:]
+        size = (size, height)
+
+    return Image(PImage.new(mode, size, *args, **kwargs))
 
 
 def fromarray(*args, **kwargs):
@@ -150,7 +173,7 @@ def encode(image: Image) -> bytes:
     ::
 
        >>> import arlunio.image as image
-       >>> img = image.new("RGBA", (8, 8), color='red')
+       >>> img = image.new((8, 8), color='red')
        >>> image.encode(img)
        b'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAFklEQVR4nGP8z8DwnwEPYMInOXwUAAASWwIOH0pJXQAAAABJRU5ErkJggg=='
 
@@ -245,7 +268,6 @@ def colorramp(values, start: Optional[str] = None, stop: Optional[str] = None) -
           cartesian = math.Cartesian()
           p = cartesian(width=256, height=256)
 
-          bg = image.new("RGBA", (256, 256), color="black")
           x = image.colorramp(p[:, :, 0], start="#0000", stop="#f007")
           y = image.colorramp(p[:, :, 1], start="#0000", stop="#00f7")
 
@@ -328,7 +350,7 @@ def fill(
         background = "#0000" if background is None else background
 
         height, width = mask.shape
-        image = new("RGBA", (width, height), color=background)
+        image = new((width, height), color=background)
 
     else:
         image = image.copy()

diff --git a/arlunio/shape.py b/arlunio/shape.py
@@ -57,7 +57,7 @@ def Circle(x: math.X, y: math.Y, *, xc=0, yc=0, r=0.8, pt=None) -> mask.Mask:
 
           @ar.definition
           def Target(width: int, height: int) -> image.Image:
-              img = image.new("RGBA", (width, height), color="white")
+              img = image.new((width, height), color="white")
               parts = [
                   (shape.Circle(pt=0.02), "#000"),
                   (shape.Circle(r=0.75, pt=0.12), "#f00"),
@@ -96,7 +96,7 @@ def OlympicRings(width: int, height: int, *, spacing=0.5, pt=0.025):
               dx = spacing / 2
               args = {"scale": 0.5, "r": spacing, "pt": pt}
 
-              img = image.new("RGBA", (width, height), color="white")
+              img = image.new((width, height), color="white")
               rings = [
                   (shape.Circle(yc=dy, xc=-(2.2 * dx), **args), "#0ff"),
                   (shape.Circle(yc=dy, **args), "#000"),
@@ -194,7 +194,7 @@ def Ellipse(x: math.X, y: math.Y, *, xc=0, yc=0, a=2, b=1, r=0.8, pt=None) -> ma
 
           @ar.definition
           def EllipseDemo(width: int, height: int):
-              img = image.new("RGBA", (width, height), color="white")
+              img = image.new(width, height, color="white")
               ellipses = [
                   shape.Ellipse(xc=-0.5, yc=-0.5, a=0.5, b=0.5, r=0.4),
                   shape.Ellipse(yc=-0.5, a=1, b=0.5, r=0.4),
@@ -340,7 +340,7 @@ def SuperEllipse(
 
           @ar.definition
           def SuperEllipseDemo(width: int, height: int):
-              img = image.new("RGBA", (width, height), color="white")
+              img = image.new(width, height, color="white")
               ellipses = [
                   (shape.SuperEllipse(n=0.5, pt=0.01),'#f00'),
                   (shape.SuperEllipse(n=1, pt=0.01),'#0f0'),
@@ -376,7 +376,7 @@ def SuperEllipseDemo(width: int, height: int):
 
           @ar.definition
           def Sauron(width: int, height: int):
-              img = image.new("RGBA", (width, height), color="white")
+              img = image.new(width, height, color="white")
               ellipses = [
                   (shape.SuperEllipse(a=2, n=3, m=0.2, r=0.98),'#f00'),
                   (shape.SuperEllipse(n=2),'#f50'),