Merge pull request #142 from andrewthetechie/dependabot/pip/pyupgrade-2.32.1

Bump pyupgrade from 2.32.0 to 2.32.1

.github/workflows/constraints.txt

@@ -1,6 +1,6 @@
-pip==21.3.1
+pip==22.1.1
-nox==2021.10.1
+nox==2022.1.7
-nox-poetry==0.9.0
+nox-poetry==1.0.0
-poetry==1.1.12
+poetry==1.1.13
-virtualenv==20.10.0
+virtualenv==20.14.1
-poetry-dynamic-versioning==0.13.1
+poetry-dynamic-versioning==0.17.1

.github/workflows/labeler.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v2.4.0
+        uses: actions/checkout@v3
 
       - name: Run Labeler
         uses: crazy-max/ghaction-github-labeler@v3.1.1

.github/workflows/pre-release.yml

@@ -10,12 +10,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v2.4.0
+        uses: actions/checkout@v3
         with:
           fetch-depth: 2
 
       - name: Set up Python
-        uses: actions/setup-python@v2.3.1
+        uses: actions/setup-python@v3.1.2
         with:
           python-version: "3.10"
 
@@ -35,7 +35,7 @@ jobs:
 
       - name: Publish package on TestPyPI
         if: "! steps.check-version.outputs.tag"
-        uses: pypa/gh-action-pypi-publish@v1.4.2
+        uses: pypa/gh-action-pypi-publish@v1.5.0
         with:
           user: __token__
           password: ${{ secrets.TEST_PYPI_TOKEN }}

.github/workflows/release.yml

@@ -10,12 +10,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v2.4.0
+        uses: actions/checkout@v3
         with:
           fetch-depth: 2
 
       - name: Set up Python
-        uses: actions/setup-python@v2.3.1
+        uses: actions/setup-python@v3.1.2
         with:
           python-version: "3.10"
 
@@ -34,7 +34,7 @@ jobs:
           poetry build --ansi
 
       - name: Publish package on PyPI
-        uses: pypa/gh-action-pypi-publish@v1.4.2
+        uses: pypa/gh-action-pypi-publish@v1.5.0
         with:
           user: __token__
           password: ${{ secrets.PYPI_TOKEN }}

.github/workflows/tests.yml

@@ -35,10 +35,10 @@ jobs:
 
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v2.4.0
+        uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python }}
-        uses: actions/setup-python@v2.3.1
+        uses: actions/setup-python@v3.1.2
         with:
           python-version: ${{ matrix.python }}
 
@@ -83,7 +83,7 @@ jobs:
           print("::set-output name=result::{}".format(result))
 
       - name: Restore pre-commit cache
-        uses: actions/cache@v2.1.7
+        uses: actions/cache@v3.0.2
         if: matrix.session == 'pre-commit'
         with:
           path: ~/.cache/pre-commit
@@ -97,14 +97,14 @@ jobs:
 
       - name: Upload coverage data
         if: always() && matrix.session == 'tests'
-        uses: "actions/upload-artifact@v2.3.1"
+        uses: "actions/upload-artifact@v3"
         with:
           name: coverage-data
           path: ".coverage.*"
 
       - name: Upload documentation
         if: matrix.session == 'docs-build'
-        uses: actions/upload-artifact@v2.3.1
+        uses: actions/upload-artifact@v3
         with:
           name: docs
           path: docs/_build
@@ -114,10 +114,10 @@ jobs:
     needs: tests
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v2.4.0
+        uses: actions/checkout@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v2.3.1
+        uses: actions/setup-python@v3.1.2
         with:
           python-version: "3.10"
 
@@ -138,7 +138,7 @@ jobs:
           nox --version
 
       - name: Download coverage data
-        uses: actions/download-artifact@v2.1.0
+        uses: actions/download-artifact@v3
         with:
           name: coverage-data
 
@@ -151,4 +151,4 @@ jobs:
           nox --force-color --session=coverage -- xml
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@v2.1.0
+        uses: codecov/codecov-action@v3.1.0

.gitignore

