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.
-
dantalian.base.
link
(rootpath, src, dst)¶ 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.
-
dantalian.base.
unlink
(rootpath, 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 linkbar
to another directory will not properly updatebar
‘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 linkbar
to another directory will not properly updatebar
‘s.dtags
file.
The following function is provided for convenience.
-
dantalian.base.
list_links
(top, path)¶ 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 atbar
, calling this function onbar
will move the actual directory tobar
, creating a symlink atfoo
, 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.
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.
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.
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.