################################
 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`