Update configuration information

src/pystow/__init__.py

@@ -46,7 +46,7 @@
     open,
     open_gz,
 )
-from .config_api import get_config, write_config  # noqa
+from .config_api import ConfigError, get_config, write_config  # noqa
 from .impl import Module  # noqa
 from .utils import ensure_readme  # noqa
 

src/pystow/cli.py

@@ -8,8 +8,6 @@
 
 import click
 
-from . import api
-
 
 @click.group()
 def main():
@@ -21,13 +19,17 @@ def main():
 @click.option("--name")
 def join(keys: Sequence[str], name: Optional[str]):
     """List a directory."""
+    from . import api
+
     click.echo(api.join(*keys, name=name))
 
 
 @main.command()
 @click.argument("keys", nargs=-1)
 def ls(keys: Sequence[str]):
     """List a directory."""
+    from . import api
+
     directory = api.join(*keys)
     _ls(directory)
 
@@ -39,6 +41,8 @@ def ls(keys: Sequence[str]):
 @click.option("--force", is_flag=True)
 def ensure(keys: Sequence[str], url: str, name: Optional[str], force: bool):
     """Ensure a file is downloaded."""
+    from . import api
+
     path = api.ensure(*keys, url=url, name=name, force=force)
     _ls(path.parent)
 
@@ -49,5 +53,16 @@ def _ls(directory):
     os.system(command)  # noqa:S605
 
 
+@main.command(name="set")
+@click.argument("module")
+@click.argument("key")
+@click.argument("value")
+def set_config(module: str, key: str, value: str):
+    """Set a configuration value."""
+    from .config_api import write_config
+
+    write_config(module, key, value)
+
+
 if __name__ == "__main__":
     main()

src/pystow/config_api.py

@@ -36,13 +36,35 @@ def __init__(self, module: str, key: str):
         self.key = key
 
     def __str__(self) -> str:
+        path = get_home().joinpath(self.module).with_suffix(".ini")
         return dedent(
             f"""\
-        Could not look up {self.module}/{self.key} and no default given
+        Could not look up {self.module}/{self.key} and no default given.
 
-        1. Set the {self.module.upper()}_{self.key.upper()}
-        2. Create a file in {get_home()}/{self.module}.ini, create a section inside it
-           called [{self.module}] and set a value for {self.key} = ...
+        This can be solved with one of the following:
+
+        1. Set the {self.module.upper()}_{self.key.upper()} environment variable
+
+           - Windows, via GUI: https://www.computerhope.com/issues/ch000549.htm
+           - Windows, via CLI: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/set_1
+           - Mac OS: https://apple.stackexchange.com/questions/106778/how-do-i-set-environment-variables-on-os-x
+           - Linux: https://www.freecodecamp.org/news/how-to-set-an-environment-variable-in-linux/
+
+        2. Use the PyStow CLI from the command line to
+           set the configuration like so:
+
+           $ pystow set {self.module} {self.key} <value>
+
+           This creates an INI file in {path}
+           with the configuration in the right place.
+
+        3. Create/edit an INI file in {path} and manually
+           fill it in by 1) creating a section inside it called [{self.module}]
+           and 2) setting a value for {self.key} = <value> that looks like:
+
+           # {path}
+           [{self.module}]
+           {self.key} = <value>
 
         See https://github.com/cthoyt/pystow#%EF%B8%8F%EF%B8%8F-configuration for more information.
         """
@@ -69,7 +91,7 @@ def get_home(ensure_exists: bool = True) -> Path:
         2. The default directory constructed in the user's home directory plus what's
            returned by :func:`get_name`.
     """
-    default = Path.home() / get_name()
+    default = Path.home().joinpath(get_name()).expanduser()
     return getenv_path(CONFIG_HOME_ENVVAR, default, ensure_exists=ensure_exists)
 
 

src/pystow/utils.py

@@ -471,7 +471,7 @@ def getenv_path(envvar: str, default: Path, ensure_exists: bool = True) -> Path:
     :param ensure_exists: Should the directories leading to the path be created if they don't already exist?
     :return: A path either specified by the environmental variable or by the default.
     """
-    rv = Path(os.getenv(envvar, default=default))
+    rv = Path(os.getenv(envvar, default=default)).expanduser()
     mkdir(rv, ensure_exists=ensure_exists)
     return rv