0
# Directory Management
1

2
PyStow's directory management system provides standardized, configurable data storage for Python applications. It handles automatic directory creation, environment variable configuration, and versioned storage patterns.
3

4
## Core Directory Functions
5

6
### Module Creation
7

8
```python { .api }
9
def module(key: str, *subkeys: str, ensure_exists: bool = True) -> Module:
10
    """Return a module for the application.
11
    
12
    Args:
13
        key: The name of the module. No funny characters. The envvar <key>_HOME where
14
            key is uppercased is checked first before using the default home directory.
15
        subkeys: A sequence of additional strings to join. If none are given, returns
16
            the directory for this module.  
17
        ensure_exists: Should all directories be created automatically? Defaults to true.
18
    
19
    Returns:
20
        The module object that manages getting and ensuring
21
    """
22
```
23

24
### Path Creation
25

26
```python { .api }
27
def join(key: str, *subkeys: str, name: str | None = None, ensure_exists: bool = True, version: VersionHint = None) -> Path:
28
    """Return the home data directory for the given module.
29
    
30
    Args:
31
        key: The name of the module. No funny characters. The envvar <key>_HOME where
32
            key is uppercased is checked first before using the default home directory.
33
        subkeys: A sequence of additional strings to join
34
        name: The name of the file (optional) inside the folder
35
        ensure_exists: Should all directories be created automatically? Defaults to true.
36
        version: The optional version, or no-argument callable that returns an
37
            optional version. This is prepended before the subkeys.
38
    
39
    Returns:
40
        The path of the directory or subdirectory for the given module.
41
    """
42
```
43

44
## Configuration
45

46
### Environment Variables
47

48
PyStow respects several environment variables for configuration:
49

50
- `PYSTOW_HOME`: Override the default base directory (e.g., `/usr/local/data`)
51
- `PYSTOW_NAME`: Change the default directory name from `.data` (e.g., `mydata`) 
52
- `<MODULE>_HOME`: Set custom home for specific modules (e.g., `MYAPP_HOME=/custom/path`)
53

54
### Directory Structure
55

56
Default directory structure follows the pattern:
57
```
58
$HOME/.data/
59
├── myapp/
60
│   ├── datasets/
61
│   │   └── v1/
62
│   └── config/
63
└── otherapp/
64
    └── cache/
65
```
66

67
With version support:
68
```
69
$HOME/.data/
70
└── myapp/
71
    ├── v1.0/
72
    │   └── data.csv
73
    └── v2.0/
74
        └── data.csv
75
```
76

77
## Usage Examples
78

79
### Basic Directory Management
80

81
```python
82
import pystow
83

84
# Get application directory
85
app_dir = pystow.join("myapp")
86
# Creates: $HOME/.data/myapp/
87

88
# Get nested directories
89
data_dir = pystow.join("myapp", "datasets", "raw")
90
# Creates: $HOME/.data/myapp/datasets/raw/
91

92
# Get file path
93
config_path = pystow.join("myapp", "config", name="settings.json")
94
# Returns: $HOME/.data/myapp/config/settings.json
95
```
96

97
### Module-Based Management
98

99
```python
100
import pystow
101

102
# Create a module for your application
103
module = pystow.module("myapp")
104

105
# Get subdirectories
106
data_module = module.module("datasets")
107
config_module = module.module("config")
108

109
# Get file paths
110
data_file = data_module.join(name="data.csv")
111
config_file = config_module.join(name="settings.json")
112
```
113

114
### Version-Aware Storage
115

116
```python
117
import pystow
118
import requests
119

120
def get_data_version():
121
    """Get current data version from API"""
122
    response = requests.get("https://api.example.com/version")
123
    return response.json()["version"]
124

125
# Store data with version
126
data_path = pystow.join(
127
    "myapp", "datasets", 
128
    name="data.csv",
129
    version=get_data_version  # Callable for dynamic versioning
130
)
131

132
# Or with static version
133
data_path = pystow.join(
134
    "myapp", "datasets",
135
    name="data.csv", 
136
    version="v1.2.3"
137
)
138
```
139

140
### Custom Base Directories
141

142
```python
143
import os
144
import pystow
145

146
# Set custom base directory
147
os.environ['PYSTOW_HOME'] = '/opt/data'
148

149
# Now all modules use /opt/data as base
150
app_dir = pystow.join("myapp")  # -> /opt/data/myapp/
151

152
# Set app-specific directory
153
os.environ['MYAPP_HOME'] = '/custom/myapp/path'
154
app_dir = pystow.join("myapp")  # -> /custom/myapp/path/
155
```
156

157
### Directory Control
158

159
```python
160
import pystow
161

162
# Don't create directories automatically
163
path = pystow.join("myapp", "temp", ensure_exists=False)
164

165
# Only create if it doesn't exist
166
if not path.exists():
167
    path.mkdir(parents=True)
168
```
169

170
## File Path Utilities
171

172
### SQLite Connection Strings
173

174
```python { .api }
175
def joinpath_sqlite(key: str, *subkeys: str, name: str) -> str:
176
    """Get an SQLite database connection string.
177
    
178
    Args:
179
        key: The name of the module. No funny characters. The envvar <key>_HOME
180
            where key is uppercased is checked first before using the default home
181
            directory.
182
        subkeys: A sequence of additional strings to join. If none are given, returns
183
            the directory for this module.
184
        name: The name of the database file.
185
    
186
    Returns:
187
        A SQLite path string.
188
    """
189
```
190

191
Usage:
192
```python
193
import pystow
194
import sqlite3
195

196
# Get SQLite connection string
197
db_path = pystow.joinpath_sqlite("myapp", "databases", name="data.db")
198
conn = sqlite3.connect(db_path)
199
```