File: index.rst

package info (click to toggle)
python-pystow 0.5.5-2
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid
  • size: 408 kB
  • sloc: python: 3,119; makefile: 13
file content (64 lines) | stat: -rw-r--r-- 2,275 bytes parent folder | download | duplicates (2)
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`