Implement the 'actions' submodule (#100)

Closes #85

.github/workflows/main.yml

@@ -8,13 +8,13 @@ on:
 
 jobs:
   test:
-    name: test w/ Python ${{ matrix.python_version }}
+    name: test w/ Python ${{ matrix.python-version }}
 
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        python_version: ["3.6", "3.7", "3.8"]
+        python-version: ["3.6", "3.7", "3.8"]
 
     steps:
       - uses: actions/checkout@v1
@@ -26,14 +26,13 @@ jobs:
             ${{ runner.os }}-pip-
       - uses: actions/setup-python@v1
         with:
-          python-version: ${{ matrix.python_version }}
-      - run: pip install flit
-      - run: flit install --deps develop
-      - name: Run `pytest --cov`
-        run: pytest --cov --cov-report=xml:cov.xml
+          python-version: ${{ matrix.python-version }}
+      - run: pip install nox
+      - run: nox --session tests-${{ matrix.python-version }}
         env:
           PYTHONDEVMODE: 1
       - uses: codecov/codecov-action@v1
+        if: always()
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           file: ./cov.xml
@@ -52,10 +51,5 @@ jobs:
       - uses: actions/setup-python@v1
         with:
           python-version: "3.8"
-      - run: pip install flit
-      - run: flit install --deps develop
-      - run: black --check .
-      - name: Check type hints
-        run: mypy --ignore-missing-imports --strict gidgethub/*.py
-      - name: Check docs
-        run: sphinx-build -nW -q -b html -b linkcheck -d docs/_build/doctrees docs docs/_build/html
+      - run: pip install nox
+      - run: nox --session lint

.gitignore

@@ -98,3 +98,6 @@ ENV/
 
 # pytest
 .pytest_cache
+
+# nox
+.nox

Third-Party Notice - GitHub Actions Toolkit.md

@@ -0,0 +1,7 @@
+Copyright 2019 GitHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

docs/__init__.rst

@@ -72,6 +72,17 @@ Exceptions
       A list of error details for each field which was invalid.
 
 
+.. exception:: ValidationError(errors, *args)
+
+   A request was unable to be completed.
+
+   Inherits from :exc:`BadRequest` a 422 HTTP response.
+
+   .. attribute:: errors
+
+      Error details.
+
+
 .. exception:: GitHubBroken
 
    An exception representing 5XX HTTP responses.

docs/actions.rst

@@ -0,0 +1,37 @@
+:mod:`gidgethub.actions` --- Support for GitHub Actions
+=======================================================
+
+.. module:: gidgethub.actions
+
+.. versionadded:: 4.0.0
+
+This module is to help provide support for `GitHub Actions`_ when writing a
+`container action <https://help.github.com/en/actions/building-actions/creating-a-docker-container-action>`__.
+
+
+.. function:: workspace()
+
+    Return a :class:`pathlib.Path` object representing the ``GITHUB_WORKSPACE``
+    path. As the location is considered static, the function is idempotent after
+    its initial call.
+
+.. function:: event()
+
+    Return the webhook event data as kept at the path as pointed at by the
+    ``GITHUB_EVENT_PATH`` environment variable. As the data is considered
+    static, the function is idempotent after its initial call.
+
+
+.. function:: command(cmd, val, **parameters)
+
+   Issue a `logging command <https://help.github.com/en/actions/reference/development-tools-for-github-actions#logging-commands>`_.
+
+   Note that no automatic string conversion is performed on any arguments.
+
+   ::
+
+     # `::warning file=app.js,line=1,col=5::Missing semicolon`
+     gidgethub.actions.command("warning", "Missing semicolon", file="app.js", line="1", col="5")
+
+
+.. _GitHub Actions: https://help.github.com/en/actions

docs/changelog.rst

@@ -1,6 +1,21 @@
 Changelog
 =========
 
+4.0.0
+'''''
+
+.. note::
+   Under development
+
+- Remove `gidgethub.treq`; tests were not passing and a request for help on
+  Twitter came back with no reponse (happy to add back if someone steps forward
+  to help out).
+- Remove `gidgethub.test` from the distribution.
+- Introduce :mod:`gidgethub.actions`.
+- Add :exc:`gidgethub.ValidationError` for when the HTTP response is a 422 but not
+  field-related. ([#83](https://github.com/brettcannon/gidgethub/pull/83);
+  thanks [John Hossler](https://github.com/jmhossler))
+
 3.3.0
 '''''
 
@@ -128,7 +143,7 @@ Changelog
 1.1.0
 '''''
 
-- Introduced :mod:`gidgethub.treq` (thanks to Cory Benfield).
+- Introduced ``gidgethub.treq`` (thanks to Cory Benfield).
 
 
 1.0.0

docs/conf.py

@@ -84,7 +84,8 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+# pygments_style = 'sphinx'
+highlight_language = "python3"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False

docs/index.rst

@@ -129,10 +129,10 @@ Contents
    changelog
    __init__
    sansio
+   actions
    routing
    abc
    aiohttp
-   treq
    tornado
    httpx
 

gidgethub/__init__.py

@@ -1,5 +1,5 @@
 """An async GitHub API library"""
-__version__ = "3.3.0"
+__version__ = "4.0.0"
 
 import http
 from typing import Any
@@ -76,8 +76,8 @@ class ValidationError(BadRequest):
 
     """A request was unable to be completed.
 
-    Represented by a 422 HTTP Response. Details of what went wrong
-    are stored in the errors attribute.
+    Represented by a 422 HTTP response. Details of what went wrong
+    are stored in the *errors* attribute.
     """
 
     def __init__(self, errors: Any, *args: Any) -> None:

gidgethub/actions.py

@@ -0,0 +1,45 @@
+"""Support for GitHub Actions."""
+import functools
+import json
+import os
+import pathlib
+from typing import Any
+import urllib.parse
+
+
+@functools.lru_cache(maxsize=1)
+def workspace() -> pathlib.Path:
+    """Return the action workspace as a pathlib.Path object."""
+    return pathlib.Path(os.environ["GITHUB_WORKSPACE"])
+
+
+@functools.lru_cache(maxsize=1)
+def event() -> Any:
+    """Return the webhook event data for the running action."""
+    with open(os.environ["GITHUB_EVENT_PATH"], "r", encoding="utf-8") as file:
+        return json.load(file)
+
+
+# https://github.com/actions/toolkit/blob/b0e01b71c0e630eb4b420f763029a7476c6cf075/packages/core/src/command.ts#L76-L81
+_DATA_ESCAPE = [("%", "%25"), ("\r", "%0D"), ("\n", "%0A")]
+# https://github.com/actions/toolkit/blob/b0e01b71c0e630eb4b420f763029a7476c6cf075/packages/core/src/command.ts#L83-L90
+_VALUE_ESCAPE = [("%", "%25"), ("\r", "%0D"), ("\n", "%0A"), (":", "%3A"), (",", "%3A")]
+
+
+def command(cmd: str, data: str = "", **parameters: str) -> None:
+    """Issue a logging command."""
+    cmd_parts = [f"::{cmd}"]
+    if parameters:
+        cmd_parts.append(" ")
+        param_list = []
+        for param, val in parameters.items():
+            val = functools.reduce(
+                lambda accum, args: accum.replace(*args), _VALUE_ESCAPE, val
+            )
+            param_list.append(f"{param}={val}")
+        cmd_parts.append(",".join(param_list))
+    data = functools.reduce(
+        lambda accum, args: accum.replace(*args), _DATA_ESCAPE, data
+    )
+    cmd_parts.append(f"::{data}")
+    print("".join(cmd_parts))