The filerecords core

Note

These are techincal records for other utility submodules of filerecords. They are of no further concern to the user.

API

filerecords.api.base module

This is the base class for the filerecords API classes.

Note

This is not intended to be used directly.

class filerecords.api.base.BaseRecord(filename: Optional[str] = None, metadata: Optional[dict] = None)

Bases: object

The basic record handling class for storing metadata.

Parameters

• filename (str) – The yaml file storing the record metadata.

• metadata (dict) – The metadata of the record.

add_comment(comment: str)

Add a comment to the registry.

Note

This will not automatically save the metadata, use the save() method to do so.

Parameters

comment (str) – The comment to add.

add_flags(flag: str)

Add a new flag to the registry.

Note

This will not automatically save the metadata, use the save() method to do so.

Parameters

flag (str or list) – The flag(s) to add.

property comments: dict

Get the comments.

property flags: list

Get the flags.

load(filename: str)

Load yaml metadata from a file.

Parameters

filename (str) – The path to the yaml file.

lookup_last() → dict

Get the last comment.

Returns

The last comment dictionary with timestamp as key, user and comment as values.

Return type

dict

remove_flags(flag: str)

Remove one or more flags from the registry.

Note

This will not automatically save the metadata, use the save() method to do so.

Parameters

flag (str or list) – The flag(s) to remove.

save()

Save the metadata.

undo_comment()

Undo the last comment.

Note

This will not automatically save the metadata, use the save() method to do so.

filerecords.api.utils module

Utility functions for filerecords.

filerecords.api.utils.add_registry_to_gitignore()

Add the registry directory to a .gitignore file in the current directory.

filerecords.api.utils.find_registry(directory: str)

Find a registry associated with a source directory. This will repeatedly search the upper level directories until a registry is found.

Parameters

directory (str) –

Returns

The path to the registry directory or None if no registry was found.

Return type

str or None

filerecords.api.utils.get_directory_perms(directory)

Get the permissions of the parent directory.

Parameters

directory (str) – The directory to get the permissions of the parent directory of.

Returns

The permissions of the parent directory as numeric value.

Return type

int

filerecords.api.utils.get_indexfile(registry_dir: str)

Get the indexfile of a registry.

Parameters

registry_dir (str) – The path to the registry directory.

Returns

The path to the registry’s indexfile.

Return type

str

filerecords.api.utils.get_metafile(registry_dir: str)

Get the metafile of a registry.

Parameters

registry_dir (str) – The path to the registry directory.

Returns

The path to the registry’s metafile.

Return type

str

filerecords.api.utils.load_indexfile(filename: str)

Load a registry indexfile.

Parameters

filename (str) – The path to the registry indexfile.

Returns

The contents of the registry indexfile.

Return type

pandas.DataFrame

filerecords.api.utils.load_yamlfile(filename: str)

Load a yaml metadata file.

Parameters

filename (str) – The path to the yaml file.

Returns

The contents of the yaml file.

Return type

dict

filerecords.api.utils.log(name: str = 'filerecords', level: Optional[int] = None, outfile: Optional[str] = None)

A logger that can be used to log records.

Parameters

• name (str) – The name of the logger.

• level (int) – The level of the logger.

• outfile (str) – The file to log to. If None, logs to stdout.

filerecords.api.utils.make_new_registry(directory: str, perms: Optional[int] = None)

Make a new registry in a directory.

Parameters

• directory (str) – The directory to create the registry in.

• perms (int or str) – The permissions to set on the registry directory. This can be either the numeric permissions (e.g. 755) or a string (e.g. “rwxr-xr-x”). By default the permissions are inherited by the parent directory.

filerecords.api.utils.save_yamlfile(filename: str, contents: dict)

Save a yaml metadata file.

Parameters

• filename (str) – The path to the yaml file.

• contents (dict) – The contents of the yaml file.

filerecords.api.settings module

These are the default settings that control filerecords behavior.

filerecords.api.settings.comment_format(comment, name, timestamp)

The default format in which comments shall be represented in markdown files. This must be a function accepting a comment, name, and timestamp (datetime object) argument and return a string.

filerecords.api.settings.entryfile_template = {'comments': {}, 'flags': []}

The template for file record entries

filerecords.api.settings.indexfile = 'INDEXFILE'

The name of the indexfile, which will map filenames (basenames) to unique identifiers within the registry.

filerecords.api.settings.indexfile_header = 'id\tfilename\trelpath\n'

The header of the indexfile

filerecords.api.settings.log_level = 20

The default logging level

filerecords.api.settings.registry_dir = '.registry'

