Skip to content

Context

datamate.context

This module handles context management and global settings for Directory objects.

set_root_dir 

set_root_dir(root_dir)

Set the directory in which to search for Directory objects.

Parameters:

Name Type Description Default
root_dir Optional[Path]

Path to set as root directory. If None, uses current directory.

 required
Source code in datamate/context.py 
63
64
65
66
67
68
69
def set_root_dir(root_dir: Optional[Path]) -> None:
    """Set the directory in which to search for Directory objects.

    Args:
        root_dir: Path to set as root directory. If None, uses current directory.
    """
    context.root_dir.set(Path(root_dir) if root_dir is not None else Path("."))

get_root_dir 

get_root_dir()

Return the current Directory search directory.

Returns:

Name Type Description
Path Path

Current root directory, defaults to current directory if not set.
Source code in datamate/context.py 
72
73
74
75
76
77
78
def get_root_dir() -> Path:
    """Return the current Directory search directory.

    Returns:
        Path: Current root directory, defaults to current directory if not set.
    """
    return context.root_dir.get()

root 

root(root_dir=None, precedence=2)

Decorates a callable to fix its individual root directory.

Parameters:

Name Type Description Default
root_dir Union[str, Path, NoneType]

Root directory that will be set at execution of the callable.

 None
precedence Literal[1, 2, 3]

Determines the precedence of this root setting.

  • 1: Lowest - global and context settings override this
  • 2: Medium - overrides global but not context settings
  • 3: Highest - overrides both global and context settings
 2

Returns:

Name Type Description
callable callable

Decorated function or class.
Example 
@root("/path/to/this/individual/dir", precedence=3)
class MyDirectory(Directory):
    pass

dir = MyDirectory(...)
assert dir.path.parent == "/path/to/this/individual/dir"

Raises:

Type Description
ValueError

If decorator is applied to anything other than function or class.
Source code in datamate/context.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def root(
    root_dir: Union[str, Path, NoneType] = None, precedence: Literal[1, 2, 3] = 2
) -> callable:
    """Decorates a callable to fix its individual root directory.

    Args:
        root_dir: Root directory that will be set at execution of the callable.
        precedence: Determines the precedence of this root setting.

            - `1`: Lowest - global and context settings override this
            - `2`: Medium - overrides global but not context settings
            - `3`: Highest - overrides both global and context settings

    Returns:
        callable: Decorated function or class.

    Example:
        ```python
        @root("/path/to/this/individual/dir", precedence=3)
        class MyDirectory(Directory):
            pass

        dir = MyDirectory(...)
        assert dir.path.parent == "/path/to/this/individual/dir"
        ```

    Raises:
        ValueError: If decorator is applied to anything other than function or class.
    """

    if precedence not in [1, 2, 3]:
        raise ValueError("Precedence must be 1, 2, or 3")

    def decorator(callable):
        if inspect.isfunction(callable):

            @functools.wraps(callable)
            def function(*args, **kwargs):
                _root_dir = get_root_dir()
                within_context = context.within_root_context.get(False)

                if root_dir is not None and (
                    precedence == 3
                    or (precedence == 2 and not within_context)
                    or precedence == 1
                    and not within_context
                ):
                    set_root_dir(root_dir)

                _return = callable(*args, **kwargs)
                set_root_dir(_root_dir)
                return _return

            return function
        elif inspect.isclass(callable):
            new = callable.__new__

            @functools.wraps(callable)
            def function(*args, **kwargs):
                _root_dir = get_root_dir()
                within_context = context.within_root_context.get(False)

                if root_dir is not None and (
                    precedence == 3
                    or (precedence == 2 and not within_context)
                    or precedence == 1
                    and not within_context
                ):
                    set_root_dir(root_dir)

                _return = new(*args, **kwargs)
                set_root_dir(_root_dir)
                return _return

            callable.__new__ = function

            return callable
        else:
            raise ValueError("Decorator can only be applied to functions or classes.")

    return decorator

set_root_context 

set_root_context(root_dir=None)

Set root directory within a context and revert after.

Parameters:

Name Type Description Default
root_dir Union[str, Path, NoneType]

Temporary root directory to use within the context.

 None
Example 
with set_root_context(dir):
    Directory(config)
Note

Takes precedence over all other methods to control the root directory.

Source code in datamate/context.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
@contextmanager
def set_root_context(root_dir: Union[str, Path, NoneType] = None) -> None:
    """Set root directory within a context and revert after.

    Args:
        root_dir: Temporary root directory to use within the context.

    Example:
        ```python
        with set_root_context(dir):
            Directory(config)
        ```

    Note:
        Takes precedence over all other methods to control the root directory.
    """
    _root_dir = get_root_dir()
    set_root_dir(root_dir)
    context.within_root_context.set(True)
    try:
        yield
    finally:
        set_root_dir(_root_dir)
        context.within_root_context.set(False)

enforce_config_match 

enforce_config_match(enforce)

Enforce error if configs are not matching.

Parameters:

Name Type Description Default
enforce bool

Whether to enforce config matching.

 required
Note

Configs are compared when initializing a directory from an existing path and configuration.

Source code in datamate/context.py 
210
211
212
213
214
215
216
217
218
219
220
def enforce_config_match(enforce: bool) -> None:
    """Enforce error if configs are not matching.

    Args:
        enforce: Whether to enforce config matching.

    Note:
        Configs are compared when initializing a directory from an existing path
        and configuration.
    """
    context.enforce_config_match.set(enforce)

set_verbosity_level 

set_verbosity_level(level)

Set verbosity level of representation for Directory objects.

Parameters:

Name Type Description Default
level Literal[0, 1, 2]

Verbosity level where:

  • 0: Only top level directory name and last modified date
  • 1: Maximum 2 levels and 25 lines
  • 2: All directories and files
 required
Source code in datamate/context.py 
240
241
242
243
244
245
246
247
248
249
250
251
252
def set_verbosity_level(level: Literal[0, 1, 2]) -> None:
    """Set verbosity level of representation for Directory objects.

    Args:
        level: Verbosity level where:

            - `0`: Only top level directory name and last modified date
            - `1`: Maximum 2 levels and 25 lines
            - `2`: All directories and files
    """
    if level not in [0, 1, 2]:
        raise ValueError("Verbosity level must be 0, 1, or 2")
    context.verbosity_level.set(level)

check_size_on_init 

check_size_on_init(enforce)

Switch size warning on/off.

Parameters:

Name Type Description Default
enforce bool

Whether to check directory size on initialization.

 required
Note

Checking the size of a directory is slow, therefore this should be used only consciously.

Source code in datamate/context.py 
223
224
225
226
227
228
229
230
231
232
233
def check_size_on_init(enforce: bool) -> None:
    """Switch size warning on/off.

    Args:
        enforce: Whether to check directory size on initialization.

    Note:
        Checking the size of a directory is slow, therefore this should be used
        only consciously.
    """
    context.check_size_on_init.set(enforce)

delete_if_exists 

delete_if_exists(enable=True)

Delete directory if it exists within a context and revert after.

Parameters:

Name Type Description Default
enable bool

Whether to enable directory deletion.

 True
Example 
with delete_if_exists():
    Directory(config)
Source code in datamate/context.py 
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
@contextmanager
def delete_if_exists(enable: bool = True) -> None:
    """Delete directory if it exists within a context and revert after.

    Args:
        enable: Whether to enable directory deletion.

    Example:
        ```python
        with delete_if_exists():
            Directory(config)
        ```
    """
    token = context.delete_if_exists.set(enable)
    try:
        yield
    finally:
        context.delete_if_exists.reset(token)