Simple filesystem based file tagging
and the associated `fstags` command line script.
*Latest release 20241122*:
* FSTags.copy: use atomic_copy2 instead of shutil.copy2.
* FSTagsCommand: rename "-o ontology" to "-O ontology", modernise option specifications.
Many basic tasks can be performed with the `fstags` command line utility,
documented under the `FSTagsCommand` class below.
Why `fstags`?
By storing the tags in a separate file we:
* can store tags without modifying a file
* do not need to know the file's format,
or even whether that format supports metadata
* can process tags on any kind of file
* because tags are inherited from parent directories,
tags can be automatically acquired merely by arranging your file tree
Tags are stored in the file `.fstags` in each directory;
there is a line for each entry in the directory
consisting of the directory entry name and the associated tags.
Tags may be "bare", or have a value.
If there is a value it is expressed with an equals (`'='`)
followed by the JSON encoding of the value.
The tags for a file are the union of its direct tags
and all relevant ancestor tags,
with priority given to tags closer to the file.
For example, a media file for a television episode with the pathname
`/path/to/series-name/season-02/episode-name--s02e03--something.mp4`
might have the tags:
series_title="Series Full Name"
season=2
sf
episode=3
episode_title="Full Episode Title"
obtained from the following `.fstags` entries:
* tag file `/path/to/.fstags`:
series-name sf series_title="Series Full Name"
* tag file `/path/to/series-name/.fstags`:
season-02 season=2
* tag file `/path/to/series-name/season-02/.fstags`:
episode-name--s02e03--something.mp4 episode=3 episode_title="Full Episode Title"
## `fstags` Examples ##
### Backing up a media tree too big for the removable drives ###
Walk the media tree for files tagged for backup to `archive2`:
fstags find /path/to/media backup=archive2
Walk the media tree for files not assigned to a backup archive:
fstags find /path/to/media -backup
Backup the `archive2` files using `rsync`:
fstags find --for-rsync /path/to/media backup=archive2 \
| rsync -ia --include-from=- /path/to/media /path/to/backup_archive2
## <a name="CachedValue"></a>Class `CachedValue`
Manage a cached value stored in a `TaggedPath`.
The value and the validity state are stored in a prefixed
subsection of the tags.
This is how modules like `cs.hashindex` cache file content hashcodes.
The default state function is `TaggedPath.stat_size_mtime`,
which returns `{'st_size':st_size,'st_mtime':int(st_mtime)}` by default,
essentially the same criteria used by `rsync(1)` to skip
comparing file contents.
Example:
tags = fstags[fspath]
hash
*`CachedValue.__init__(self, taggedpath: cs.fstags.TaggedPath, prefix: str, name: str, *, state_func: Optional[Callable[[str], Mapping[str, Any]]] = None)`*:
Initialise a cached value reference.
Parameters:
* `taggedpath`: the `TaggedPath` tagged file system path
* `prefix`: the tags prefix
* `name`: the tag name for the value
* `state_func`; an optional function to compute the current
state if `taggedpath`; the default is
`CachedValue.stat_size_mtime` which returns the current
file `st_size` and `st_mtime`
*`CachedValue.get(self) -> Tuple[Optional[Any], Mapping[str, Any]]`*:
Get the cached value if the current state matches the cache
state, otherwise `None`.
Return the valu or `None` and the current state.
*`CachedValue.set(self, value: Any, *, state: Mapping = None)`*:
Update the cached value and associated state.
If the state is omitted, the current state is used.
*`CachedValue.stat_size_mtime(fspath: str, round_mtime=<class 'int'>, follow_symlinks=True) -> dict`*:
Return the default cache state mapping.
This function `stat`s the `fspath` and returns `{'size':st_size,'mtime':int(st_mtime)}`.
## <a name="CascadeRule"></a>Class `CascadeRule`
A cascade rule of possible source tag names to provide a target tag.
*`CascadeRule.infer_tag(self, tagset)`*:
Apply the rule to the `TagSet` `tagset`.
Return a new `Tag(self.target,value)`
for the first cascade `value` found in `tagset`,
or `None` if there is no match.
## <a name="DEFAULT_FSTAGS"></a>`DEFAULT_FSTAGS = FSTags('.fstags')`
A class to examine filesystem tags.
## <a name="FSTags"></a>Class `FSTags(cs.resources.MultiOpenMixin)`
A class to examine filesystem tags.
*`FSTags.__init__(self, tagsfile_basename=None, ontology_filepath=None, physical=None, update_mapping: Optional[Mapping] = None, update_prefix: Optional[str] = 'cs.fstags', update_uuid_tag_name: Optional[str] = 'uuid')`*:
Initialise the `FSTags` instance.
Parameters:
* `tagsfile_basename`: optional basename forthe backing tags files,
default from `TAGSFILE_BASENAME`: `'.fstags'`
* `ontology_filepath`: optional filesystem path for an associated ontology
* `physical`: optional flag for the associated `FSTagsConfig`
specifying whether `TagFile`s are indexed by their physical or logical
filesystem paths
* `update_mapping`: optional secondary mapping to which to mirror
tags, such as an `SQLTags`;
the default comes from an `SQLTags` specified by the
environment variable `$FSTAGS_UPDATE_MAPPING`
if present
* `update_prefix`: optional key prefix for use in the secondary mapping;
the default comes from the environment variable
`$FSTAGS_UPDATE_MAPPING_PREFIX` if present,
otherwise `'cs.fstags'`
* `update_uuid_tag_name`: optional name for the per file UUID tag name;
default `'uuid'`
*`FSTags.__getitem__(self, path) -> 'TaggedPath'`*:
Return the `TaggedPath` for `abspath(path)`.
*`FSTags.apply_tag_choices(self, tag_choices, paths)`*:
Apply the `tag_choices` to `paths`.
Parameters:
* `tag_choices`:
an iterable of `Tag` or an equality `TagBasedTest`.
Each item applies or removes a `Tag`
from each path's direct tags.
* `paths`:
an iterable of filesystem paths.
*`FSTags.attach_path(self, attach, srcpath, dstpath, *, force=False, crop_ok=False)`*:
Attach `srcpath` to `dstpath` using the `attach` callable.
Parameters:
* `attach`: callable accepting `attach(srcpath,dstpath)`
to do the desired attachment,
such as a copy, link or move
* `srcpath`: the source filesystem object
* `dstpath`: the destination filesystem object
* `crop_ok`: if true and the OS raises `OSError(ENAMETOOLONG)`
attempt to crop the name before the file extension and retry
* `force`: default `False`.
If true and the destination exists
try to remove it before calling `attach`.
Otherwise if the destination exists
raise a `ValueError`.
*`FSTags.cascade_tags(self, tags, cascade_rules=None)`*:
Yield `Tag`s
which cascade from the `TagSet` `tags`
via `cascade_rules` (an iterable of `CascadeRules`).
*`FSTags.copy(self, srcpath, dstpath, **kw)`*:
Copy `srcpath` to `dstpath`.
*`FSTags.dir_tagfile(self, dirpath: str) -> 'FSTagsTagFile'`*:
Return the `FSTagsTagFile` associated with `dirpath`.
*`FSTags.edit_dirpath(self, dirpath, all_names=False)`*:
Edit the filenames and tags in a directory.
If `all_names` is true, include names commencing with a dot,
otherwise exclude them.
*`FSTags.export_xattrs(self, paths)`*:
Import the extended attributes of `paths`
and use them to update the fstags.
*`FSTags.find(self, path, tag_tests, use_direct_tags=False)`*:
Walk the file tree from `path`
searching for files matching the supplied `tag_tests`.
Yield the matching file paths.
Parameters:
* `path`: the top of the file tree to walk
* `tag_tests`: a sequence of `TagBasedTest`s
* `use_direct_tags`: test the `direct_tags` if true,
otherwise the `all_tags`.
Default: `False`
*`FSTags.find_ontology(self, dirpath, ontbase=None)`*:
Locate an ontology for the directory `dirpath`.
The optional `ontbase` may override the relative path to the file,
default is `self.ontology_filepath`.
Return a `TagOntology` or `None` if not found.
*`FSTags.find_ontpath(self, dirpath, ontbase=None)`*:
Locate an ontology file for the directory `dirpath`.
The optional `ontbase` may override the relative path to the file,
default is `self.ontology_filepath`.
Return the found ontology file or `None` if not found.
*`FSTags.import_xattrs(self, paths)`*:
Update the extended attributes of `paths`
from their fstags.
*`FSTags.keypath(self, fspath)`*:
Compute the absolute path used to index a `TaggedPath` instance.
This returns `realpath(fspath)` if `self.config.physical`,
otherwise `abspath(fspath)`.
*`FSTags.link(self, srcpath, dstpath, **kw)`*:
Link `srcpath` to `dstpath`.
*`FSTags.move(self, srcpath, dstpath, **kw)`*:
Move `srcpath` to `dstpath`.
*`FSTags.mv(self, srcpath: str, dstpath: str, *, symlink=False, remove=True)`*:
Move (or link or symlink) `srcpath` to `dstpath`.
Parameters:
* `srcpath`: the source filesystem path
* `dstpath`: the destination filesystem path
* `symlink`: default `False`: if true, make a symbolic link
* `remove`: default `True`: if true, remove `srcpath` after
hard linking to `dstpath`
*`FSTags.ontology`*:
The primary `TagsOntology`, or `None` if `self.ontology_filepath` was `None`.
*`FSTags.ontology_filepath`*:
The ontology file basename.
*`FSTags.ontology_for(self, path, ontbase=None)`*:
Return the `TagsOntology` associated with `path`.
Returns `None` if an ontology cannot be found.
*`FSTags.open_ontology(self, ontpath)`*:
Open the contology file at `ontpath`.
*`FSTags.path_tagfiles(self, fspath)`*:
Generator yielding a sequence of `(FSTagsTagFile,name)` pairs
where `name` is the key within the `FSTagsTagFile`
for the `FSTagsTagFile`s affecting `fspath`
in order from the root to `dirname(fspath)`.
*`FSTags.resolve_format_string(self, format_string)`*:
See if `format_string` looks like `[`*clausename*`]`*entryname*.
if so, return the corresponding config entry string,
otherwise return `format_string` unchanged.
*`FSTags.scrub(self, path)`*:
Scrub tags for names which do not exist in the filesystem.
*`FSTags.startup_shutdown(self)`*:
Sync tag files and db mapping on final close.
*`FSTags.sync(self)`*:
Flush modified tag files.
*`FSTags.tagfile_for(self, fspath)`*:
Return the `FSTagsTagFile` storing the `Tag`s for `fspath`.
*`FSTags.tagsfile_basename`*:
The tag file basename.
*`FSTags.test(self, path, tag_tests, use_direct_tags=False)`*:
Test a path against `tag_tests`.
Parameters:
* `path`: path to test
* `tag_tests`: an iterable of `TagBasedTest`s
* `use_direct_tags`: test the `direct_tags` if true,
otherwise the `all_tags`.
Default: `False`
## <a name="FSTagsCommand"></a>Class `FSTagsCommand(cs.cmdutils.BaseCommand, cs.tagset.TagsCommandMixin)`
Usage summary:
Usage: fstags [common-options...] [-o ontology] [-P] subcommand [...]
Work with fstags.
Subcommands:
autotag [common-options...] paths...
Tag paths based on rules from the rc file.
cp [common-options...] [-finv] srcpath dstpath, cp [common-options...] [-finv] srcpaths... dstdirpath
POSIX cp(1) equivalent, but also copying tags: copy files and their tags into targetdir.
-f Force: remove destination if it exists.
-i Interactive: fail if the destination exists.
-n No remove: fail if the destination exists.
-v Verbose: show copied files.
cptags [common-options...] srcpath dstpath
Copy the direct tags from srcpath to dstpath.
edit [common-options...] [-ad] [path]
Edit the direct tagsets of path, default: '.'.
If path is a directory, provide the tags of its entries.
Otherwise edit just the tags for path.
-a List all names in directory edit mode; normally
names commencing with a dot are omitted.
-d Treat directories like files: edit just its tags.
export [common-options...] [-a] [--direct] path {tag[=value]|-tag}...
Export tags for files from paths matching all the constraints.
-a Export all paths, not just those with tags.
--direct Export the direct tags instead of the computed tags.
The output is in the same CSV format as that from "sqltags export",
with the following columns:
* unixtime: the file's st_mtime from os.stat.
* id: empty
* name: the file path
* tags: the file's direct or indirect tags
find [common-options...] [--direct] [--for-rsync] [-o output_format] path {tag[=value]|-tag}...
List files from path matching all the constraints.
--direct Use direct tags instead of all tags.
--for-rsync Instead of listing matching paths, emit a
sequence of rsync(1) patterns suitable for use with
--include-from in order to do a selective rsync of the
matched paths.
-o output_format
Use output_format as a Python format string to lay out
the listing.
Default: {fspath}
help [common-options...] [-l] [-s] [subcommand-names...]
Print help for subcommands.
This outputs the full help for the named subcommands,
or the short help for all subcommands if no names are specified.
-l Long help.
-r Recurse into subcommands.
-s Short help.
import [common-options...] {-|srcpath}...
Import CSV data in the format emitted by "export".
Each argument is a file path or "-", indicating standard input.
infer [common-options...] pathname
Print the base and inferred tags for pathname.
info [common-options...] [field-names...]
Recite general information.
Explicit field names may be provided to override the default listing.
json_import --prefix=tag_prefix {-|path} {-|tags.json}
Apply JSON data to path.
A path named "-" indicates that paths should be read from
the standard input.
The JSON tag data come from the file "tags.json"; the name
"-" indicates that the JSON data should be read from the
standard input.
ln [common-options...] [-finv] srcpath dstpath, ln [common-options...] [-finv] srcpaths... dstdirpath
POSIX ln(1) equivalent, but also copying the tags: link files and their tags into targetdir.
-f Force: remove destination if it exists.
-i Interactive: fail if the destination exists.
-n No remove: fail if the destination exists.
-v Verbose: show linked files.
ls [common-options...] [-dlr] [--direct] [-o output_format] [paths...]
List files from paths and their tags.
-d Treat directories like files, do not recurse.
--direct List direct tags instead of all tags.
-l Long format.
-o output_format
Use output_format as a Python format string to lay out
the listing.
Default: {fspath:json} {tags}
-r Recurse into subdirectories.
mv [common-options...] [-finv] srcpath dstpath, mv [common-options...] [-finv] srcpaths... dstdirpath
POSIX mv(1) equivalent, but also copying the tags: move files and their tags into targetdir.
-f Force: remove destination if it exists.
-i Interactive: fail if the destination exists.
-n No remove: fail if the destination exists.
-v Verbose: show moved files.
ns [common-options...] [-d] [--direct] [paths...]
Report on the available primary namespace fields for formatting.
Note that because the namespace used for formatting has
inferred field names there are also unshown secondary field
names available in format strings.
-d Treat directories like files, do not recurse.
--direct List direct tags instead of all tags.
ont [common-options...] [subcommand [args...]]
With no arguments, print the ontology.
rename [common-options...] -o basename_format paths...
Rename paths according to a format string.
-o basename_format
Use basename_format as a Python format string to
compute the new basename for each path.
scrub [common-options...] paths...
Remove all tags for missing paths.
If a path is a directory, scrub the immediate paths in the directory.
shell [common-options...]
Run a command prompt via cmd.Cmd using this command's subcommands.
tag [common-options...] {-|path} {tag[=value]|-tag}...
Tag a path with multiple tags.
With the form "-tag", remove that tag from the direct tags.
A path named "-" indicates that paths should be read from the
standard input.
tagfile [common-options...] tagfile_path [subcommand ...]
Perform operations on a tag file.
Subcommands:
tag tagset_name {tag[=value]|-tag}...
Directly modify tag_name within the tag file tagfile_path.
tagpaths [common-options...] {tag[=value]|-tag} {-|paths...}
Tag multiple paths.
With the form "-tag", remove the tag from the immediate tags.
A single path named "-" indicates that paths should be read
from the standard input.
test [common-options...] [--direct] path {tag[=value]|-tag}...
Test whether the path matches all the constraints.
--direct Use direct tags instead of all tags.
xattr-export [common-options...] {-|paths...}
Import tag information from extended attributes.
xattr-import [common-options...] {-|paths...}
Update extended attributes from tags.
*`FSTagsCommand.Options`*
*`FSTagsCommand.cmd_autotag(self, argv, *, upd: cs.upd.Upd, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x108b55fc0>)`*:
Usage: {cmd} paths...
Tag paths based on rules from the rc file.
*`FSTagsCommand.cmd_cp(self, argv)`*:
Usage: {cmd} [-finv] srcpath dstpath, {cmd} [-finv] srcpaths... dstdirpath
POSIX cp(1) equivalent, but also copying tags: copy files and their tags into targetdir.
-f Force: remove destination if it exists.
-i Interactive: fail if the destination exists.
-n No remove: fail if the destination exists.
-v Verbose: show copied files.
*`FSTagsCommand.cmd_cptags(self, argv)`*:
Usage: {cmd} srcpath dstpath
Copy the direct tags from srcpath to dstpath.
*`FSTagsCommand.cmd_edit(self, argv)`*:
Usage: {cmd} [-ad] [path]
Edit the direct tagsets of path, default: '.'.
If path is a directory, provide the tags of its entries.
Otherwise edit just the tags for path.
-a List all names in directory edit mode; normally
names commencing with a dot are omitted.
-d Treat directories like files: edit just its tags.
*`FSTagsCommand.cmd_export(self, argv, *, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x108b56440>)`*:
Usage: {cmd} [-a] [--direct] path {{tag[=value]|-tag}}...
Export tags for files from paths matching all the constraints.
-a Export all paths, not just those with tags.
--direct Export the direct tags instead of the computed tags.
The output is in the same CSV format as that from "sqltags export",
with the following columns:
* unixtime: the file's st_mtime from os.stat.
* id: empty
* name: the file path
* tags: the file's direct or indirect tags
*`FSTagsCommand.cmd_find(self, argv, *, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x108b565f0>)`*:
Usage: {cmd} [--direct] [--for-rsync] [-o output_format] path {{tag[=value]|-tag}}...
List files from path matching all the constraints.
--direct Use direct tags instead of all tags.
--for-rsync Instead of listing matching paths, emit a
sequence of rsync(1) patterns suitable for use with
--include-from in order to do a selective rsync of the
matched paths.
-o output_format
Use output_format as a Python format string to lay out
the listing.
Default: {FIND_OUTPUT_FORMAT_DEFAULT}
*`FSTagsCommand.cmd_import(self, argv)`*:
Usage: {cmd} {{-|srcpath}}...
Import CSV data in the format emitted by "export".
Each argument is a file path or "-", indicating standard input.
*`FSTagsCommand.cmd_infer(self, argv)`*:
Usage: {cmd} pathname
Print the base and inferred tags for pathname.
*`FSTagsCommand.cmd_json_import(self, argv)`*:
Usage: json_import --prefix=tag_prefix {{-|path}} {{-|tags.json}}
Apply JSON data to path.
A path named "-" indicates that paths should be read from
the standard input.
The JSON tag data come from the file "tags.json"; the name
"-" indicates that the JSON data should be read from the
standard input.
*`FSTagsCommand.cmd_ln(self, argv)`*:
Usage: {cmd} [-finv] srcpath dstpath, {cmd} [-finv] srcpaths... dstdirpath
POSIX ln(1) equivalent, but also copying the tags: link files and their tags into targetdir.
-f Force: remove destination if it exists.
-i Interactive: fail if the destination exists.
-n No remove: fail if the destination exists.
-v Verbose: show linked files.
*`FSTagsCommand.cmd_ls(self, argv, *, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x108b569e0>)`*:
Usage: {cmd} [-dlr] [--direct] [-o output_format] [paths...]
List files from paths and their tags.
-d Treat directories like files, do not recurse.
--direct List direct tags instead of all tags.
-l Long format.
-o output_format
Use output_format as a Python format string to lay out
the listing.
Default: {LS_OUTPUT_FORMAT_DEFAULT}
-r Recurse into subdirectories.
*`FSTagsCommand.cmd_mv(self, argv)`*:
Usage: {cmd} [-finv] srcpath dstpath, {cmd} [-finv] srcpaths... dstdirpath
POSIX mv(1) equivalent, but also copying the tags: move files and their tags into targetdir.
-f Force: remove destination if it exists.
-i Interactive: fail if the destination exists.
-n No remove: fail if the destination exists.
-v Verbose: show moved files.
*`FSTagsCommand.cmd_ns(self, argv, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x108b56dd0>)`*:
Usage: {cmd} [-d] [--direct] [paths...]
Report on the available primary namespace fields for formatting.
Note that because the namespace used for formatting has
inferred field names there are also unshown secondary field
names available in format strings.
-d Treat directories like files, do not recurse.
--direct List direct tags instead of all tags.
*`FSTagsCommand.cmd_ont(self, argv)`*:
Ontology operations.
Usage: {cmd} [subcommand [args...]]
With no arguments, print the ontology.
*`FSTagsCommand.cmd_rename(self, argv)`*:
Usage: {cmd} -o basename_format paths...
Rename paths according to a format string.
-o basename_format
Use basename_format as a Python format string to
compute the new basename for each path.
*`FSTagsCommand.cmd_scrub(self, argv)`*:
Usage: {cmd} paths...
Remove all tags for missing paths.
If a path is a directory, scrub the immediate paths in the directory.
*`FSTagsCommand.cmd_tag(self, argv)`*:
Usage: {cmd} {{-|path}} {{tag[=value]|-tag}}...
Tag a path with multiple tags.
With the form "-tag", remove that tag from the direct tags.
A path named "-" indicates that paths should be read from the
standard input.
*`FSTagsCommand.cmd_tagfile(self, argv)`*:
Usage: {cmd} tagfile_path [subcommand ...]
Perform operations on a tag file.
Subcommands:
tag tagset_name {{tag[=value]|-tag}}...
Directly modify tag_name within the tag file tagfile_path.
*`FSTagsCommand.cmd_tagpaths(self, argv)`*:
Usage: {cmd} {{tag[=value]|-tag}} {{-|paths...}}
Tag multiple paths.
With the form "-tag", remove the tag from the immediate tags.
A single path named "-" indicates that paths should be read
from the standard input.
*`FSTagsCommand.cmd_test(self, argv)`*:
Usage: {cmd} [--direct] path {{tag[=value]|-tag}}...
Test whether the path matches all the constraints.
--direct Use direct tags instead of all tags.
*`FSTagsCommand.cmd_xattr_export(self, argv)`*:
Usage: {cmd} {{-|paths...}}
Import tag information from extended attributes.
*`FSTagsCommand.cmd_xattr_import(self, argv)`*:
Usage: {cmd} {{-|paths...}}
Update extended attributes from tags.
*`FSTagsCommand.import_csv_file(self, f, *, convert_name=None)`*:
Import CSV data from the file `f`.
Parameters:
* `f`: the source CSV file
* `convert_name`: a callable to convert each input name
into a file path; the default is to use the input name directly
*`FSTagsCommand.run_context(self)`*:
Push the `FSTags`.
## <a name="FSTagsConfig"></a>Class `FSTagsConfig(cs.fs.FSPathBasedSingleton)`
A configuration for fstags.
*`FSTagsConfig.__init__(self, rcfilepath=None, physical=None)`*:
Initialise the config.
Parameters:
* `rcfilepath`: the path to the confguration file
If `None`, default to `'~/.fstagsrc'` (from `RCFILE`).
*`FSTagsConfig.cascade_rules_from_config(config)`*:
Return a list of the `[cascade]` tag rules from the config.
*`FSTagsConfig.filename_rules_from_config(config)`*:
Return a list of the `[filename_autotag]` tag rules from the config.
*`FSTagsConfig.load_config(rcfilepath)`*:
Read an rc file, return a `ConfigParser` instance.
*`FSTagsConfig.tagsfile_basename`*:
The tags filename, default `'.fstags'`.
## <a name="FSTagsTagFile"></a>Class `FSTagsTagFile(cs.tagset.TagFile, HasFSTagsMixin)`
A `FSTagsTagFile` indexing `TagSet`s for file paths
which lives in the file path's directory.
*`FSTagsTagFile.TagSetClass(self, name: str) -> cs.fstags.TaggedPath`*:
factory to create a `TaggedPath` from a `name`.
*`FSTagsTagFile.dirpath`*:
Return the path of the directory associated with this `FSTagsTagFile`.
## <a name="get_xattr_value"></a>`get_xattr_value(fspath, xattr_name)`
Read the extended attribute `xattr_name` of `fspath`.
Return the extended attribute value as a string,
or `None` if the attribute does not exist.
Parameters:
* `fspath`: the filesystem path to update
* `xattr_name`: the extended attribute to obtain
if this is a `str`, the attribute is the UTF-8 encoding of that name.
## <a name="HasFSTagsMixin"></a>Class `HasFSTagsMixin`
Mixin providing an automatic `.fstags` property.
*`HasFSTagsMixin.fstags`*:
Return the `.fstags` property,
default a shared default `FSTags` instance.
## <a name="is_valid_basename"></a>`is_valid_basename(name: str)`
Test whether `name` is a valid basefile for something in a directory.
## <a name="main"></a>`main(argv=None)`
Command line mode.
## <a name="rsync_patterns"></a>`rsync_patterns(paths, top_path)`
Return a list of rsync include lines
suitable for use with the `--include-from` option.
## <a name="TaggedPath"></a>Class `TaggedPath(cs.tagset.TagSet, HasFSTagsMixin, cs.fs.HasFSPath, cs.deco.Promotable)`
Class to manipulate the tags for a specific filesystem path.
*`TaggedPath.all_tags`*:
Cached cumulative tags for this path as a `TagSet`
by merging the tags from the root to the path.
Note that subsequent changes to some path component's `direct_tags`
will not affect this `TagSet`.
*`TaggedPath.as_tags(self, prefix=None, all_tags=False)`*:
Yield the tag data as `Tag`s.
This overrides `TagSet.as_tags`,
honouring an `optional `all_tags` parameter.
*`TaggedPath.auto_infer(self, attr)`*:
Infer a value from `attr` via the associated `FSTags.cascade_rules`.
This implementation tries the cascade rules from the configuration
and falls back to the superclass inference (the direct tag, if present).
Therefore a tagset with a rule for `.title` and also a
direct `.title` Tag would return the direct tag value for
`.title` and the rule value for `.auto.title`.
*`TaggedPath.basename`*:
The name of the final path component.
*`TaggedPath.cached_value(self, prefix: str, name: str, *, state_func: Optional[Callable[[str], Mapping[str, Any]]] = None) -> 'CachedValue'`*:
Return `CachedValue` managing the `prefix.name` tag.
*`TaggedPath.export_xattrs(self)`*:
Update the extended attributes of the file.
*`TaggedPath.findup(self, check)`*:
Locate the first `TaggedPath` from `self` upwards (via `.parent`)
for which `check(TaggedPath)` is true.
*`TaggedPath.format_kwargs(self, *, direct=False)`*:
Format arguments suitable for `str.format_map`.
This returns an `ExtendedNamespace` from `TagSet.ns()`
for a computed `TagSet`.
In addition to the normal `TagSet.ns()` names
the following additional names are available:
* `fspath.basename`: basename of the `TaggedPath.fspath`
* `fspath.pathname`: the `TaggedPath.fspath`
* `fspath.encoded`: the JSON encoded fspath
* `tags`: the `TagSet` as a string
*`TaggedPath.format_tagset(self, *, direct=False)`*:
Compute a `TagSet` from this file's tags
with additional derived tags.
This can be converted into an `ExtendedNamespace`
suitable for use with `str.format_map`
via the `TagSet`'s `.format_kwargs()` method.
In addition to the normal `TagSet.ns()` names
the following additional names are available:
* `fspath.basename`: basename of the `TaggedPath.fspath`
* `fspath.ext`: the file extension of the basename
of the `TaggedPath.fspath`
* `fspath.pathname`: the `TaggedPath.fspath`
* `fspath.encoded`: the JSON encoded fspath
*`TaggedPath.from_str(fspath, *, fstags: Optional[cs.fstags.FSTags] = <function <lambda> at 0x108b55990>)`*:
Supports the `@promote` decorator.
*`TaggedPath.get_xattr_tagset(self, xattr_name=None)`*:
Return a new `TagSet`
from the extended attribute `xattr_name` of `self.fspath`.
The default `xattr_name` is `XATTR_B` (`None`).
*`TaggedPath.import_xattrs(self)`*:
Update the direct tags from the file's extended attributes.
*`TaggedPath.infer_from_basename(self, rules=None)`*:
Apply `rules` to the basename of this `TaggedPath`,
return a `TagSet` of inferred `Tag`s.
Tag values from earlier rules override values from later rules.
The default rules come from `self.fstags.config.filename_rules`,
which is sourced from `~/.fstagsrc`.
*`TaggedPath.infer_tags(self)`*:
Infer tags for this path.
In order of preference:
* from filesystem fstags
* from file basename matching
* from various `_type` suffixes
* from the cascade rules (see `FSTags.cascade_rules`)
*`TaggedPath.keypath`*:
The key path used to index this `TaggedPath` within its `FSTags`
from `FSTags.keypath(path)`.
*`TaggedPath.merged_tags(self)`*:
Compute the cumulative tags for this path as a new `TagSet`
by merging the tags from the root to the path.
*`TaggedPath.name`*:
The `.name` is `basename(self.fspath)`.
*`TaggedPath.parent`*:
A reference to the parent of this `TaggedPath`, or `None`.
*`TaggedPath.prune_inherited(self)`*:
Examine the tags of this path's parent.
Remove any tag on this file if they are present on the parent.
Return a `TagSet` containing the pruned `Tag`s.
*`TaggedPath.save(self, prune=True)`*:
Update the associated `FSTagsTagFile`.
*`TaggedPath.save_if_closed(self, **save_kw)`*:
Save the tag file is `self._fstags` is closed (no autosave).
*`TaggedPath.set(self, tag_name, value, **kw)`*:
Forbid the special tag name `'name'`, reserved for the filename.
*`TaggedPath.tagfile`*:
Return the `FSTagsTagFile` storing the state for this `TaggedPath`.
*`TaggedPath.update(self, other=None, **update_kw)`*:
Call `TagSet.update` with the `FSTags` open.
## <a name="update_xattr_value"></a>`update_xattr_value(fspath, xattr_name, new_xattr_value)`
Update the extended attributes of `fspath`
with `new_xattr_value` for `xattr_name`.
Return the previous value, or `None` if the attribute was missing.
We avoid calling `os.setxattr` if the value will not change.
Parameters:
* `fspath`: the filesystem path to update
* `xattr_name`: the extended attribute to update;
if this is a `str`, the attribute is the UTF-8 encoding of that name.
* `new_xattr_value`: the new extended attribute value, a `str`
which should be the transcription of `TagSet`
i.e. `str(tagset)`
## <a name="verbose"></a>`verbose(msg, *a)`
Emit message if in verbose mode.
# Release Log
*Release 20241122*:
* FSTags.copy: use atomic_copy2 instead of shutil.copy2.
* FSTagsCommand: rename "-o ontology" to "-O ontology", modernise option specifications.
*Release 20241005*:
Assorted minor changes.
*Release 20240709*:
* New CachedValue class to manage a cached TaggedPath tag value.
* New TaggedPath.cached_value() method to return a CachedValue.
*Release 20240422*:
* Bugfix: .fstags files should no longer get Python repr() output for weirdly typed tag values.
* Some other minor internal updates.
*Release 20240412*:
Changes to accomodate dropping BaseCommandOptions.runstate.
*Release 20240316*:
* TaggedPath.infer_tags: add _dt, _date, _f conversions, skip conversions which raise TypeError or ValueError.
* rpaths: fix to yield relative paths.
*Release 20240211*:
* TaggedPath: subclass Promotable, add from_str(fspath) class method.
* FSTags: new mv(srcpath,dstpath) method to move/link/symlink a file bringing its tags.
*Release 20240201.1*:
Release with "fstags" script.
*Release 20240201*:
FSTags.attach_path: do not save the tagfile if the FSTags is open - the final close will do it.
*Release 20231129*:
FSTags.startup_shutdown: run self.sync() in a finally clause.
*Release 20230407*:
* FSTags: support open/close of self.update_mapping, update startup/shutdown to startup_shutdown.
* Move the (optional) ORM open/close from FSTags.startup_shutdown to TagFile.save, greatly shortens the ORM lock.
*Release 20230217*:
FSTagsCommand.cmd_rename: use -o for the format string as for other commands, -n is for "no action".
*Release 20230212*:
* FSTags.keypath(fspath) and TaggedPath.keypath with the singleton filesystem path for a TaggedPath.
* TaggedPath.parent property.
* TaggedPath.findup(check) method.
* FSTagsCommand: cmd_find,cmd_ls: abort if runstate.cancelled thus honouring SIGINT/^C.
*Release 20230211*:
FSTags.__init__: treat empty $FSTAGS_UPDATE_MAPPING as missing i.e. None.
*Release 20230210*:
New optional update_mapping for mirroring tags eg to an SQLTags; activated automatically by an $FSTAGS_UPDATE_MAPPING environment variable.
*Release 20221228*:
TaggedPath.save: new options prune=True parameter to drop empty top level dict/lists.
*Release 20220918*:
* FSTagsConfig: add empty .provided dict for config overrides.
* FSTagsConfig: set FSPATH_DEFAULT=RCFILE for use by FSPathBasedSingleton._singleton_key.
* FSTagsConfig: accept optional `physical` parameter to choose `realpath` over `abspath` and new `.physical` property.
* FSTags.__getitem__: use `abspath` or `realpath` depending on `self.config.physical`.
* FSTagsCommand: new -P option for "physical" mode, plumb though to the config and self.options.
* Provide a DEFAULT_FSTAGS instance and an @uses_fstags decorator.
*Release 20220606*:
FSTagsCommand.edit: mention the filename in the header comments in tagset edit mode.
*Release 20220430*:
Minor bugfixes.
*Release 20220311*:
* New TaggedPath.infer_tags() method to compute and return the inferred TagSet.
* New "fstags infer pathname" command.
*Release 20211212*:
* Rename edit_many to edit_tagsets for clarity.
* FSTags.edit_dirpath: include realpath(dirpath) at the top of the edit list.
*Release 20210906*:
* TaggedPath: new auto_infer method overriding the inherited TagSet.auto_infer which consults the cascade_rules from the .fstagsrc.
* fstags ls: new -l option to print a multiline tag listing.
* fstags cptags: copy the tags from one path to another.
* Assorted other changes.
*Release 20210404*:
* FSTags.edit_dirpath: new all_names parameter to include dot-names.
* FSTagsCommand.cmd_edit: new -a option to turn on the all_names parameter.
*Release 20210306*:
* FSTags: new tagfile_for(filepath) to obtain the TagFile for filepath.
* FSTagsCommand: new -o ontology option to supply an ontology file for the FSTags.
* FSTagsCommand.cmd_ont: drop -o/--ontology, superceded by global -o option.
* Move BaseTagFile from cs.fstags to TagFile in cs.tagset.
* FSTags.edit_dirpath: we now get (old_name,new_name,TaggedPath) back from edit_many, obviating the te_id_map.
* TaggedPath: .name property returning basename(self.filepath), .set and .discard methods rejecting use of the 'name' tag.
* FSTagsCommand: port to new cs.cmdutils API.
* Many small refactors and bugfixes.
*Release 20200717.1*:
Add the manual page MarkDown source files. Note: well out of date, need updating.
*Release 20200717*:
DISTINFO: require cs.obj>=20200716 for SingletonMixin API change.
*Release 20200716*:
* Update for changed cs.obj.SingletonMixin API.
* fstags: new "export" and "import" subcommands roughly paralleling those from "sqltags", providing CSV formatted export/import.
* fstags export: ew -a (all paths) option - the default is not to not export paths with no tags.
*Release 20200521.1*:
fix DISTINFO.install_requires
*Release 20200521*:
* Add -i option to cp,ln,mv for command line compatibility, just disables -f.
* New "rename" subcommand to rename files according to a format string.
* Ontology support (optional).
* Various classes are now singletons to avoid dissonance.
* Fold "edittags" subcommand into "edit" via the "-d" (directories like files) option.
* New "ns" subcommand reporting on the primary names available for formatting.
* Accept [clausename]entryname as a format string to obtain the string from that entry of the config file.
* Many bugfixes and improvements.
*Release 20200229*:
* New TaggedPath.modified property aliasing the TagSet.modified attribute.
* ls: new -d option to treat directories like files (do not recurse), aiding reporting of tags for a directory.
* find,ls subcommands: work off the realpath of the supplied top level path.
* Tag: now subclasses namedtuple.
* Rewrite rpaths() to use scandir and to also yield (is_dir,path) tuples.
* TagSet, Tag, TagChoice moved into new cs.tagset module for reuse.
* json_import: make --prefix mandatory, is "." as separator if not empty.
* Move filename regexp rules to [filename_rules] config section.
* New CascadeRule for representing a "target_tag_name = tag_name1 tag_name2..." config rules.
* autotag: include the cascade rules in the autotagging after the filename rules.
*Release 20200210*:
* New "json_import" subcommand to import a JSON dict as tags, initial use case to load the metadata from youtube-dl.
* New "scrub" command line operation, to purge tags of paths which do not exist.
* New "cp", "ln" and "mv" subcommands to copy/link/move paths and take their tags with them.
* New "test" subcommand to test paths against tag criteria, useful for find and scripts.
* Small bugfixes.
*Release 20200130*:
* New FSTagsConfig class which parses the .fstagsrc as a .ini file; related adjustments.
* New HasFSTagsMixin presenting a settable .fstags property with a shared default.
* New xattr_import and xattr_export subcommands, remove implicit xattr access/update from other operations.
* New TagSet.__len__ returning the number of tags.
* Add "-" support for stdin to "tag" and "tagpaths" subcommands.
*Release 20200113.2*:
FSTagsCommand docstring tweak.
*Release 20200113.1*:
Small docstring updates.
*Release 20200113*:
Mirror tags to user.cs.fstags xattr to honour Linux namespace requirements. Add "filesize" to available tag string format (-o option). Small bugfixes.
*Release 20191230*:
* Command line: new "find" command to search a file tree based on tags.
* Command line: new "mv" command to move a file and its tags.
* Command line: Python string formats for "find" and "ls" output.
* TaggedPath.autotag: new optional `no_save` parameter, default False, to suppress update of the associated .fstags file.
* Inital and untested "mirror tags to xattrs" support.
*Release 20191201*:
New "edit" subcommand to rename files and edit tags.
*Release 20191130.1*:
Initial release: fstags, filesystem based tagging utility.
Raw data
{
"_id": null,
"home_page": null,
"name": "cs-fstags",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python3",
"author": null,
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/51/1e/a2c17885261d48d41699ccc4da64ae4aa6ea234c9a87454ae50a9e47afb2/cs_fstags-20241122.tar.gz",
"platform": null,
"description": "Simple filesystem based file tagging\nand the associated `fstags` command line script.\n\n*Latest release 20241122*:\n* FSTags.copy: use atomic_copy2 instead of shutil.copy2.\n* FSTagsCommand: rename \"-o ontology\" to \"-O ontology\", modernise option specifications.\n\nMany basic tasks can be performed with the `fstags` command line utility,\ndocumented under the `FSTagsCommand` class below.\n\nWhy `fstags`?\nBy storing the tags in a separate file we:\n* can store tags without modifying a file\n* do not need to know the file's format,\n or even whether that format supports metadata\n* can process tags on any kind of file\n* because tags are inherited from parent directories,\n tags can be automatically acquired merely by arranging your file tree\n\nTags are stored in the file `.fstags` in each directory;\nthere is a line for each entry in the directory\nconsisting of the directory entry name and the associated tags.\n\nTags may be \"bare\", or have a value.\nIf there is a value it is expressed with an equals (`'='`)\nfollowed by the JSON encoding of the value.\n\nThe tags for a file are the union of its direct tags\nand all relevant ancestor tags,\nwith priority given to tags closer to the file.\n\nFor example, a media file for a television episode with the pathname\n`/path/to/series-name/season-02/episode-name--s02e03--something.mp4`\nmight have the tags:\n\n series_title=\"Series Full Name\"\n season=2\n sf\n episode=3\n episode_title=\"Full Episode Title\"\n\nobtained from the following `.fstags` entries:\n* tag file `/path/to/.fstags`:\n\n series-name sf series_title=\"Series Full Name\"\n\n* tag file `/path/to/series-name/.fstags`:\n\n season-02 season=2\n\n* tag file `/path/to/series-name/season-02/.fstags`:\n\n episode-name--s02e03--something.mp4 episode=3 episode_title=\"Full Episode Title\"\n\n## `fstags` Examples ##\n\n### Backing up a media tree too big for the removable drives ###\n\nWalk the media tree for files tagged for backup to `archive2`:\n\n fstags find /path/to/media backup=archive2\n\nWalk the media tree for files not assigned to a backup archive:\n\n fstags find /path/to/media -backup\n\nBackup the `archive2` files using `rsync`:\n\n fstags find --for-rsync /path/to/media backup=archive2 \\\n | rsync -ia --include-from=- /path/to/media /path/to/backup_archive2\n\n## <a name=\"CachedValue\"></a>Class `CachedValue`\n\nManage a cached value stored in a `TaggedPath`.\nThe value and the validity state are stored in a prefixed\nsubsection of the tags.\n\nThis is how modules like `cs.hashindex` cache file content hashcodes.\n\nThe default state function is `TaggedPath.stat_size_mtime`,\nwhich returns `{'st_size':st_size,'st_mtime':int(st_mtime)}` by default,\nessentially the same criteria used by `rsync(1)` to skip\ncomparing file contents.\n\nExample:\n\n tags = fstags[fspath]\n hash\n\n*`CachedValue.__init__(self, taggedpath: cs.fstags.TaggedPath, prefix: str, name: str, *, state_func: Optional[Callable[[str], Mapping[str, Any]]] = None)`*:\nInitialise a cached value reference.\n\nParameters:\n* `taggedpath`: the `TaggedPath` tagged file system path\n* `prefix`: the tags prefix\n* `name`: the tag name for the value\n* `state_func`; an optional function to compute the current\n state if `taggedpath`; the default is\n `CachedValue.stat_size_mtime` which returns the current\n file `st_size` and `st_mtime`\n\n*`CachedValue.get(self) -> Tuple[Optional[Any], Mapping[str, Any]]`*:\nGet the cached value if the current state matches the cache\nstate, otherwise `None`.\nReturn the valu or `None` and the current state.\n\n*`CachedValue.set(self, value: Any, *, state: Mapping = None)`*:\nUpdate the cached value and associated state.\nIf the state is omitted, the current state is used.\n\n*`CachedValue.stat_size_mtime(fspath: str, round_mtime=<class 'int'>, follow_symlinks=True) -> dict`*:\nReturn the default cache state mapping.\nThis function `stat`s the `fspath` and returns `{'size':st_size,'mtime':int(st_mtime)}`.\n\n## <a name=\"CascadeRule\"></a>Class `CascadeRule`\n\nA cascade rule of possible source tag names to provide a target tag.\n\n*`CascadeRule.infer_tag(self, tagset)`*:\nApply the rule to the `TagSet` `tagset`.\nReturn a new `Tag(self.target,value)`\nfor the first cascade `value` found in `tagset`,\nor `None` if there is no match.\n\n## <a name=\"DEFAULT_FSTAGS\"></a>`DEFAULT_FSTAGS = FSTags('.fstags')`\n\nA class to examine filesystem tags.\n\n## <a name=\"FSTags\"></a>Class `FSTags(cs.resources.MultiOpenMixin)`\n\nA class to examine filesystem tags.\n\n*`FSTags.__init__(self, tagsfile_basename=None, ontology_filepath=None, physical=None, update_mapping: Optional[Mapping] = None, update_prefix: Optional[str] = 'cs.fstags', update_uuid_tag_name: Optional[str] = 'uuid')`*:\nInitialise the `FSTags` instance.\n\nParameters:\n* `tagsfile_basename`: optional basename forthe backing tags files,\n default from `TAGSFILE_BASENAME`: `'.fstags'`\n* `ontology_filepath`: optional filesystem path for an associated ontology\n* `physical`: optional flag for the associated `FSTagsConfig`\n specifying whether `TagFile`s are indexed by their physical or logical\n filesystem paths\n* `update_mapping`: optional secondary mapping to which to mirror\n tags, such as an `SQLTags`;\n the default comes from an `SQLTags` specified by the\n environment variable `$FSTAGS_UPDATE_MAPPING`\n if present\n* `update_prefix`: optional key prefix for use in the secondary mapping;\n the default comes from the environment variable\n `$FSTAGS_UPDATE_MAPPING_PREFIX` if present,\n otherwise `'cs.fstags'`\n* `update_uuid_tag_name`: optional name for the per file UUID tag name;\n default `'uuid'`\n\n*`FSTags.__getitem__(self, path) -> 'TaggedPath'`*:\nReturn the `TaggedPath` for `abspath(path)`.\n\n*`FSTags.apply_tag_choices(self, tag_choices, paths)`*:\nApply the `tag_choices` to `paths`.\n\nParameters:\n* `tag_choices`:\n an iterable of `Tag` or an equality `TagBasedTest`.\n Each item applies or removes a `Tag`\n from each path's direct tags.\n* `paths`:\n an iterable of filesystem paths.\n\n*`FSTags.attach_path(self, attach, srcpath, dstpath, *, force=False, crop_ok=False)`*:\nAttach `srcpath` to `dstpath` using the `attach` callable.\n\nParameters:\n* `attach`: callable accepting `attach(srcpath,dstpath)`\n to do the desired attachment,\n such as a copy, link or move\n* `srcpath`: the source filesystem object\n* `dstpath`: the destination filesystem object\n* `crop_ok`: if true and the OS raises `OSError(ENAMETOOLONG)`\n attempt to crop the name before the file extension and retry\n* `force`: default `False`.\n If true and the destination exists\n try to remove it before calling `attach`.\n Otherwise if the destination exists\n raise a `ValueError`.\n\n*`FSTags.cascade_tags(self, tags, cascade_rules=None)`*:\nYield `Tag`s\nwhich cascade from the `TagSet` `tags`\nvia `cascade_rules` (an iterable of `CascadeRules`).\n\n*`FSTags.copy(self, srcpath, dstpath, **kw)`*:\nCopy `srcpath` to `dstpath`.\n\n*`FSTags.dir_tagfile(self, dirpath: str) -> 'FSTagsTagFile'`*:\nReturn the `FSTagsTagFile` associated with `dirpath`.\n\n*`FSTags.edit_dirpath(self, dirpath, all_names=False)`*:\nEdit the filenames and tags in a directory.\n\nIf `all_names` is true, include names commencing with a dot,\notherwise exclude them.\n\n*`FSTags.export_xattrs(self, paths)`*:\nImport the extended attributes of `paths`\nand use them to update the fstags.\n\n*`FSTags.find(self, path, tag_tests, use_direct_tags=False)`*:\nWalk the file tree from `path`\nsearching for files matching the supplied `tag_tests`.\nYield the matching file paths.\n\nParameters:\n* `path`: the top of the file tree to walk\n* `tag_tests`: a sequence of `TagBasedTest`s\n* `use_direct_tags`: test the `direct_tags` if true,\n otherwise the `all_tags`.\n Default: `False`\n\n*`FSTags.find_ontology(self, dirpath, ontbase=None)`*:\nLocate an ontology for the directory `dirpath`.\nThe optional `ontbase` may override the relative path to the file,\ndefault is `self.ontology_filepath`.\nReturn a `TagOntology` or `None` if not found.\n\n*`FSTags.find_ontpath(self, dirpath, ontbase=None)`*:\nLocate an ontology file for the directory `dirpath`.\nThe optional `ontbase` may override the relative path to the file,\ndefault is `self.ontology_filepath`.\nReturn the found ontology file or `None` if not found.\n\n*`FSTags.import_xattrs(self, paths)`*:\nUpdate the extended attributes of `paths`\nfrom their fstags.\n\n*`FSTags.keypath(self, fspath)`*:\nCompute the absolute path used to index a `TaggedPath` instance.\n\nThis returns `realpath(fspath)` if `self.config.physical`,\notherwise `abspath(fspath)`.\n\n*`FSTags.link(self, srcpath, dstpath, **kw)`*:\nLink `srcpath` to `dstpath`.\n\n*`FSTags.move(self, srcpath, dstpath, **kw)`*:\nMove `srcpath` to `dstpath`.\n\n*`FSTags.mv(self, srcpath: str, dstpath: str, *, symlink=False, remove=True)`*:\nMove (or link or symlink) `srcpath` to `dstpath`.\n\nParameters:\n* `srcpath`: the source filesystem path\n* `dstpath`: the destination filesystem path\n* `symlink`: default `False`: if true, make a symbolic link\n* `remove`: default `True`: if true, remove `srcpath` after\n hard linking to `dstpath`\n\n*`FSTags.ontology`*:\nThe primary `TagsOntology`, or `None` if `self.ontology_filepath` was `None`.\n\n*`FSTags.ontology_filepath`*:\nThe ontology file basename.\n\n*`FSTags.ontology_for(self, path, ontbase=None)`*:\nReturn the `TagsOntology` associated with `path`.\nReturns `None` if an ontology cannot be found.\n\n*`FSTags.open_ontology(self, ontpath)`*:\nOpen the contology file at `ontpath`.\n\n*`FSTags.path_tagfiles(self, fspath)`*:\nGenerator yielding a sequence of `(FSTagsTagFile,name)` pairs\nwhere `name` is the key within the `FSTagsTagFile`\nfor the `FSTagsTagFile`s affecting `fspath`\nin order from the root to `dirname(fspath)`.\n\n*`FSTags.resolve_format_string(self, format_string)`*:\nSee if `format_string` looks like `[`*clausename*`]`*entryname*.\nif so, return the corresponding config entry string,\notherwise return `format_string` unchanged.\n\n*`FSTags.scrub(self, path)`*:\nScrub tags for names which do not exist in the filesystem.\n\n*`FSTags.startup_shutdown(self)`*:\nSync tag files and db mapping on final close.\n\n*`FSTags.sync(self)`*:\nFlush modified tag files.\n\n*`FSTags.tagfile_for(self, fspath)`*:\nReturn the `FSTagsTagFile` storing the `Tag`s for `fspath`.\n\n*`FSTags.tagsfile_basename`*:\nThe tag file basename.\n\n*`FSTags.test(self, path, tag_tests, use_direct_tags=False)`*:\nTest a path against `tag_tests`.\n\nParameters:\n* `path`: path to test\n* `tag_tests`: an iterable of `TagBasedTest`s\n* `use_direct_tags`: test the `direct_tags` if true,\n otherwise the `all_tags`.\n Default: `False`\n\n## <a name=\"FSTagsCommand\"></a>Class `FSTagsCommand(cs.cmdutils.BaseCommand, cs.tagset.TagsCommandMixin)`\n\n\n\nUsage summary:\n\n Usage: fstags [common-options...] [-o ontology] [-P] subcommand [...]\n Work with fstags.\n Subcommands:\n autotag [common-options...] paths...\n Tag paths based on rules from the rc file.\n cp [common-options...] [-finv] srcpath dstpath, cp [common-options...] [-finv] srcpaths... dstdirpath\n POSIX cp(1) equivalent, but also copying tags: copy files and their tags into targetdir.\n -f Force: remove destination if it exists.\n -i Interactive: fail if the destination exists.\n -n No remove: fail if the destination exists.\n -v Verbose: show copied files.\n cptags [common-options...] srcpath dstpath\n Copy the direct tags from srcpath to dstpath.\n edit [common-options...] [-ad] [path]\n Edit the direct tagsets of path, default: '.'.\n If path is a directory, provide the tags of its entries.\n Otherwise edit just the tags for path.\n -a List all names in directory edit mode; normally\n names commencing with a dot are omitted.\n -d Treat directories like files: edit just its tags.\n export [common-options...] [-a] [--direct] path {tag[=value]|-tag}...\n Export tags for files from paths matching all the constraints.\n -a Export all paths, not just those with tags.\n --direct Export the direct tags instead of the computed tags.\n The output is in the same CSV format as that from \"sqltags export\",\n with the following columns:\n * unixtime: the file's st_mtime from os.stat.\n * id: empty\n * name: the file path\n * tags: the file's direct or indirect tags\n find [common-options...] [--direct] [--for-rsync] [-o output_format] path {tag[=value]|-tag}...\n List files from path matching all the constraints.\n --direct Use direct tags instead of all tags.\n --for-rsync Instead of listing matching paths, emit a\n sequence of rsync(1) patterns suitable for use with\n --include-from in order to do a selective rsync of the\n matched paths.\n -o output_format\n Use output_format as a Python format string to lay out\n the listing.\n Default: {fspath}\n help [common-options...] [-l] [-s] [subcommand-names...]\n Print help for subcommands.\n This outputs the full help for the named subcommands,\n or the short help for all subcommands if no names are specified.\n -l Long help.\n -r Recurse into subcommands.\n -s Short help.\n import [common-options...] {-|srcpath}...\n Import CSV data in the format emitted by \"export\".\n Each argument is a file path or \"-\", indicating standard input.\n infer [common-options...] pathname\n Print the base and inferred tags for pathname.\n info [common-options...] [field-names...]\n Recite general information.\n Explicit field names may be provided to override the default listing.\n json_import --prefix=tag_prefix {-|path} {-|tags.json}\n Apply JSON data to path.\n A path named \"-\" indicates that paths should be read from\n the standard input.\n The JSON tag data come from the file \"tags.json\"; the name\n \"-\" indicates that the JSON data should be read from the\n standard input.\n ln [common-options...] [-finv] srcpath dstpath, ln [common-options...] [-finv] srcpaths... dstdirpath\n POSIX ln(1) equivalent, but also copying the tags: link files and their tags into targetdir.\n -f Force: remove destination if it exists.\n -i Interactive: fail if the destination exists.\n -n No remove: fail if the destination exists.\n -v Verbose: show linked files.\n ls [common-options...] [-dlr] [--direct] [-o output_format] [paths...]\n List files from paths and their tags.\n -d Treat directories like files, do not recurse.\n --direct List direct tags instead of all tags.\n -l Long format.\n -o output_format\n Use output_format as a Python format string to lay out\n the listing.\n Default: {fspath:json} {tags}\n -r Recurse into subdirectories.\n mv [common-options...] [-finv] srcpath dstpath, mv [common-options...] [-finv] srcpaths... dstdirpath\n POSIX mv(1) equivalent, but also copying the tags: move files and their tags into targetdir.\n -f Force: remove destination if it exists.\n -i Interactive: fail if the destination exists.\n -n No remove: fail if the destination exists.\n -v Verbose: show moved files.\n ns [common-options...] [-d] [--direct] [paths...]\n Report on the available primary namespace fields for formatting.\n Note that because the namespace used for formatting has\n inferred field names there are also unshown secondary field\n names available in format strings.\n -d Treat directories like files, do not recurse.\n --direct List direct tags instead of all tags.\n ont [common-options...] [subcommand [args...]]\n With no arguments, print the ontology.\n rename [common-options...] -o basename_format paths...\n Rename paths according to a format string.\n -o basename_format\n Use basename_format as a Python format string to\n compute the new basename for each path.\n scrub [common-options...] paths...\n Remove all tags for missing paths.\n If a path is a directory, scrub the immediate paths in the directory.\n shell [common-options...]\n Run a command prompt via cmd.Cmd using this command's subcommands.\n tag [common-options...] {-|path} {tag[=value]|-tag}...\n Tag a path with multiple tags.\n With the form \"-tag\", remove that tag from the direct tags.\n A path named \"-\" indicates that paths should be read from the\n standard input.\n tagfile [common-options...] tagfile_path [subcommand ...]\n Perform operations on a tag file.\n Subcommands:\n tag tagset_name {tag[=value]|-tag}...\n Directly modify tag_name within the tag file tagfile_path.\n tagpaths [common-options...] {tag[=value]|-tag} {-|paths...}\n Tag multiple paths.\n With the form \"-tag\", remove the tag from the immediate tags.\n A single path named \"-\" indicates that paths should be read\n from the standard input.\n test [common-options...] [--direct] path {tag[=value]|-tag}...\n Test whether the path matches all the constraints.\n --direct Use direct tags instead of all tags.\n xattr-export [common-options...] {-|paths...}\n Import tag information from extended attributes.\n xattr-import [common-options...] {-|paths...}\n Update extended attributes from tags.\n\n*`FSTagsCommand.Options`*\n\n*`FSTagsCommand.cmd_autotag(self, argv, *, upd: cs.upd.Upd, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x108b55fc0>)`*:\nUsage: {cmd} paths...\nTag paths based on rules from the rc file.\n\n*`FSTagsCommand.cmd_cp(self, argv)`*:\nUsage: {cmd} [-finv] srcpath dstpath, {cmd} [-finv] srcpaths... dstdirpath\nPOSIX cp(1) equivalent, but also copying tags: copy files and their tags into targetdir.\n-f Force: remove destination if it exists.\n-i Interactive: fail if the destination exists.\n-n No remove: fail if the destination exists.\n-v Verbose: show copied files.\n\n*`FSTagsCommand.cmd_cptags(self, argv)`*:\nUsage: {cmd} srcpath dstpath\nCopy the direct tags from srcpath to dstpath.\n\n*`FSTagsCommand.cmd_edit(self, argv)`*:\nUsage: {cmd} [-ad] [path]\nEdit the direct tagsets of path, default: '.'.\nIf path is a directory, provide the tags of its entries.\nOtherwise edit just the tags for path.\n-a List all names in directory edit mode; normally\n names commencing with a dot are omitted.\n-d Treat directories like files: edit just its tags.\n\n*`FSTagsCommand.cmd_export(self, argv, *, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x108b56440>)`*:\nUsage: {cmd} [-a] [--direct] path {{tag[=value]|-tag}}...\nExport tags for files from paths matching all the constraints.\n-a Export all paths, not just those with tags.\n--direct Export the direct tags instead of the computed tags.\nThe output is in the same CSV format as that from \"sqltags export\",\nwith the following columns:\n* unixtime: the file's st_mtime from os.stat.\n* id: empty\n* name: the file path\n* tags: the file's direct or indirect tags\n\n*`FSTagsCommand.cmd_find(self, argv, *, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x108b565f0>)`*:\nUsage: {cmd} [--direct] [--for-rsync] [-o output_format] path {{tag[=value]|-tag}}...\nList files from path matching all the constraints.\n--direct Use direct tags instead of all tags.\n--for-rsync Instead of listing matching paths, emit a\n sequence of rsync(1) patterns suitable for use with\n --include-from in order to do a selective rsync of the\n matched paths.\n-o output_format\n Use output_format as a Python format string to lay out\n the listing.\n Default: {FIND_OUTPUT_FORMAT_DEFAULT}\n\n*`FSTagsCommand.cmd_import(self, argv)`*:\nUsage: {cmd} {{-|srcpath}}...\nImport CSV data in the format emitted by \"export\".\nEach argument is a file path or \"-\", indicating standard input.\n\n*`FSTagsCommand.cmd_infer(self, argv)`*:\nUsage: {cmd} pathname\nPrint the base and inferred tags for pathname.\n\n*`FSTagsCommand.cmd_json_import(self, argv)`*:\nUsage: json_import --prefix=tag_prefix {{-|path}} {{-|tags.json}}\nApply JSON data to path.\nA path named \"-\" indicates that paths should be read from\nthe standard input.\nThe JSON tag data come from the file \"tags.json\"; the name\n\"-\" indicates that the JSON data should be read from the\nstandard input.\n\n*`FSTagsCommand.cmd_ln(self, argv)`*:\nUsage: {cmd} [-finv] srcpath dstpath, {cmd} [-finv] srcpaths... dstdirpath\nPOSIX ln(1) equivalent, but also copying the tags: link files and their tags into targetdir.\n-f Force: remove destination if it exists.\n-i Interactive: fail if the destination exists.\n-n No remove: fail if the destination exists.\n-v Verbose: show linked files.\n\n*`FSTagsCommand.cmd_ls(self, argv, *, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x108b569e0>)`*:\nUsage: {cmd} [-dlr] [--direct] [-o output_format] [paths...]\nList files from paths and their tags.\n-d Treat directories like files, do not recurse.\n--direct List direct tags instead of all tags.\n-l Long format.\n-o output_format\n Use output_format as a Python format string to lay out\n the listing.\n Default: {LS_OUTPUT_FORMAT_DEFAULT}\n-r Recurse into subdirectories.\n\n*`FSTagsCommand.cmd_mv(self, argv)`*:\nUsage: {cmd} [-finv] srcpath dstpath, {cmd} [-finv] srcpaths... dstdirpath\nPOSIX mv(1) equivalent, but also copying the tags: move files and their tags into targetdir.\n-f Force: remove destination if it exists.\n-i Interactive: fail if the destination exists.\n-n No remove: fail if the destination exists.\n-v Verbose: show moved files.\n\n*`FSTagsCommand.cmd_ns(self, argv, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x108b56dd0>)`*:\nUsage: {cmd} [-d] [--direct] [paths...]\nReport on the available primary namespace fields for formatting.\nNote that because the namespace used for formatting has\ninferred field names there are also unshown secondary field\nnames available in format strings.\n-d Treat directories like files, do not recurse.\n--direct List direct tags instead of all tags.\n\n*`FSTagsCommand.cmd_ont(self, argv)`*:\nOntology operations.\n\nUsage: {cmd} [subcommand [args...]]\n With no arguments, print the ontology.\n\n*`FSTagsCommand.cmd_rename(self, argv)`*:\nUsage: {cmd} -o basename_format paths...\nRename paths according to a format string.\n-o basename_format\n Use basename_format as a Python format string to\n compute the new basename for each path.\n\n*`FSTagsCommand.cmd_scrub(self, argv)`*:\nUsage: {cmd} paths...\nRemove all tags for missing paths.\nIf a path is a directory, scrub the immediate paths in the directory.\n\n*`FSTagsCommand.cmd_tag(self, argv)`*:\nUsage: {cmd} {{-|path}} {{tag[=value]|-tag}}...\nTag a path with multiple tags.\nWith the form \"-tag\", remove that tag from the direct tags.\nA path named \"-\" indicates that paths should be read from the\nstandard input.\n\n*`FSTagsCommand.cmd_tagfile(self, argv)`*:\nUsage: {cmd} tagfile_path [subcommand ...]\nPerform operations on a tag file.\nSubcommands:\n tag tagset_name {{tag[=value]|-tag}}...\n Directly modify tag_name within the tag file tagfile_path.\n\n*`FSTagsCommand.cmd_tagpaths(self, argv)`*:\nUsage: {cmd} {{tag[=value]|-tag}} {{-|paths...}}\nTag multiple paths.\nWith the form \"-tag\", remove the tag from the immediate tags.\nA single path named \"-\" indicates that paths should be read\nfrom the standard input.\n\n*`FSTagsCommand.cmd_test(self, argv)`*:\nUsage: {cmd} [--direct] path {{tag[=value]|-tag}}...\nTest whether the path matches all the constraints.\n--direct Use direct tags instead of all tags.\n\n*`FSTagsCommand.cmd_xattr_export(self, argv)`*:\nUsage: {cmd} {{-|paths...}}\nImport tag information from extended attributes.\n\n*`FSTagsCommand.cmd_xattr_import(self, argv)`*:\nUsage: {cmd} {{-|paths...}}\nUpdate extended attributes from tags.\n\n*`FSTagsCommand.import_csv_file(self, f, *, convert_name=None)`*:\nImport CSV data from the file `f`.\n\nParameters:\n* `f`: the source CSV file\n* `convert_name`: a callable to convert each input name\n into a file path; the default is to use the input name directly\n\n*`FSTagsCommand.run_context(self)`*:\nPush the `FSTags`.\n\n## <a name=\"FSTagsConfig\"></a>Class `FSTagsConfig(cs.fs.FSPathBasedSingleton)`\n\nA configuration for fstags.\n\n*`FSTagsConfig.__init__(self, rcfilepath=None, physical=None)`*:\nInitialise the config.\n\nParameters:\n* `rcfilepath`: the path to the confguration file\n If `None`, default to `'~/.fstagsrc'` (from `RCFILE`).\n\n*`FSTagsConfig.cascade_rules_from_config(config)`*:\nReturn a list of the `[cascade]` tag rules from the config.\n\n*`FSTagsConfig.filename_rules_from_config(config)`*:\nReturn a list of the `[filename_autotag]` tag rules from the config.\n\n*`FSTagsConfig.load_config(rcfilepath)`*:\nRead an rc file, return a `ConfigParser` instance.\n\n*`FSTagsConfig.tagsfile_basename`*:\nThe tags filename, default `'.fstags'`.\n\n## <a name=\"FSTagsTagFile\"></a>Class `FSTagsTagFile(cs.tagset.TagFile, HasFSTagsMixin)`\n\nA `FSTagsTagFile` indexing `TagSet`s for file paths\nwhich lives in the file path's directory.\n\n*`FSTagsTagFile.TagSetClass(self, name: str) -> cs.fstags.TaggedPath`*:\nfactory to create a `TaggedPath` from a `name`.\n\n*`FSTagsTagFile.dirpath`*:\nReturn the path of the directory associated with this `FSTagsTagFile`.\n\n## <a name=\"get_xattr_value\"></a>`get_xattr_value(fspath, xattr_name)`\n\nRead the extended attribute `xattr_name` of `fspath`.\nReturn the extended attribute value as a string,\nor `None` if the attribute does not exist.\n\nParameters:\n* `fspath`: the filesystem path to update\n* `xattr_name`: the extended attribute to obtain\n if this is a `str`, the attribute is the UTF-8 encoding of that name.\n\n## <a name=\"HasFSTagsMixin\"></a>Class `HasFSTagsMixin`\n\nMixin providing an automatic `.fstags` property.\n\n*`HasFSTagsMixin.fstags`*:\nReturn the `.fstags` property,\ndefault a shared default `FSTags` instance.\n\n## <a name=\"is_valid_basename\"></a>`is_valid_basename(name: str)`\n\nTest whether `name` is a valid basefile for something in a directory.\n\n## <a name=\"main\"></a>`main(argv=None)`\n\nCommand line mode.\n\n## <a name=\"rsync_patterns\"></a>`rsync_patterns(paths, top_path)`\n\nReturn a list of rsync include lines\nsuitable for use with the `--include-from` option.\n\n## <a name=\"TaggedPath\"></a>Class `TaggedPath(cs.tagset.TagSet, HasFSTagsMixin, cs.fs.HasFSPath, cs.deco.Promotable)`\n\nClass to manipulate the tags for a specific filesystem path.\n\n*`TaggedPath.all_tags`*:\nCached cumulative tags for this path as a `TagSet`\nby merging the tags from the root to the path.\n\nNote that subsequent changes to some path component's `direct_tags`\nwill not affect this `TagSet`.\n\n*`TaggedPath.as_tags(self, prefix=None, all_tags=False)`*:\nYield the tag data as `Tag`s.\n\nThis overrides `TagSet.as_tags`,\nhonouring an `optional `all_tags` parameter.\n\n*`TaggedPath.auto_infer(self, attr)`*:\nInfer a value from `attr` via the associated `FSTags.cascade_rules`.\n\nThis implementation tries the cascade rules from the configuration\nand falls back to the superclass inference (the direct tag, if present).\nTherefore a tagset with a rule for `.title` and also a\ndirect `.title` Tag would return the direct tag value for\n`.title` and the rule value for `.auto.title`.\n\n*`TaggedPath.basename`*:\nThe name of the final path component.\n\n*`TaggedPath.cached_value(self, prefix: str, name: str, *, state_func: Optional[Callable[[str], Mapping[str, Any]]] = None) -> 'CachedValue'`*:\nReturn `CachedValue` managing the `prefix.name` tag.\n\n*`TaggedPath.export_xattrs(self)`*:\nUpdate the extended attributes of the file.\n\n*`TaggedPath.findup(self, check)`*:\nLocate the first `TaggedPath` from `self` upwards (via `.parent`)\nfor which `check(TaggedPath)` is true.\n\n*`TaggedPath.format_kwargs(self, *, direct=False)`*:\nFormat arguments suitable for `str.format_map`.\n\nThis returns an `ExtendedNamespace` from `TagSet.ns()`\nfor a computed `TagSet`.\n\nIn addition to the normal `TagSet.ns()` names\nthe following additional names are available:\n* `fspath.basename`: basename of the `TaggedPath.fspath`\n* `fspath.pathname`: the `TaggedPath.fspath`\n* `fspath.encoded`: the JSON encoded fspath\n* `tags`: the `TagSet` as a string\n\n*`TaggedPath.format_tagset(self, *, direct=False)`*:\nCompute a `TagSet` from this file's tags\nwith additional derived tags.\n\nThis can be converted into an `ExtendedNamespace`\nsuitable for use with `str.format_map`\nvia the `TagSet`'s `.format_kwargs()` method.\n\nIn addition to the normal `TagSet.ns()` names\nthe following additional names are available:\n* `fspath.basename`: basename of the `TaggedPath.fspath`\n* `fspath.ext`: the file extension of the basename\n of the `TaggedPath.fspath`\n* `fspath.pathname`: the `TaggedPath.fspath`\n* `fspath.encoded`: the JSON encoded fspath\n\n*`TaggedPath.from_str(fspath, *, fstags: Optional[cs.fstags.FSTags] = <function <lambda> at 0x108b55990>)`*:\nSupports the `@promote` decorator.\n\n*`TaggedPath.get_xattr_tagset(self, xattr_name=None)`*:\nReturn a new `TagSet`\nfrom the extended attribute `xattr_name` of `self.fspath`.\nThe default `xattr_name` is `XATTR_B` (`None`).\n\n*`TaggedPath.import_xattrs(self)`*:\nUpdate the direct tags from the file's extended attributes.\n\n*`TaggedPath.infer_from_basename(self, rules=None)`*:\nApply `rules` to the basename of this `TaggedPath`,\nreturn a `TagSet` of inferred `Tag`s.\n\nTag values from earlier rules override values from later rules.\n\nThe default rules come from `self.fstags.config.filename_rules`,\nwhich is sourced from `~/.fstagsrc`.\n\n*`TaggedPath.infer_tags(self)`*:\nInfer tags for this path.\n\nIn order of preference:\n* from filesystem fstags\n* from file basename matching\n* from various `_type` suffixes\n* from the cascade rules (see `FSTags.cascade_rules`)\n\n*`TaggedPath.keypath`*:\nThe key path used to index this `TaggedPath` within its `FSTags`\nfrom `FSTags.keypath(path)`.\n\n*`TaggedPath.merged_tags(self)`*:\nCompute the cumulative tags for this path as a new `TagSet`\nby merging the tags from the root to the path.\n\n*`TaggedPath.name`*:\nThe `.name` is `basename(self.fspath)`.\n\n*`TaggedPath.parent`*:\nA reference to the parent of this `TaggedPath`, or `None`.\n\n*`TaggedPath.prune_inherited(self)`*:\nExamine the tags of this path's parent.\nRemove any tag on this file if they are present on the parent.\nReturn a `TagSet` containing the pruned `Tag`s.\n\n*`TaggedPath.save(self, prune=True)`*:\nUpdate the associated `FSTagsTagFile`.\n\n*`TaggedPath.save_if_closed(self, **save_kw)`*:\nSave the tag file is `self._fstags` is closed (no autosave).\n\n*`TaggedPath.set(self, tag_name, value, **kw)`*:\nForbid the special tag name `'name'`, reserved for the filename.\n\n*`TaggedPath.tagfile`*:\nReturn the `FSTagsTagFile` storing the state for this `TaggedPath`.\n\n*`TaggedPath.update(self, other=None, **update_kw)`*:\nCall `TagSet.update` with the `FSTags` open.\n\n## <a name=\"update_xattr_value\"></a>`update_xattr_value(fspath, xattr_name, new_xattr_value)`\n\nUpdate the extended attributes of `fspath`\nwith `new_xattr_value` for `xattr_name`.\nReturn the previous value, or `None` if the attribute was missing.\n\nWe avoid calling `os.setxattr` if the value will not change.\n\nParameters:\n* `fspath`: the filesystem path to update\n* `xattr_name`: the extended attribute to update;\n if this is a `str`, the attribute is the UTF-8 encoding of that name.\n* `new_xattr_value`: the new extended attribute value, a `str`\n which should be the transcription of `TagSet`\n i.e. `str(tagset)`\n\n## <a name=\"verbose\"></a>`verbose(msg, *a)`\n\nEmit message if in verbose mode.\n\n# Release Log\n\n\n\n*Release 20241122*:\n* FSTags.copy: use atomic_copy2 instead of shutil.copy2.\n* FSTagsCommand: rename \"-o ontology\" to \"-O ontology\", modernise option specifications.\n\n*Release 20241005*:\nAssorted minor changes.\n\n*Release 20240709*:\n* New CachedValue class to manage a cached TaggedPath tag value.\n* New TaggedPath.cached_value() method to return a CachedValue.\n\n*Release 20240422*:\n* Bugfix: .fstags files should no longer get Python repr() output for weirdly typed tag values.\n* Some other minor internal updates.\n\n*Release 20240412*:\nChanges to accomodate dropping BaseCommandOptions.runstate.\n\n*Release 20240316*:\n* TaggedPath.infer_tags: add _dt, _date, _f conversions, skip conversions which raise TypeError or ValueError.\n* rpaths: fix to yield relative paths.\n\n*Release 20240211*:\n* TaggedPath: subclass Promotable, add from_str(fspath) class method.\n* FSTags: new mv(srcpath,dstpath) method to move/link/symlink a file bringing its tags.\n\n*Release 20240201.1*:\nRelease with \"fstags\" script.\n\n*Release 20240201*:\nFSTags.attach_path: do not save the tagfile if the FSTags is open - the final close will do it.\n\n*Release 20231129*:\nFSTags.startup_shutdown: run self.sync() in a finally clause.\n\n*Release 20230407*:\n* FSTags: support open/close of self.update_mapping, update startup/shutdown to startup_shutdown.\n* Move the (optional) ORM open/close from FSTags.startup_shutdown to TagFile.save, greatly shortens the ORM lock.\n\n*Release 20230217*:\nFSTagsCommand.cmd_rename: use -o for the format string as for other commands, -n is for \"no action\".\n\n*Release 20230212*:\n* FSTags.keypath(fspath) and TaggedPath.keypath with the singleton filesystem path for a TaggedPath.\n* TaggedPath.parent property.\n* TaggedPath.findup(check) method.\n* FSTagsCommand: cmd_find,cmd_ls: abort if runstate.cancelled thus honouring SIGINT/^C.\n\n*Release 20230211*:\nFSTags.__init__: treat empty $FSTAGS_UPDATE_MAPPING as missing i.e. None.\n\n*Release 20230210*:\nNew optional update_mapping for mirroring tags eg to an SQLTags; activated automatically by an $FSTAGS_UPDATE_MAPPING environment variable.\n\n*Release 20221228*:\nTaggedPath.save: new options prune=True parameter to drop empty top level dict/lists.\n\n*Release 20220918*:\n* FSTagsConfig: add empty .provided dict for config overrides.\n* FSTagsConfig: set FSPATH_DEFAULT=RCFILE for use by FSPathBasedSingleton._singleton_key.\n* FSTagsConfig: accept optional `physical` parameter to choose `realpath` over `abspath` and new `.physical` property.\n* FSTags.__getitem__: use `abspath` or `realpath` depending on `self.config.physical`.\n* FSTagsCommand: new -P option for \"physical\" mode, plumb though to the config and self.options.\n* Provide a DEFAULT_FSTAGS instance and an @uses_fstags decorator.\n\n*Release 20220606*:\nFSTagsCommand.edit: mention the filename in the header comments in tagset edit mode.\n\n*Release 20220430*:\nMinor bugfixes.\n\n*Release 20220311*:\n* New TaggedPath.infer_tags() method to compute and return the inferred TagSet.\n* New \"fstags infer pathname\" command.\n\n*Release 20211212*:\n* Rename edit_many to edit_tagsets for clarity.\n* FSTags.edit_dirpath: include realpath(dirpath) at the top of the edit list.\n\n*Release 20210906*:\n* TaggedPath: new auto_infer method overriding the inherited TagSet.auto_infer which consults the cascade_rules from the .fstagsrc.\n* fstags ls: new -l option to print a multiline tag listing.\n* fstags cptags: copy the tags from one path to another.\n* Assorted other changes.\n\n*Release 20210404*:\n* FSTags.edit_dirpath: new all_names parameter to include dot-names.\n* FSTagsCommand.cmd_edit: new -a option to turn on the all_names parameter.\n\n*Release 20210306*:\n* FSTags: new tagfile_for(filepath) to obtain the TagFile for filepath.\n* FSTagsCommand: new -o ontology option to supply an ontology file for the FSTags.\n* FSTagsCommand.cmd_ont: drop -o/--ontology, superceded by global -o option.\n* Move BaseTagFile from cs.fstags to TagFile in cs.tagset.\n* FSTags.edit_dirpath: we now get (old_name,new_name,TaggedPath) back from edit_many, obviating the te_id_map.\n* TaggedPath: .name property returning basename(self.filepath), .set and .discard methods rejecting use of the 'name' tag.\n* FSTagsCommand: port to new cs.cmdutils API.\n* Many small refactors and bugfixes.\n\n*Release 20200717.1*:\nAdd the manual page MarkDown source files. Note: well out of date, need updating.\n\n*Release 20200717*:\nDISTINFO: require cs.obj>=20200716 for SingletonMixin API change.\n\n*Release 20200716*:\n* Update for changed cs.obj.SingletonMixin API.\n* fstags: new \"export\" and \"import\" subcommands roughly paralleling those from \"sqltags\", providing CSV formatted export/import.\n* fstags export: ew -a (all paths) option - the default is not to not export paths with no tags.\n\n*Release 20200521.1*:\nfix DISTINFO.install_requires\n\n*Release 20200521*:\n* Add -i option to cp,ln,mv for command line compatibility, just disables -f.\n* New \"rename\" subcommand to rename files according to a format string.\n* Ontology support (optional).\n* Various classes are now singletons to avoid dissonance.\n* Fold \"edittags\" subcommand into \"edit\" via the \"-d\" (directories like files) option.\n* New \"ns\" subcommand reporting on the primary names available for formatting.\n* Accept [clausename]entryname as a format string to obtain the string from that entry of the config file.\n* Many bugfixes and improvements.\n\n*Release 20200229*:\n* New TaggedPath.modified property aliasing the TagSet.modified attribute.\n* ls: new -d option to treat directories like files (do not recurse), aiding reporting of tags for a directory.\n* find,ls subcommands: work off the realpath of the supplied top level path.\n* Tag: now subclasses namedtuple.\n* Rewrite rpaths() to use scandir and to also yield (is_dir,path) tuples.\n* TagSet, Tag, TagChoice moved into new cs.tagset module for reuse.\n* json_import: make --prefix mandatory, is \".\" as separator if not empty.\n* Move filename regexp rules to [filename_rules] config section.\n* New CascadeRule for representing a \"target_tag_name = tag_name1 tag_name2...\" config rules.\n* autotag: include the cascade rules in the autotagging after the filename rules.\n\n*Release 20200210*:\n* New \"json_import\" subcommand to import a JSON dict as tags, initial use case to load the metadata from youtube-dl.\n* New \"scrub\" command line operation, to purge tags of paths which do not exist.\n* New \"cp\", \"ln\" and \"mv\" subcommands to copy/link/move paths and take their tags with them.\n* New \"test\" subcommand to test paths against tag criteria, useful for find and scripts.\n* Small bugfixes.\n\n*Release 20200130*:\n* New FSTagsConfig class which parses the .fstagsrc as a .ini file; related adjustments.\n* New HasFSTagsMixin presenting a settable .fstags property with a shared default.\n* New xattr_import and xattr_export subcommands, remove implicit xattr access/update from other operations.\n* New TagSet.__len__ returning the number of tags.\n* Add \"-\" support for stdin to \"tag\" and \"tagpaths\" subcommands.\n\n*Release 20200113.2*:\nFSTagsCommand docstring tweak.\n\n*Release 20200113.1*:\nSmall docstring updates.\n\n*Release 20200113*:\nMirror tags to user.cs.fstags xattr to honour Linux namespace requirements. Add \"filesize\" to available tag string format (-o option). Small bugfixes.\n\n*Release 20191230*:\n* Command line: new \"find\" command to search a file tree based on tags.\n* Command line: new \"mv\" command to move a file and its tags.\n* Command line: Python string formats for \"find\" and \"ls\" output.\n* TaggedPath.autotag: new optional `no_save` parameter, default False, to suppress update of the associated .fstags file.\n* Inital and untested \"mirror tags to xattrs\" support.\n\n*Release 20191201*:\nNew \"edit\" subcommand to rename files and edit tags.\n\n*Release 20191130.1*:\nInitial release: fstags, filesystem based tagging utility.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Simple filesystem based file tagging and the associated `fstags` command line script.",
"version": "20241122",
"project_urls": {
"MonoRepo Commits": "https://bitbucket.org/cameron_simpson/css/commits/branch/main",
"Monorepo Git Mirror": "https://github.com/cameron-simpson/css",
"Monorepo Hg/Mercurial Mirror": "https://hg.sr.ht/~cameron-simpson/css",
"Source": "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/fstags.py"
},
"split_keywords": [
"python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "76a9ad3b349ac0e62344c36230afe1edb1b3803d55693bb50a25ae6d43145734",
"md5": "66acfff218ff206c782786a22cc2bd02",
"sha256": "31bedb0c9eb9905083048077ffb676f2b07008dacfd8612d3455db329f6294ee"
},
"downloads": -1,
"filename": "cs_fstags-20241122-py3-none-any.whl",
"has_sig": false,
"md5_digest": "66acfff218ff206c782786a22cc2bd02",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 31145,
"upload_time": "2024-11-22T09:15:29",
"upload_time_iso_8601": "2024-11-22T09:15:29.882501Z",
"url": "https://files.pythonhosted.org/packages/76/a9/ad3b349ac0e62344c36230afe1edb1b3803d55693bb50a25ae6d43145734/cs_fstags-20241122-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "511ea2c17885261d48d41699ccc4da64ae4aa6ea234c9a87454ae50a9e47afb2",
"md5": "2c78c9888bc3a0cb70a6027bdfc101a8",
"sha256": "ce7b3c262485bde5626e671b1bbffde805c1fe99b45ebeb6e18e6e454e453cfd"
},
"downloads": -1,
"filename": "cs_fstags-20241122.tar.gz",
"has_sig": false,
"md5_digest": "2c78c9888bc3a0cb70a6027bdfc101a8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 69951,
"upload_time": "2024-11-22T09:15:32",
"upload_time_iso_8601": "2024-11-22T09:15:32.182917Z",
"url": "https://files.pythonhosted.org/packages/51/1e/a2c17885261d48d41699ccc4da64ae4aa6ea234c9a87454ae50a9e47afb2/cs_fstags-20241122.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-22 09:15:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cameron-simpson",
"github_project": "css",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cs-fstags"
}
JSON
