PyStow 0.5.1-dev Documentation
If you’ve ever written the following few lines of code, pystow
is for you:
import os
home = os.path.expanduser('~')
project_name = 'adeft'
envvar_name = f'{project_name.upper()}_HOME'
if envvar_name in os.environ:
ADEFT_HOME = os.environ[envvar_name]
else:
ADEFT_HOME = os.path.join(home, f'.{project_name}')
os.makedirs(ADEFT_HOME, exist_ok=True)
Many projects (let’s use Adeft as an example) create a folder in the home
directory as a dot-file such as $HOME/.adeft
. I found that I had so many of these that I started grouping
them inside a $HOME/.data
folder. It’s also the case that every time you create one of these folders,
you need to ensure its existence.
pystow
takes care of these things. You can replace the previous code with:
import pystow
ADEFT_HOME = pystow.join('adeft')
First, it takes the name of the module, uppercases it, and postpends _HOME
on to it (e.g., ADEFT_HOME
)
and looks in the environment. If this variable is available, it uses that as the directory. It ensures it
exists, then returns a pathlib.Path
pointing to it.
If ADEFT_HOME
(or more generally, <MODULENAME>_HOME
is not available in the environment, it picks the
path as $HOME/.data/<module name>
. Normally, $HOME
is specified in your OS. However, if you want to
pick another location to stick the data, you can override using $HOME
by setting $PYSTOW_HOME
in
the environment.
If you want to go more directories deep inside the adeft default directory, you can just keep using more
positional arguments (the same semantics as os.path.join()
). These directories automatically
get created as well.
>>> import pystow
>>> from pathlib import Path
>>> # already set somewhere
>>> __version__ = ...
>>> ADEFT_VERSION_HOME: Path = pystow.join('adeft', __version__)