The directory to store the registry in

filerecords.api.settings.registry_export_name = 'registry'

The default name of exported registry file(s) in yaml or markdown format

filerecords.api.settings.registry_metafile = 'METAFILE'

The name of the file storing the registry’s own metadata - i.e. registry comments and the associated flags and flag groups.

CLI

filerecords.cli.auxiliary module

filerecords.cli.clear module

filerecords.cli.comment module

The records comment command can be used to add a comment to a specific file or the registry itself.

Usage

>>> records comment [-c <comment>] [-f <flags>] <filename>

where <filename> is the path to the file to comment. If left blank the comment is added to the registry itself. -c <comment>, adds a comment or description message. -f <flags>, adds any number of flags. These can include defined flag group labels.

filerecords.cli.comment.comment(args)

The core function to add comments.

filerecords.cli.comment.setup(parent)

Set up the CLI

filerecords.cli.destroy module

filerecords.cli.export module

filerecords.cli.flag module

The records flag command can be used to add flags to a specific file or the registry itself, and to define flag groups.

Usage

>>> records flag [-f <flags>] [-g <groupname> : <grouplabels>] <filename>

where <filename> is the path to the file to comment. If left blank the flag is added to the registry itself. -f <flags>, adds any number of flags. These can include defined flag group labels. -g <groupname> : <grouplabels>, will define a flag group in the registry. -f and -g can be provided at the same time.

filerecords.cli.flag.flag(args)

The core function to add comments.

filerecords.cli.flag.setup(parent)

Set up the CLI

filerecords.cli.init module

The records init command can be used to initialize a new registry in the current directory.

Usage:

>>> records init [-c <comment>] [-g <groupname> : <grouplabels>] [-g <groupname> : <grouplabels>]

-c <comment> : Adds a comment or description to the registry that is initialized. -g <groupname> : Adds a label group to the registry. Label groups can be specified via ‘<name> : <label1> <label2>…’ syntax. Note, this option specifies a single group. It can be supplied multiple times to specify multiple groups in one go.

Flags and Flag groups

Flags are used to label files and group them together. Flags are arbitrary labels so they can be specified on-the-run while commenting a file. Flag groups can be used to add multiple flags at a time to a file. Contrary to single flags, flag groups must be defined before they can be used.

filerecords.cli.init.init(args)

The core function to initialize a new registry.

filerecords.cli.init.setup(parent)

Set up the CLI

filerecords.cli.list module

The records list command can be used to list recorded files within the registry. By default this will list all recorded files in the registry. The results can be restricted using the -f and -e flags.

Usage

>>> records list [-f <flag>] [-e <pattern>]

where <flag>, is a flag to search for and <pattern>, is a regular expression to search for. Both <flag> and <pattern> can be specified at the same time.

The -f flag can only be used to search for a single flag. To search for multiple flags at a time, define a flag group first and then search for it’s label using ‘group:your_group’.

filerecords.cli.list.search(args)

The core function to search for entries.

filerecords.cli.list.setup(parent)

Set up the CLI

filerecords.cli.list_local module

filerecords.cli.lookup module

filerecords.cli.main module

filerecords.cli.move module

The records mv command can be used to move / rename a file or directory in the registry. This command by default also performs file moving.

Usage

>>> records mv [-k] <filename>

where <filename> is the path to the file to move / rename in the registry. The -k option can be specified to prevent the file from being moved itself. In this case the file will remain unchanged while its records are adjusted.

filerecords.cli.move.move(args)

The core function to move / rename entries in the registry.

filerecords.cli.move.setup(parent)

Set up the CLI

filerecords.cli.read module

filerecords.cli.remove module

The records rm command can be used to remove a file or directory from the registry. This command by default also performs file removal.

Usage

>>> records rm [-k] <filename>

where <filename> is the path to the file to remove from the registry. The -k option can be specified to prevent the file from being removed itself. In this case the file will remain while its records are removed.

filerecords.cli.remove.remove(args)

The core function to remove entries from the registry.

filerecords.cli.remove.setup(parent)

Set up the CLI

filerecords.cli.undo module

The records undo command can be used to remove a file or directory’s last added comment.

Usage

>>> records undo [-f <flags>] <filename>

where <filename> is the path to the file whose last comment to remove. If left blank the comment is removed from the registry itself. -f <flags>, removes any number of flags. These can include defined flag group labels.

When flags are specified, then only the flags are removed while the comments are left untouched.

filerecords.cli.undo.setup(parent)

Set up the CLI

filerecords.cli.undo.undo(args)

The core function to undo comments or files.