Path

Contains path handling systems used internally by dman.

class dman.core.path.Config(on_retouch: str = 'ignore', default_suffix: str = '.sto')

Configuration class for path handling.

This class has a global instance that can be accessed as follows:

>>> dman.core.path.config.on_retouch = 'prompt'
>>> dman.params.store.on_retouch = 'prompt'  # equivalent

Parameters:

• on_retouch (str, optional) – Procedure handling re-used file names. Options are 'prompt', 'quit', 'ignore', 'auto'. Defaults to 'ignore'.

• default_suffix (str, optional) – Default suffix used for files when none is specified. Defaults to '.sto'.

exception dman.core.path.RootError

Raised when no .dman directory could be found.

dman.core.path.script_label(base: Optional[PathLike] = None)

Generate a label for the current executing script.

Takes the path relative to the folder containing .dman and replaces the separators with :.

dman.core.path.normalize_path(path: str)

Simplify path string relative to folder containing .dman to be used for printing.

exception dman.core.path.TargetException

Raised when an invalid target file is encountered.

class dman.core.path.Target(stem: str = <dman.core.path._Auto object>, suffix: str = <dman.core.path._Auto object>, subdir: ~os.PathLike = '', name: str = <dman.core.path._Auto object>)

Object representing file relative to current folder.

property name

Name of the file

classmethod from_path(path: PathLike)

Create a target from a relative path.

classmethod from_tuple(t)

Create a target from a tuple (subdir, stem, suffix).

is_complete()

Is the target completely specified.

merge(*args)

Merge target with others.

Example

>>> Target(name='test.json').merge(Target(suffix='.obj'), Target(subdir='folder'))
folder/test.obj
>>> Target(name='test.json').merge(Target(subdir='folder'), Target(suffix='.obj'))
test.obj
>>> Target(name='test.json').merge(Target(subdir='folder'), Target(suffix='.obj', subdir=AUTO))
folder/test.obj

update(stem: str = <dman.core.path._Auto object>, suffix: str = <dman.core.path._Auto object>, subdir: ~os.PathLike = <dman.core.path._Auto object>, name: str = <dman.core.path._Auto object>)

Update parts of target. See also merge().

dman.core.path.target(stem: str = <dman.core.path._Auto object>, suffix: str = <dman.core.path._Auto object>, name: str = <dman.core.path._Auto object>, subdir: str = '')

Get a target path used for relative file definitions.

<subdir>/<stem>.<suffix> or <subdir>/<name>

Raises:

ValueError – Both name and suffix or stem were provided.

dman.core.path.gitignore(directory: PathLike, ignored: Iterable, *, check: Optional[Iterable] = None)

Add ignored files to gitignore in provided directory.

Parameters:

• directory (os.PathLike) – Directory to add .gitignore file to.

• ignored (Iterable) – Files to add to current .gitignore.

• check (Iterable, optional) – Check whether these files still exists. If not, don’t add them.

dman.core.path.prune_directories(directory: PathLike, *, root=True)

Prune all empty directories contained within this one.

exception dman.core.path.UserQuitException

Raised when a file was re-used by a mount point and the quit option was selected.

exception dman.core.path.MountException

Raised when a file is accessed outside of a mount point.

class dman.core.path.Mount(directory: PathLike, cluster: bool = False, gitignore: bool = True)

Mount point used as start of file hierarchy.

contains(path: PathLike)

Is the specified path contained within this mount point.

abspath(path: PathLike, *, validate=False)

Get the absolute path

Raises:

ValueError – The path is not contained within this FileSystem.

normalize(path: PathLike, *, validate: bool = False)

Construct a target based on the path relative to this mount point.

default(target: Target)

Get default suggestion for target.

register(target: Target, *, choice: Optional[str] = None)

Register a target in the mount point.

It avoids registering a target multiple times. The behavior is determined by config.on_retouch or the value in choice.

• 'prompt': Prompt the user for a different file name.

• 'quit': Raise a UserQuitException.

• 'ignore': Override the existing file.

• 'auto': Add an index to the file name to make it unique.

prepare(target: PathLike, *, validate: bool = True, choice: Optional[str] = None)

Prepare directory to write to target path.

close()

Close this mount point.

Empty subdirectories are deleted and a gitignore is created if requested on creation.

open(path: PathLike, *args, **kwargs)

Open a file, registered by this mount point.

The signature is identical to the standard open command.

untrack(target: PathLike, *, validate: bool = False)

Untrack a registered file. Afterwards it can be overridden without issues.

remove(target: PathLike, *, validate: bool = True)

Delete a file from the mount point and stop tracking it.

dman.core.path.mount(key: str = '', *, subdir: PathLike = '', cluster: bool = True, generator: Optional[str] = None, base: Optional[PathLike] = None, gitignore: bool = True)

Get the mount point where a file with the given key is stored by dman.

The path of the file is determined as described below.

If the files are clustered then the path is <base>/<generator>/<subdir>/<key>/<key>.<ext> If cluster is set to False then the path is <base>/<generator>/<subdir>/<key>.<ext>

When base is not provided then it is set to .dman if it does not exist an exception is raised.

When generator is not provided it will automatically be set based on the location of the script relative to the .dman folder (again raising an exception if it is not found). For example if the script is located in <project-root>/examples/folder/script.py and .dman is located in <project-root>/.dman. Then generator is set to cache/examples:folder:script (i.e. the / is replaced by : in the output).

See Mounting and Targets for detailed examples on how to create and use mount points.

Parameters:

• key (str, optional) – Key for the file. Default '', so the generator folder is returned.

• subdir (os.PathLike, optional) – Specifies optional subdirectory in generator folder. Defaults to “”.

• cluster (bool, optional) – A subfolder key is automatically created when set to True. Defaults to True.

• generator (str, optional) – Specifies the generator that created the file. Defaults to script label.

• base (os.PathLike, optional) – Specifies the root folder. Defaults to “.dman”.

• gitignore (bool, optional) – Specifies whether files added to this mount point should be ignored.