feat: add app handler method, get_appdir()

docs/glossary.rst

@@ -25,6 +25,9 @@ Glossary
      Usually this is named ``app`` and is located at the root of the
      virtual environment.
 
+     Can be retrieved via
+     :meth:`~wuttjamaican.app.AppHandler.get_appdir()`.
+
    app enum
       Python module whose namespace contains all the "enum" values
       used by the :term:`app`.  Available on the :term:`app handler`

src/wuttjamaican/app.py

@@ -26,6 +26,7 @@ WuttJamaican - app handler
 
 import importlib
 import os
+import sys
 import warnings
 
 from wuttjamaican.util import (load_entry_points, load_object,
@@ -353,6 +354,54 @@ class AppHandler:
         """
         return load_object(spec)
 
+    def get_appdir(self, *args, **kwargs):
+        """
+        Returns path to the :term:`app dir`.
+
+        This does not check for existence of the path, it only reads
+        it from config or (optionally) provides a default path.
+
+        :param configured_only: Pass ``True`` here if you only want
+           the configured path and ignore the default path.
+
+        :param create: Pass ``True`` here if you want to ensure the
+           returned path exists, creating it if necessary.
+
+        :param \*args: Any additional args will be added as child
+           paths for the final value.
+
+        For instance, assuming ``/srv/envs/poser`` is the virtual
+        environment root::
+
+           app.get_appdir()             # => /srv/envs/poser/app
+
+           app.get_appdir('data')       # => /srv/envs/poser/app/data
+        """
+        configured_only = kwargs.pop('configured_only', False)
+        create = kwargs.pop('create', False)
+
+        # maybe specify default path
+        if not configured_only:
+            path = os.path.join(sys.prefix, 'app')
+            kwargs.setdefault('default', path)
+
+        # get configured path
+        kwargs.setdefault('usedb', False)
+        path = self.config.get(f'{self.appname}.appdir', **kwargs)
+
+        # add any subpath info
+        if path and args:
+            path = os.path.join(path, *args)
+
+        # create path if requested/needed
+        if create:
+            if not path:
+                raise ValueError("appdir path unknown! so cannot create it.")
+            if not os.path.exists(path):
+                os.makedirs(path)
+
+        return path
+
     def make_appdir(self, path, subfolders=None, **kwargs):
         """
         Establish an :term:`app dir` at the given path.

src/wuttjamaican/testing.py

@@ -97,3 +97,11 @@ class FileConfigTestCase(TestCase):
         with open(path, 'wt') as f:
             f.write(content)
         return path
+
+    def mkdir(self, dirname):
+        """
+        Make a new temporary folder and return its path.
+
+        Note that this will be created *underneath* :attr:`tempdir`.
+        """
+        return tempfile.mkdtemp(dir=self.tempdir)

tests/test_app.py

@@ -15,11 +15,13 @@ from wuttjamaican import app
 from wuttjamaican.progress import ProgressBase
 from wuttjamaican.conf import WuttaConfig
 from wuttjamaican.util import UNSPECIFIED
+from wuttjamaican.testing import FileConfigTestCase
 
 
-class TestAppHandler(TestCase):
+class TestAppHandler(FileConfigTestCase):
 
     def setUp(self):
+        self.setup_files()
         self.config = WuttaConfig(appname='wuttatest')
         self.app = app.AppHandler(self.config)
         self.config.app = self.app
@@ -39,6 +41,40 @@ class TestAppHandler(TestCase):
         obj = self.app.load_object('wuttjamaican.util:UNSPECIFIED')
         self.assertIs(obj, UNSPECIFIED)
 
+    def test_get_appdir(self):
+
+        mockdir = self.mkdir('mockdir')
+
+        # default appdir
+        with patch.object(sys, 'prefix', new=mockdir):
+
+            # default is returned by default
+            appdir = self.app.get_appdir()
+            self.assertEqual(appdir, os.path.join(mockdir, 'app'))
+
+            # but not if caller wants config only
+            appdir = self.app.get_appdir(configured_only=True)
+            self.assertIsNone(appdir)
+
+            # also, cannot create if appdir path not known
+            self.assertRaises(ValueError, self.app.get_appdir, configured_only=True, create=True)
+
+        # configured appdir
+        self.config.setdefault('wuttatest.appdir', mockdir)
+        appdir = self.app.get_appdir()
+        self.assertEqual(appdir, mockdir)
+
+        # appdir w/ subpath
+        appdir = self.app.get_appdir('foo', 'bar')
+        self.assertEqual(appdir, os.path.join(mockdir, 'foo', 'bar'))
+
+        # subpath is created
+        self.assertEqual(len(os.listdir(mockdir)), 0)
+        appdir = self.app.get_appdir('foo', 'bar', create=True)
+        self.assertEqual(appdir, os.path.join(mockdir, 'foo', 'bar'))
+        self.assertEqual(os.listdir(mockdir), ['foo'])
+        self.assertEqual(os.listdir(os.path.join(mockdir, 'foo')), ['bar'])
+
     def test_make_appdir(self):
 
         # appdir is created, and 3 subfolders added by default