Basic linking

This section describes Dantalian’s basic linking features.

Dantalian’s fundamental linking functionality is contained in dantalian.base. The main functions defined in this module are link(), unlink(), and rename(), which are analogous to their counterparts in the standard os module, except that they have been extended to work with directories (see Directory linking). dantalian.base additionally includes helper functions to compensate for the implementation of these extended features.

Link src to dst. See Directory linking for how directories are linked.

Parameters:
  • rootpath (str) – Path for tagname conversions.
  • src (str) – Source path.
  • dst (str) – Destination path.

Unlink the given path. See Directory linking for how directories are unlinked.

If the directory does not have any extra links, IsADirectoryError is raised.

If path is the actual directory and the directory dies have extra links, the directory is swapped out using swap_dir()

Parameters:
  • rootpath (str) – Path for tagname conversions.
  • path (str) – Target path.
Raises IsADirectoryError:
 

Target is a directory without any other links.

Note

This function does not work recursively for directories. For example, unlinking a directory foo that contains a link bar to another directory will not properly update bar‘s .dtags file.

dantalian.base.rename(rootpath, src, dst)

Renames the given link. Implemented as and functionally equivalent to:

link(rootpath, src, dst)
unlink(rootpath, src)
Parameters:
  • rootpath (str) – Path for tagname conversions.
  • src (str) – Source path.
  • dst (str) – Destination path.

Note

This will not overwrite files, unlike os.rename().

Note

This function does not work recursively for directories. For example, renaming a directory foo that contains a link bar to another directory will not properly update bar‘s .dtags file.

The following function is provided for convenience.

Traverse the directory tree, finding all of the links to the target file.

Parameters:
  • top (str) – Path of directory to begin search.
  • path (str) – Path of target file.
Returns:

Generator yielding paths.

Note

This function returns a generator that lazily traverses the file system. Any changes to the file system will affect the generator’s execution.

Directory linking

Directory linking is implemented in Dantalian using symlinks and a file named .dtags in each tagged directory. Dantalian assumes that the status of symlinks in the file system are consistent with the contents of the .dtags files, except for a number of administrative functions.

A directory is linked thus, given a target path path and a rootpath rootpath: A symlink is created at path, whose target is the absolute path to the directory. A tagname is created given path and rootpath, which is added to the file named .dtags in the directory.

Similarly, a directory is unlinked thus, given a target path path and a rootpath rootpath: The symlink at path is removed, and the tagname created given path and rootpath is removed from the .dtags file in the directory. Unlinking a directory that has no such extra links is invalid.

The following function is provided for convenience.

dantalian.base.swap_dir(rootpath, path)

Swap a symlink with its target directory. More specifically, given that an actual directory with path foo is also linked at bar, calling this function on bar will move the actual directory to bar, creating a symlink at foo, and updating the .dtags file appropriately.

This is useful when the actual directory, not a symlink, is needed somewhere.

Parameters:
  • rootpath (str) – Path for tagname conversions.
  • path (str) – Target path.
Raises ValueError:
 

Target is not a symlink to a directory.

The following are administrative functions that do not necessarily assume that symlink state is consistent with .dtags state and are used to repair and maintain such state consistency.

dantalian.base.save_dtags(rootpath, top, dirpath)

Save the current state of symlinks to the target directory in its .dtags file, overwriting its current .dtags state. The file system search is done recursively from top.

This is useful for “committing” file system changes to .dtags files.

Parameters:
  • rootpath (str) – Path for tagname conversions.
  • top (str) – Path of search directory.
  • dirpath (str) – Path of target directory.
dantalian.base.load_dtags(rootpath, dirpath)

Create symlinks according to the directory’s .dtags file.

This is useful in conjunction with unload_dtags() for moving directory trees around without worrying about symlink targets.

Parameters:
  • rootpath (str) – Path for tagname conversions.
  • dirpath (str) – Path of target directory.
dantalian.base.unload_dtags(rootpath, dirpath)

Remove symlinks according to the directory’s .dtags file.

This is useful in conjunction with load_dtags() for moving directory trees around without worrying about symlink targets.

Parameters:
  • rootpath (str) – Path for tagname conversions.
  • dirpath (str) – Path of target directory.

Tagnames

Tagnames are a special type of pathnames used by Dantalian internally. They begin with at least two forward slashes. After stripping all forward slashes from the beginning of a tagname, the remaining string is considered a pathname relative to a given rootpath.

Tagnames are used in .dtags files for tagging directories, as well as as shortcuts for the standalone script.

dantalian.tagnames contains functions for working with tagnames. Even though the transformation between tagnames and pathnames is relatively simple, use the functions provided in this module to ensure consistent behavior.

dantalian.tagnames.is_tag(name)

Check if the given path is a tagname.

Parameters:name (str) – Pathname.
Returns:Whether the given path is a tagname.
Return type:bool
dantalian.tagnames.path2tag(rootpath, pathname)

Convert a pathname to a tagname.

This function will also normalize the given path before converting it to a tagname.

Parameters:
  • rootpath (str) – Path for tagname conversions.
  • pathname (str) – Pathname.
Returns:

Tagname.
Return type:

str
dantalian.tagnames.tag2path(rootpath, tagname)

Convert a tagname to a pathname.

This function doesn’t normalize the resulting path.

Parameters:
  • rootpath (str) – Path for tagname conversions.
  • tagname (str) – Tagname.
Returns:

Pathname.
Return type:

str
dantalian.tagnames.path(rootpath, name)

Return the given tagname or pathname as a pathname.

In other words, convert the given name to a pathname if it is tagname.

dantalian.tagnames.tag(rootpath, name)

Return the given tagname or pathname as a tagname.

In other words, convert the given name to a tagname if it is not a tagname.

Libraries

Libraries are special directories Dantalian uses to make file management more convenient. A library is a directory that contains a subdirectory named .dantalian.

Currently, libraries exist to provide a clear rootpath to be used by Dantalian’s various linking function. The standalone Dantalian script will search parent directories for a library to use as a root for many commands so that you do not have to explicitly provide one yourself. Other scripts using Dantalian as a library can also take advantage of libraries as anchor points.

Currently, .dantalian is not used for anything beyond identifying libraries, but in the future, it may be used for caching search results or other caching or data storage purposes.

dantalian.library contains functions for working with libraries.

dantalian.library.is_library(dirpath)

Return whether the given directory is a library.

Parameters:dirpath (str) – Path to directory.
Returns:Whether directory is library.
Return type:bool
dantalian.library.find_library(dirpath='.')

Find a library. Starting from the given path, search up the file system. Return the path of the first library found, including the initially given path. Returns None if no library is found.

Parameters:dirpath (str) – Path to search.
Returns:Path or None
Return type:str or None
dantalian.library.init_library(dirpath)

Initialize a library. Does nothing if the given directory is already a library.

Parameters:dirpath (str) – Path to directory.
dantalian.library.get_resource(dirpath, resource_path)

Get the path of a resource stored in the library.

May be used in the future for library data or cache storage.