@@ -8,3 +8,4 @@
 /docs/_build/
 /src/*.egg-info/
 __pycache__/
+.vscode

.vscode/settings.json

@@ -1,3 +0,0 @@
-{
-  "python.pythonPath": "/home/andrew/.pyenv/versions/3.10.0/envs/healthchecks/bin/python"
-}

README.rst

@@ -7,16 +7,16 @@ Py Healthchecks.Io
 
 |pre-commit| |Black|
 
-.. |PyPI| image:: https://img.shields.io/pypi/v/py-healthchecksio.svg
+.. |PyPI| image:: https://img.shields.io/pypi/v/healthchecks-io.svg
-   :target: https://pypi.org/project/py-healthchecksio/
+   :target: https://pypi.org/project/healthchecks-io/
    :alt: PyPI
-.. |Status| image:: https://img.shields.io/pypi/status/py-healthchecksio.svg
+.. |Status| image:: https://img.shields.io/pypi/status/healthchecks-io.svg
-   :target: https://pypi.org/project/py-healthchecksio/
+   :target: https://pypi.org/project/healthchecks-io/
    :alt: Status
-.. |Python Version| image:: https://img.shields.io/pypi/pyversions/py-healthchecksio
+.. |Python Version| image:: https://img.shields.io/pypi/pyversions/healthchecks-io
-   :target: https://pypi.org/project/py-healthchecksio
+   :target: https://pypi.org/project/healthchecks-io
    :alt: Python Version
-.. |License| image:: https://img.shields.io/pypi/l/py-healthchecks.io
+.. |License| image:: https://img.shields.io/pypi/l/healthchecks-io
    :target: https://opensource.org/licenses/MIT
    :alt: License
 .. |Read the Docs| image:: https://img.shields.io/readthedocs/py-healthchecksio/latest.svg?label=Read%20the%20Docs

docs/requirements.txt

@@ -1,3 +1,3 @@
-furo==2021.11.23
+furo==2022.4.7
-sphinx==4.3.1
+sphinx==4.5.0
-sphinx-click==3.0.2
+sphinx-click==4.0.3

docs/usage.rst

@@ -3,6 +3,31 @@ Usage
 
 This package implements the Healthchecks.io Management and Ping APIs as documented here https://healthchecks.io/docs/api/.
 
+Context Manager
+---------------
+
+Either the Client or AsyncClient can be used as a ContextManager (or Async Context Manager)
+
+.. code-block:: python
+
+    from healthchecks_io import Client, CheckCreate
+
+    with Client(api_key="myapikey") as client:
+        check = client.create_check(CheckCreate(name="New Check", tags="tag1 tag2"))
+    print(check)
+
+This is probably the easiest way to use the Clients for one-off scripts. If you do not need to keep a client open for multiple requests, just use
+the context manager.
+
+.. note::
+    When using either of the client types as a context manager, the httpx client underlying the client will be closed when the context manager exits.
+
+    Since we allow you to pass in a client on creation, its possible to use a shared client with this library. If you then use the client as a contextmanager,
+    it will close that shared client.
+
+    Just a thing to be aware of!
+
+
 Sync
 ----
 
@@ -38,7 +63,7 @@ Creating a new Check
 
     client = Client(api_key="myapikey")
 
-    check = client.create_check(CreateCheck(name="New Check", tags="tag1 tag2")
+    check = client.create_check(CheckCreate(name="New Check", tags="tag1 tag2"))
     print(check)
 
 Getting a Check
@@ -57,6 +82,7 @@ Pinging a Check
 ^^^^^^^^^^^^^^^
 
 .. code-block:: python
+
     from healthchecks_io import Client
 
     client = Client(api_key="myapikey")
@@ -68,13 +94,54 @@ Async
 
 If you want to use the client in an async program, use AsyncClient instead of Client
 
+.. code-block:: python
 
+    import asyncio
+    from healthchecks_io import AsyncClient, CheckCreate
+
+    async def main():
+        client = AsyncClient(api_key="myapikey")
+
+        check = await client.create_check(CheckCreate(name="New Check", tags="tag1 tag2"))
+        print(check)
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+
+
+CheckTrap
+---------
+
+Ever wanted to run some code and wrape it in a healthcheck check without thinking about it?
+
+That's what CheckTrap is for.
 
 .. code-block:: python
 
-    from healthchecks_io import AsyncClient, CheckCreate
+    import asyncio
+    from healthchecks_io import Client, AsyncClient, CheckCreate, CheckTrap
 
-    client = AsyncClient(api_key="myapikey")
+    def run_my_thing_to_monitor():
+        pass
 
-    check = await client.create_check(CreateCheck(name="New Check", tags="tag1 tag2")
+    async def main(check):
-    print(check)
+        client = AsyncClient(ping_key="ping_key")
+
+        # works with async too, and the ping api and slugs
+        async with CheckTrap(client, slug=check.slug) as ct:
+            # when entering the context manager, sends a start ping to your check
+            # Add custom logs to what gets sent to healthchecks. Reminder, only the first 10k bytes get saved
+            ct.add_log("My custom log message")
+            run_my_thing_to_monitor()
+
+    if __name__ == "__main__":
+        client = Client(api_key="myapikey")
+
+        # create a new check, or use an existing one already with just its uuid.
+        check = await client.create_check(CreateCheck(name="New Check", tags="tag1 tag2")
+
+        with CheckTrap(client, check.uuid):
+            # when entering the context manager, sends a start ping to your check
+            run_my_thing_to_monitor()
+
+        asyncio.run(main())

pyproject.toml

@@ -19,41 +19,41 @@ Changelog = "https://github.com/andrewthetechie/py-healthchecks.io/releases"
 python = "^3.7"
 click = "^8.0.1"
 pydantic = "^1.8.2"
-httpx = "^0.21.1"
+httpx = ">=0.21.1,<0.24.0"
 croniter = "^1.1.0"
-pytz = "^2021.3"
+pytz = ">=2021.3,<2023.0"
 
 [tool.poetry.dev-dependencies]
-pytest = "^6.2.5"
+pytest = "^7.1.2"
-coverage = {extras = ["toml"], version = "^6.2"}
+coverage = {extras = ["toml"], version = "^6.4"}
 safety = "^1.10.3"
-mypy = "^0.910"
+mypy = "^0.960"
 typeguard = "^2.13.2"
-xdoctest = {extras = ["colors"], version = "^0.15.10"}
+xdoctest = {extras = ["colors"], version = "^1.0.0"}
-sphinx = "^4.3.1"
+sphinx = "^4.3.2"
 sphinx-autobuild = ">=2021.3.14"
-pre-commit = "^2.16.0"
+pre-commit = "^2.19.0"
 flake8 = "^4.0.1"
 black = ">=21.10b0"
-flake8-bandit = "^2.1.2"
+flake8-bandit = "^3.0.0"
 flake8-bugbear = ">=21.9.2"
 flake8-docstrings = "^1.6.0"
 flake8-rst-docstrings = "^0.2.3"
 pep8-naming = "^0.12.1"
 darglint = "^1.8.1"
-reorder-python-imports = "^2.6.0"
+reorder-python-imports = "^3.1.0"
-pre-commit-hooks = "^4.0.1"
+pre-commit-hooks = "^4.2.0"
-sphinx-click = "^3.0.2"
+sphinx-click = "^4.0.3"
-Pygments = "^2.10.0"
+Pygments = "^2.12.0"
-pyupgrade = "^2.29.1"
+pyupgrade = "^2.32.1"
 furo = ">=2021.11.12"
 pytest-cov = "^3.0.0"
-types-croniter = "^1.0.3"
+types-croniter = "^1.0.10"
-types-pytz = "^2021.3.3"
+types-pytz = "^2021.3.8"
 pytest_async = "^0.1.1"
-pytest-asyncio = "^0.16.0"
+pytest-asyncio = "^0.18.3"
-respx = "^0.19.0"
+respx = "^0.19.2"
-pytest-mock = "^3.6.1"
+pytest-mock = "^3.7.0"
 pytest-lazy-fixture = "^0.6.3"
 
 [tool.coverage.paths]

src/healthchecks_io/__init__.py

@@ -4,18 +4,22 @@ __version__ = "0.0.0"  # noqa: E402
 
 from .client import AsyncClient  # noqa: F401, E402
 from .client import Client  # noqa: F401, E402
+from .client import CheckTrap  # noqa: F401, E402
 from .client.exceptions import BadAPIRequestError  # noqa: F401, E402
 from .client.exceptions import CheckNotFoundError  # noqa: F401, E402
 from .client.exceptions import HCAPIAuthError  # noqa: F401, E402
 from .client.exceptions import HCAPIError  # noqa: F401, E402
 from .client.exceptions import HCAPIRateLimitError  # noqa: F401, E402
 from .client.exceptions import NonUniqueSlugError  # noqa: F401, E402
+from .client.exceptions import WrongClientError  # noqa: F401, E402
+from .client.exceptions import PingFailedError  # noqa: F401, E402
 from .schemas import Check, CheckCreate, CheckPings, CheckStatuses  # noqa: F401, E402
 from .schemas import Integration, Badges, CheckUpdate  # noqa: F401, E402
 
 __all__ = [
     "AsyncClient",
     "Client",
+    "CheckTrap",
     "BadAPIRequestError",
     "CheckNotFoundError",
     "HCAPIAuthError",
@@ -23,6 +27,8 @@ __all__ = [
     "CheckNotFoundError",
     "HCAPIRateLimitError",
     "NonUniqueSlugError",
+    "WrongClientError",
+    "PingFailedError",
     "Check",
     "CheckCreate",
     "CheckUpdate",

src/healthchecks_io/client/__init__.py

@@ -1,5 +1,6 @@
 """healthchecks_io clients."""
 from .async_client import AsyncClient  # noqa: F401
+from .check_trap import CheckTrap  # noqa: F401
 from .sync_client import Client  # noqa: F401
 
-__all__ = ["AsyncClient", "Client"]
+__all__ = ["AsyncClient", "Client", "CheckTrap"]

src/healthchecks_io/client/async_client.py

@@ -1,9 +1,11 @@
 """An async healthchecks.io client."""
 import asyncio
+from types import TracebackType
 from typing import Dict
 from typing import List
 from typing import Optional
 from typing import Tuple
+from typing import Type
 
 from httpx import AsyncClient as HTTPXAsyncClient
 
@@ -56,6 +58,23 @@ class AsyncClient(AbstractClient):
         ] = f"py-healthchecks.io-async/{client_version}"
         self._client.headers["Content-type"] = "application/json"
 
+    async def __aenter__(self) -> "AsyncClient":
+        """Context manager entrance.
+
+        Returns:
+            AsyncClient: returns this client as a context manager
+        """
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        """Context manager exit."""
+        await self._afinalizer_method()
+
     def _finalizer_method(self) -> None:
         """Calls _afinalizer_method from a sync context to work with weakref.finalizer."""
         asyncio.run(self._afinalizer_method())
@@ -79,7 +98,7 @@ class AsyncClient(AbstractClient):
         """
         request_url = self._get_api_request_url("checks/")
         response = self.check_response(
-            await self._client.post(request_url, json=new_check.dict())
+            await self._client.post(request_url, json=new_check.dict(exclude_none=True))
         )
         return Check.from_api_result(response.json())
 
@@ -99,7 +118,8 @@ class AsyncClient(AbstractClient):
         request_url = self._get_api_request_url(f"checks/{uuid}")
         response = self.check_response(
             await self._client.post(
-                request_url, json=update_check.dict(exclude_unset=True)
+                request_url,
+                json=update_check.dict(exclude_unset=True, exclude_none=True),
             )
         )
         return Check.from_api_result(response.json())
@@ -322,7 +342,9 @@ class AsyncClient(AbstractClient):
             for key, item in response.json()["badges"].items()
         }
 
-    async def success_ping(self, uuid: str = "", slug: str = "") -> Tuple[bool, str]:
+    async def success_ping(
+        self, uuid: str = "", slug: str = "", data: str = ""
+    ) -> Tuple[bool, str]:
         """Signals to Healthchecks.io that a job has completed successfully.
 
         Can also be used to indicate a continuously running process is still running and healthy.
@@ -338,6 +360,7 @@ class AsyncClient(AbstractClient):
         Args:
             uuid (str): Check's UUID. Defaults to "".
             slug (str):  Check's Slug. Defaults to "".
+            data (str): Text data to append to this check. Defaults to "".
 
         Raises:
             HCAPIAuthError: Raised when status_code == 401 or 403
@@ -352,10 +375,14 @@ class AsyncClient(AbstractClient):
             Tuple[bool, str]: success (true or false) and the response text
         """
         ping_url = self._get_ping_url(uuid, slug, "")
-        response = self.check_ping_response(await self._client.get(ping_url))
+        response = self.check_ping_response(
+            await self._client.post(ping_url, content=data)
+        )
         return (True if response.status_code == 200 else False, response.text)
 
-    async def start_ping(self, uuid: str = "", slug: str = "") -> Tuple[bool, str]:
+    async def start_ping(
+        self, uuid: str = "", slug: str = "", data: str = ""
+    ) -> Tuple[bool, str]:
         """Sends a "job has started!" message to Healthchecks.io.
 
         Sending a "start" signal is optional, but it enables a few extra features:
@@ -373,6 +400,7 @@ class AsyncClient(AbstractClient):
         Args:
             uuid (str): Check's UUID. Defaults to "".
             slug (str): Check's Slug. Defaults to "".
+            data (str): Text data to append to this check. Defaults to "".
 
         Raises:
             HCAPIAuthError: Raised when status_code == 401 or 403
@@ -387,10 +415,14 @@ class AsyncClient(AbstractClient):
             Tuple[bool, str]: success (true or false) and the response text
         """
         ping_url = self._get_ping_url(uuid, slug, "/start")
-        response = self.check_ping_response(await self._client.get(ping_url))
+        response = self.check_ping_response(
+            await self._client.post(ping_url, content=data)
+        )
         return (True if response.status_code == 200 else False, response.text)
 
-    async def fail_ping(self, uuid: str = "", slug: str = "") -> Tuple[bool, str]:
+    async def fail_ping(
+        self, uuid: str = "", slug: str = "", data: str = ""
+    ) -> Tuple[bool, str]:
         """Signals to Healthchecks.io that the job has failed.
 
         Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert.
@@ -406,6 +438,7 @@ class AsyncClient(AbstractClient):
         Args:
             uuid (str): Check's UUID. Defaults to "".
             slug (str): Check's Slug. Defaults to "".
+            data (str): Text data to append to this check. Defaults to "".
 
         Raises:
             HCAPIAuthError: Raised when status_code == 401 or 403
@@ -420,11 +453,13 @@ class AsyncClient(AbstractClient):
             Tuple[bool, str]: success (true or false) and the response text
         """
         ping_url = self._get_ping_url(uuid, slug, "/fail")
-        response = self.check_ping_response(await self._client.get(ping_url))
+        response = self.check_ping_response(
+            await self._client.post(ping_url, content=data)
+        )
         return (True if response.status_code == 200 else False, response.text)
 
     async def exit_code_ping(
-        self, exit_code: int, uuid: str = "", slug: str = ""
+        self, exit_code: int, uuid: str = "", slug: str = "", data: str = ""
     ) -> Tuple[bool, str]:
         """Signals to Healthchecks.io that the job has failed.
 
@@ -442,6 +477,7 @@ class AsyncClient(AbstractClient):
             exit_code (int): Exit code to sent, int from 0 to 255
             uuid (str): Check's UUID. Defaults to "".
             slug (str): Check's Slug. Defaults to "".
+            data (str): Text data to append to this check. Defaults to "".
 
         Raises:
             HCAPIAuthError: Raised when status_code == 401 or 403
@@ -456,5 +492,7 @@ class AsyncClient(AbstractClient):
             Tuple[bool, str]: success (true or false) and the response text
         """
         ping_url = self._get_ping_url(uuid, slug, f"/{exit_code}")
-        response = self.check_ping_response(await self._client.get(ping_url))
+        response = self.check_ping_response(
+            await self._client.post(ping_url, content=data)
+        )
         return (True if response.status_code == 200 else False, response.text)

src/healthchecks_io/client/check_trap.py

@@ -0,0 +1,166 @@
+"""CheckTrap is a context manager to wrap around python code to communicate results to a Healthchecks check."""
+from types import TracebackType
+from typing import List
+from typing import Optional
+from typing import Type
+from typing import Union
+
+from .async_client import AsyncClient
+from .exceptions import PingFailedError
+from .exceptions import WrongClientError
+from .sync_client import Client
+
+
+class CheckTrap:
+    """CheckTrap is a context manager to wrap around python code to communicate results to a Healthchecks check."""
+
+    def __init__(
+        self,
+        client: Union[Client, AsyncClient],
+        uuid: str = "",
+        slug: str = "",
+        suppress_exceptions: bool = False,
+    ) -> None:
+        """A context manager to wrap around python code to communicate results to a Healthchecks check.
+
+        Args:
+            client (Union[Client, AsyncClient]): healthchecks_io client, async or sync
+            uuid (str): uuid of the check. Defaults to "".
+            slug (str): slug of the check, exclusion wiht uuid. Defaults to "".
+            suppress_exceptions (bool): If true, do not raise any exceptions. Defaults to False.
+
+        Raises:
+            Exception: Raised if a slug and a uuid is passed
+        """
+        if uuid == "" and slug == "":
+            raise Exception("Must pass a slug or an uuid")
+        self.client: Union[Client, AsyncClient] = client
+        self.uuid: str = uuid
+        self.slug: str = slug
+        self.log_lines: List[str] = list()
+        self.suppress_exceptions: bool = suppress_exceptions
+
+    def add_log(self, line: str) -> None:
+        """Add a line to the context manager's log that is sent with the check.
+
+        Args:
+            line (str): String to add to the logs
+        """
+        self.log_lines.append(line)
+
+    def __enter__(self) -> "CheckTrap":
+        """Enter the context manager.
+
+        Sends a start ping to the check represented by self.uuid or self.slug.
+
+        Raises:
+            WrongClientError: Raised when using an AsyncClient with this as a sync client manager
+            PingFailedError: When a ping fails for any reason not handled by a custom exception
+            HCAPIAuthError: Raised when status_code == 401 or 403
+            HCAPIError: Raised when status_code is 5xx
+            CheckNotFoundError: Raised when status_code is 404 or response text has "not found" in it
+            BadAPIRequestError: Raised when status_code is 400, or if you pass a uuid and a slug, or if
+                pinging by a slug and do not have a ping key set
+            HCAPIRateLimitError: Raised when status code is 429 or response text has "rate limited" in it
+            NonUniqueSlugError: Raused when status code is 409.
+
+        Returns:
+            CheckTrap: self
+        """
+        if isinstance(self.client, AsyncClient):
+            raise WrongClientError(
+                "You passed an AsyncClient, use this as an async context manager"
+            )
+        result = self.client.start_ping(uuid=self.uuid, slug=self.slug)
+        if not result[0]:
+            raise PingFailedError(result[1])
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> Optional[bool]:
+        """Exit the context manager.
+
+        If there is an exception, add it to any log lines and send a fail ping.
+        Otherwise, send a success ping with any log lines appended.
+
+        Args:
+            exc_type (Optional[Type[BaseException]]): [description]
+            exc (Optional[BaseException]): [description]
+            traceback (Optional[TracebackType]): [description]
+
+        Returns:
+            Optional[bool]: self.suppress_exceptions, if true will not raise any exceptions
+        """
+        if exc_type is None:
+            self.client.success_ping(
+                self.uuid, self.slug, data="\n".join(self.log_lines)
+            )
+        else:
+            self.add_log(str(exc))
+            self.add_log(str(traceback))
+            self.client.fail_ping(self.uuid, self.slug, data="\n".join(self.log_lines))
+        return self.suppress_exceptions
+
+    async def __aenter__(self) -> "CheckTrap":
+        """Enter the context manager.
+
+        Sends a start ping to the check represented by self.uuid or self.slug.
+
+        Raises:
+            WrongClientError: Raised when using an AsyncClient with this as a sync client manager
+            PingFailedError: When a ping fails for any reason not handled by a custom exception
+            HCAPIAuthError: Raised when status_code == 401 or 403
+            HCAPIError: Raised when status_code is 5xx
+            CheckNotFoundError: Raised when status_code is 404 or response text has "not found" in it
+            BadAPIRequestError: Raised when status_code is 400, or if you pass a uuid and a slug, or if
+                pinging by a slug and do not have a ping key set
+            HCAPIRateLimitError: Raised when status code is 429 or response text has "rate limited" in it
+            NonUniqueSlugError: Raused when status code is 409.
+
+        Returns:
+            CheckTrap: self
+        """
+        if isinstance(self.client, Client):
+            raise WrongClientError(
+                "You passed a sync Client, use this as a regular context manager"
+            )
+        result = await self.client.start_ping(self.uuid, self.slug)
+        if not result[0]:
+            raise PingFailedError(result[1])
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> Optional[bool]:
+        """Exit the context manager.
+
+        If there is an exception, add it to any log lines and send a fail ping.
+        Otherwise, send a success ping with any log lines appended.
+
+        Args:
+            exc_type (Optional[Type[BaseException]]): [description]
+            exc (Optional[BaseException]): [description]
+            traceback (Optional[TracebackType]): [description]
+
+        Returns:
+            Optional[bool]: self.suppress_exceptions, if true will not raise any exceptions
+        """
+        if exc_type is None:
+            # ignore typing, if we've gotten here we know its an async client
+            await self.client.success_ping(  # type: ignore
+                self.uuid, self.slug, data="\n".join(self.log_lines)
+            )
+        else:
+            self.add_log(str(exc))
+            self.add_log(str(traceback))
+            await self.client.fail_ping(  # type: ignore
+                self.uuid, self.slug, data="\n".join(self.log_lines)
+            )
+        return self.suppress_exceptions

src/healthchecks_io/client/exceptions.py

@@ -35,3 +35,15 @@ class NonUniqueSlugError(HCAPIError):
     """Thrown when the api returns a 409 when pinging."""
 
     ...
+
+
+class WrongClientError(HCAPIError):
+    """Thrown when trying to use a CheckTrap with the wrong client type."""
+
+    ...
+
+
+class PingFailedError(HCAPIError):
+    """Thrown when a ping fails."""
+
+    ...

src/healthchecks_io/client/sync_client.py

@@ -1,8 +1,10 @@
 """An async healthchecks.io client."""
+from types import TracebackType
 from typing import Dict
 from typing import List
 from typing import Optional
 from typing import Tuple
+from typing import Type
 
 from httpx import Client as HTTPXClient
 
@@ -50,6 +52,23 @@ class Client(AbstractClient):
         self._client.headers["user-agent"] = f"py-healthchecks.io/{client_version}"
         self._client.headers["Content-type"] = "application/json"
 
+    def __enter__(self) -> "Client":
+        """Context manager entrance.
+
+        Returns:
+            Client: returns this client as a context manager
+        """
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        """Context manager exit."""
+        self._finalizer_method()
+
     def _finalizer_method(self) -> None:
         """Closes the httpx client."""
         self._client.close()
@@ -119,7 +138,7 @@ class Client(AbstractClient):
         """
         request_url = self._get_api_request_url("checks/")
         response = self.check_response(
-            self._client.post(request_url, json=new_check.dict())
+            self._client.post(request_url, json=new_check.dict(exclude_none=True))
         )
         return Check.from_api_result(response.json())
 
@@ -144,7 +163,10 @@ class Client(AbstractClient):
         """
         request_url = self._get_api_request_url(f"checks/{uuid}")
         response = self.check_response(
-            self._client.post(request_url, json=update_check.dict(exclude_unset=True))
+            self._client.post(
+                request_url,
+                json=update_check.dict(exclude_unset=True, exclude_none=True),
+            )
         )
         return Check.from_api_result(response.json())
 
@@ -305,7 +327,9 @@ class Client(AbstractClient):
             for key, item in response.json()["badges"].items()
         }
 
-    def success_ping(self, uuid: str = "", slug: str = "") -> Tuple[bool, str]:
+    def success_ping(
+        self, uuid: str = "", slug: str = "", data: str = ""
+    ) -> Tuple[bool, str]:
         """Signals to Healthchecks.io that a job has completed successfully.
 
         Can also be used to indicate a continuously running process is still running and healthy.
@@ -321,6 +345,7 @@ class Client(AbstractClient):
         Args:
             uuid (str): Check's UUID. Defaults to "".
             slug (str): Check's Slug. Defaults to "".
+            data (str): Text data to append to this check. Defaults to ""
 
         Raises:
             HCAPIAuthError: Raised when status_code == 401 or 403
@@ -335,10 +360,12 @@ class Client(AbstractClient):
             Tuple[bool, str]: success (true or false) and the response text
         """
         ping_url = self._get_ping_url(uuid, slug, "")
-        response = self.check_ping_response(self._client.get(ping_url))
+        response = self.check_ping_response(self._client.post(ping_url, content=data))
         return (True if response.status_code == 200 else False, response.text)
 
-    def start_ping(self, uuid: str = "", slug: str = "") -> Tuple[bool, str]:
+    def start_ping(
+        self, uuid: str = "", slug: str = "", data: str = ""
+    ) -> Tuple[bool, str]:
         """Sends a "job has started!" message to Healthchecks.io.
 
         Sending a "start" signal is optional, but it enables a few extra features:
@@ -356,6 +383,7 @@ class Client(AbstractClient):
         Args:
             uuid (str): Check's UUID. Defaults to "".
             slug (str): Check's Slug. Defaults to "".
+            data (str): Text data to append to this check. Defaults to ""
 
         Raises:
             HCAPIAuthError: Raised when status_code == 401 or 403
@@ -370,10 +398,12 @@ class Client(AbstractClient):
             Tuple[bool, str]: success (true or false) and the response text
         """
         ping_url = self._get_ping_url(uuid, slug, "/start")
-        response = self.check_ping_response(self._client.get(ping_url))
+        response = self.check_ping_response(self._client.post(ping_url, content=data))
         return (True if response.status_code == 200 else False, response.text)
 
-    def fail_ping(self, uuid: str = "", slug: str = "") -> Tuple[bool, str]:
+    def fail_ping(
+        self, uuid: str = "", slug: str = "", data: str = ""
+    ) -> Tuple[bool, str]:
         """Signals to Healthchecks.io that the job has failed.
 
         Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert.
@@ -389,6 +419,7 @@ class Client(AbstractClient):
         Args:
             uuid (str): Check's UUID. Defaults to "".
             slug (str): Check's Slug. Defaults to "".
+            data (str): Text data to append to this check. Defaults to ""
 
         Raises:
             HCAPIAuthError: Raised when status_code == 401 or 403
@@ -403,11 +434,11 @@ class Client(AbstractClient):
             Tuple[bool, str]: success (true or false) and the response text
         """
         ping_url = self._get_ping_url(uuid, slug, "/fail")
-        response = self.check_ping_response(self._client.get(ping_url))
+        response = self.check_ping_response(self._client.post(ping_url, content=data))
         return (True if response.status_code == 200 else False, response.text)
 
     def exit_code_ping(
-        self, exit_code: int, uuid: str = "", slug: str = ""
+        self, exit_code: int, uuid: str = "", slug: str = "", data: str = ""
     ) -> Tuple[bool, str]:
         """Signals to Healthchecks.io that the job has failed.
 
@@ -425,6 +456,7 @@ class Client(AbstractClient):
             exit_code (int): Exit code to sent, int from 0 to 255
             uuid (str): Check's UUID. Defaults to "".
             slug (str): Check's Slug. Defaults to "".
+            data (str): Text data to append to this check. Defaults to ""
 
         Raises:
             HCAPIAuthError: Raised when status_code == 401 or 403
@@ -439,5 +471,5 @@ class Client(AbstractClient):
             Tuple[bool, str]: success (true or false) and the response text
         """
         ping_url = self._get_ping_url(uuid, slug, f"/{exit_code}")
-        response = self.check_ping_response(self._client.get(ping_url))
+        response = self.check_ping_response(self._client.post(ping_url, content=data))
         return (True if response.status_code == 200 else False, response.text)

src/healthchecks_io/schemas/checks.py

@@ -38,7 +38,7 @@ class Check(BaseModel):
     update_url: Optional[str]
     pause_url: Optional[str]
     channels: Optional[str]
-    timeout: int
+    timeout: Optional[int]
     uuid: Optional[str]
 
     @validator("uuid", always=True)
@@ -65,11 +65,11 @@ class Check(BaseModel):
 class CheckCreate(BaseModel):
     """Pydantic object for creating a check."""
 
-    name: Optional[str] = Field(..., description="Name of the check")
+    name: Optional[str] = Field("", description="Name of the check")
     tags: Optional[str] = Field(
-        ..., description="String separated list of tags to apply"
+        "", description="String separated list of tags to apply"
     )
-    desc: Optional[str] = Field(..., description="Description of the check")
+    desc: Optional[str] = Field("", description="Description of the check")
     timeout: Optional[int] = Field(
         86400,
         description="The expected period of this check in seconds.",
@@ -83,7 +83,7 @@ class CheckCreate(BaseModel):
         lte=31536000,
     )
     schedule: Optional[str] = Field(
-        "* * * * *",
+        None,
         description="A cron expression defining this check's schedule. "
         "If you specify both timeout and schedule parameters, "
         "Healthchecks.io will create a Cron check and ignore the "

tests/client/test_async.py

@@ -14,6 +14,42 @@ from healthchecks_io.client.exceptions import HCAPIAuthError
 from healthchecks_io.client.exceptions import HCAPIError
 
 
+@pytest.mark.asyncio
+@pytest.mark.respx
+async def test_acreate_check_200_context_manager(
+    fake_check_api_result, respx_mock, test_async_client
+):
+    checks_url = urljoin(test_async_client._api_url, "checks/")
+    respx_mock.post(checks_url).mock(
+        return_value=Response(
+            status_code=200,
+            json={
+                "channels": "",
+                "desc": "",
+                "grace": 60,
+                "last_ping": None,
+                "n_pings": 0,
+                "name": "Backups",
+                "slug": "backups",
+                "next_ping": None,
+                "manual_resume": False,
+                "methods": "",
+                "pause_url": "https://healthchecks.io/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
+                "ping_url": "https://hc-ping.com/f618072a-7bde-4eee-af63-71a77c5723bc",
+                "status": "new",
+                "tags": "prod www",
+                "timeout": 3600,
+                "update_url": "https://healthchecks.io/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
+            },
+        )
+    )
+    async with test_async_client as test_client:
+        check = await test_client.create_check(
+            CheckCreate(name="test", tags="test", desc="test")
+        )
+    assert check.name == "Backups"
+
+
 @pytest.mark.asyncio
 @pytest.mark.respx
 async def test_acreate_check_200(fake_check_api_result, respx_mock, test_async_client):
@@ -357,9 +393,9 @@ ping_test_parameters = [
 @pytest.mark.parametrize(
     "respx_mocker, tc, url, ping_method, method_kwargs", ping_test_parameters
 )
-async def test_success_ping(respx_mocker, tc, url, ping_method, method_kwargs):
+async def test_asuccess_ping(respx_mocker, tc, url, ping_method, method_kwargs):
     channels_url = urljoin(tc._ping_url, url)
-    respx_mocker.get(channels_url).mock(
+    respx_mocker.post(channels_url).mock(
         return_value=Response(status_code=200, text="OK")
     )
     ping_method = getattr(tc, ping_method)

tests/client/test_check_trap.py

@@ -0,0 +1,97 @@
+from urllib.parse import urljoin
+
+import pytest
+import respx
+from httpx import Client as HTTPXClient
+from httpx import Response
+
+from healthchecks_io import CheckCreate
+from healthchecks_io import CheckTrap
+from healthchecks_io import CheckUpdate
+from healthchecks_io import PingFailedError
+from healthchecks_io import WrongClientError
+
+
+@pytest.mark.respx
+def test_check_trap_sync(respx_mock, test_client):
+    start_url = urljoin(test_client._ping_url, "test/start")
+    respx_mock.post(start_url).mock(return_value=Response(status_code=200, text="OK"))
+    success_url = urljoin(test_client._ping_url, "test")
+    respx_mock.post(success_url).mock(return_value=Response(status_code=200, text="OK"))
+
+    with CheckTrap(test_client, uuid="test") as ct:
+        pass
+
+
+@pytest.mark.respx
+def test_check_trap_sync_failed_ping(respx_mock, test_client):
+    start_url = urljoin(test_client._ping_url, "test/start")
+    respx_mock.post(start_url).mock(return_value=Response(status_code=444, text="OK"))
+    with pytest.raises(PingFailedError):
+        with CheckTrap(test_client, uuid="test") as ct:
+            pass
+
+
+@pytest.mark.respx
+def test_check_trap_sync_exception(respx_mock, test_client):
+    start_url = urljoin(test_client._ping_url, "test/start")
+    respx_mock.post(start_url).mock(return_value=Response(status_code=200, text="OK"))
+    fail_url = urljoin(test_client._ping_url, "test/fail")
+    respx_mock.post(fail_url).mock(return_value=Response(status_code=200, text="OK"))
+    with pytest.raises(Exception):
+        with CheckTrap(test_client, uuid="test") as ct:
+            raise Exception("Exception")
+
+
+@pytest.mark.asyncio
+@pytest.mark.respx
+async def test_check_trap_async(respx_mock, test_async_client):
+    start_url = urljoin(test_async_client._ping_url, "test/start")
+    respx_mock.post(start_url).mock(return_value=Response(status_code=200, text="OK"))
+    success_url = urljoin(test_async_client._ping_url, "test")
+    respx_mock.post(success_url).mock(return_value=Response(status_code=200, text="OK"))
+
+    async with CheckTrap(test_async_client, uuid="test") as ct:
+        pass
+
+
+@pytest.mark.asyncio
+@pytest.mark.respx
+async def test_check_trap_async_failed_ping(respx_mock, test_async_client):
+    start_url = urljoin(test_async_client._ping_url, "test/start")
+    respx_mock.post(start_url).mock(return_value=Response(status_code=444, text="OK"))
+    with pytest.raises(PingFailedError):
+        async with CheckTrap(test_async_client, uuid="test") as ct:
+            pass
+
+
+@pytest.mark.asyncio
+@pytest.mark.respx
+async def test_check_trap_async_exception(respx_mock, test_async_client):
+    start_url = urljoin(test_async_client._ping_url, "test/start")
+    respx_mock.post(start_url).mock(return_value=Response(status_code=200, text="OK"))
+    fail_url = urljoin(test_async_client._ping_url, "test/fail")
+    respx_mock.post(fail_url).mock(return_value=Response(status_code=200, text="OK"))
+
+    with pytest.raises(Exception):
+        async with CheckTrap(test_async_client, uuid="test") as ct:
+            raise Exception("Exception")
+
+
+@pytest.mark.asyncio
+async def test_check_trap_wrong_client_error(test_client, test_async_client):
+
+    with pytest.raises(WrongClientError):
+        async with CheckTrap(test_client, uuid="test") as ct:
+            pass
+
+    with pytest.raises(WrongClientError):
+        with CheckTrap(test_async_client, uuid="test") as ct:
+            pass
+
+
+def test_check_trap_no_uuid_or_slug(test_client):
+    with pytest.raises(Exception) as exc:
+        with CheckTrap(test_client):
+            pass
+        assert str(exc) == "Must pass a slug or an uuid"

tests/client/test_sync.py

@@ -14,6 +14,39 @@ from healthchecks_io.client.exceptions import HCAPIAuthError
 from healthchecks_io.client.exceptions import HCAPIError
 
 
+@pytest.mark.respx
+def test_create_check_200_context_manager(
+    fake_check_api_result, respx_mock, test_client
+):
+    checks_url = urljoin(test_client._api_url, "checks/")
+    respx_mock.post(checks_url).mock(
+        return_value=Response(
+            status_code=200,
+            json={
+                "channels": "",
+                "desc": "",
+                "grace": 60,
+                "last_ping": None,
+                "n_pings": 0,
+                "name": "Backups",
+                "slug": "backups",
+                "next_ping": None,
+                "manual_resume": False,
+                "methods": "",
+                "pause_url": "https://healthchecks.io/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pause",
+                "ping_url": "https://hc-ping.com/f618072a-7bde-4eee-af63-71a77c5723bc",
+                "status": "new",
+                "tags": "prod www",
+                "timeout": 3600,
+                "update_url": "https://healthchecks.io/api/v1/checks/f618072a-7bde-4eee-af63-71a77c5723bc",
+            },
+        )
+    )
+    with test_client as tc:
+        check = tc.create_check(CheckCreate(name="test", tags="test", desc="test"))
+    assert check.name == "Backups"
+
+
 @pytest.mark.respx
 def test_create_check_200(fake_check_api_result, respx_mock, test_client):
     checks_url = urljoin(test_client._api_url, "checks/")
@@ -325,7 +358,7 @@ ping_test_parameters = [
 )
 def test_success_ping(respx_mocker, tc, url, ping_method, method_kwargs):
     channels_url = urljoin(tc._ping_url, url)
-    respx_mocker.get(channels_url).mock(
+    respx_mocker.post(channels_url).mock(
         return_value=Response(status_code=200, text="OK")
     )
     ping_method = getattr(tc, ping_method)