From 4879887cb3db4504a66f6ff24f3a3e3f7889e868 Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@edbob.org>
Date: Thu, 12 Sep 2024 12:55:28 -0500
Subject: [PATCH] feat: add `util` module with `exists()` function

---
 docs/api/wuttamess.util.rst |  6 ++++++
 docs/index.rst              |  1 +
 src/wuttamess/util.py       | 32 ++++++++++++++++++++++++++++++++
 tests/test_util.py          | 14 ++++++++++++++
 4 files changed, 53 insertions(+)
 create mode 100644 docs/api/wuttamess.util.rst
 create mode 100644 src/wuttamess/util.py
 create mode 100644 tests/test_util.py

diff --git a/docs/api/wuttamess.util.rst b/docs/api/wuttamess.util.rst
new file mode 100644
index 0000000..e8813f6
--- /dev/null
+++ b/docs/api/wuttamess.util.rst
@@ -0,0 +1,6 @@
+
+``wuttamess.util``
+==================
+
+.. automodule:: wuttamess.util
+   :members:
diff --git a/docs/index.rst b/docs/index.rst
index 50e3061..78fc2d0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -33,3 +33,4 @@ project.
    api/wuttamess.apt
    api/wuttamess.postfix
    api/wuttamess.sync
+   api/wuttamess.util
diff --git a/src/wuttamess/util.py b/src/wuttamess/util.py
new file mode 100644
index 0000000..e8fb56a
--- /dev/null
+++ b/src/wuttamess/util.py
@@ -0,0 +1,32 @@
+# -*- coding: utf-8; -*-
+################################################################################
+#
+#  WuttaMess -- Fabric Automation Helpers
+#  Copyright © 2024 Lance Edgar
+#
+#  This file is part of Wutta Framework.
+#
+#  Wutta Framework is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU General Public License as published by the Free
+#  Software Foundation, either version 3 of the License, or (at your option) any
+#  later version.
+#
+#  Wutta Framework is distributed in the hope that it will be useful, but
+#  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+#  more details.
+#
+#  You should have received a copy of the GNU General Public License along with
+#  Wutta Framework.  If not, see <http://www.gnu.org/licenses/>.
+#
+################################################################################
+"""
+Misc. Utilities
+"""
+
+
+def exists(c, path):
+    """
+    Returns ``True`` if given path exists on the host, otherwise ``False``.
+    """
+    return not c.run(f'test -e {path}', warn=True).failed
diff --git a/tests/test_util.py b/tests/test_util.py
new file mode 100644
index 0000000..177e4cc
--- /dev/null
+++ b/tests/test_util.py
@@ -0,0 +1,14 @@
+# -*- coding: utf-8; -*-
+
+from unittest import TestCase
+from unittest.mock import MagicMock
+
+from wuttamess import util as mod
+
+
+class TestExists(TestCase):
+
+    def test_basic(self):
+        c = MagicMock()
+        mod.exists(c, '/foo')
+        c.run.assert_called_once_with('test -e /foo', warn=True)