1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
|
PyStow |release| Documentation
==============================
If you've ever written the following few lines of code, :mod:`pystow` is for you:
.. code-block:: python
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 <https://github.com/indralab/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.
:mod:`pystow` takes care of these things. You can replace the previous code with:
.. code-block:: python
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 :class:`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 :func:`os.path.join`). These directories automatically
get created as well.
.. code-block:: python
>>> import pystow
>>> from pathlib import Path
>>> # already set somewhere
>>> __version__ = ...
>>> ADEFT_VERSION_HOME: Path = pystow.join('adeft', __version__)
.. toctree::
:maxdepth: 2
:caption: Getting Started
:name: start
installation
usage
utils
cli
Indices and Tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
|