Merge pull request #717

v3.3.0

Fix #718

README.md

@@ -19,6 +19,7 @@
     * [lock](#digiarch-edit-lock)
     * [remove](#digiarch-edit-remove)
     * [rollback](#digiarch-edit-rollback)
+  * [search](#digiarch-search)
   * [history](#digiarch-history)
   * [doctor](#digiarch-doctor)
   * [upgrade](#digiarch-upgrade)
@@ -42,6 +43,7 @@ Commands:
   reidentify   Reidentify files.
   extract      Unpack archives.
   edit         Edit the database.
+  search       Search the database.
   history      View events log.
   doctor       Inspect the database.
   upgrade      Upgrade the database.
@@ -217,6 +219,8 @@ Usage: digiarch edit action convert [OPTIONS] ROOT ID... REASON
 
   The --outputs option may be omitted when using the "copy" tool.
 
+  To lock the file(s) after editing them, use the --lock option.
+
   To see the changes without committing them, use the --dry-run option.
 
   For details on the ID arguments, see the edit command.
@@ -232,6 +236,7 @@ Options:
   --tool TEXT     The tool to use for conversion.  [required]
   --outputs TEXT  The file extensions to generate.  [multiple; required for
                   tools other than "copy"]
+  --lock          Lock the edited files.
   --dry-run       Show changes without committing them.
   --help          Show this message and exit.
 ```
@@ -243,6 +248,8 @@ Usage: digiarch edit action extract [OPTIONS] ROOT ID... REASON
 
   Set files' action to "extract".
 
+  To lock the file(s) after editing them, use the --lock option.
+
   To see the changes without committing them, use the --dry-run option.
 
   For details on the ID arguments, see the edit command.
@@ -258,6 +265,7 @@ Options:
   --tool TEXT       The tool to use for extraction.  [required]
   --extension TEXT  The extension the file must have for extraction to
                     succeed.
+  --lock            Lock the edited files.
   --dry-run         Show changes without committing them.
   --help            Show this message and exit.
 ```
@@ -269,6 +277,8 @@ Usage: digiarch edit action manual [OPTIONS] ROOT ID... REASON
 
   Set files' action to "manual".
 
+  To lock the file(s) after editing them, use the --lock option.
+
   To see the changes without committing them, use the --dry-run option.
 
   For details on the ID arguments, see the edit command.
@@ -284,6 +294,7 @@ Options:
   --reason TEXT   The reason why the file must be processed manually.
                   [required]
   --process TEXT  The steps to take to process the file.  [required]
+  --lock          Lock the edited files.
   --dry-run       Show changes without committing them.
   --help          Show this message and exit.
 ```
@@ -308,6 +319,8 @@ Usage: digiarch edit action ignore [OPTIONS] ROOT ID... REASON
 
   The --reason option may be omitted when using a template other than "text".
 
+  To lock the file(s) after editing them, use the --lock option.
+
   To see the changes without committing them, use the --dry-run option.
 
   For details on the ID arguments, see the edit command.
@@ -323,6 +336,7 @@ Options:
   --template TEMPLATE  The template type to use.  [required]
   --reason TEXT        The reason why the file is ignored.  [required for
                        "text" template]
+  --lock               Lock the edited files.
   --dry-run            Show changes without committing them.
   --help               Show this message and exit.
 ```
@@ -344,8 +358,12 @@ Usage: digiarch edit action copy [OPTIONS] ROOT ID... PUID
   If no actions file is give with --actions, the latest version will be
   downloaded from GitHub.
 
+  To lock the file(s) after editing them, use the --lock option.
+
   To see the changes without committing them, use the --dry-run option.
 
+  For details on the ID arguments, see the edit command.
+
 Options:
   --uuid          Use UUIDs as identifiers.  [default]
   --puid          Use PUIDs as identifiers.
@@ -356,6 +374,7 @@ Options:
   --from-file     Interpret IDs as files from which to read the IDs.
   --actions FILE  Path to a YAML file containing file format actions.  [env
                   var: DIGIARCH_ACTIONS]
+  --lock          Lock the edited files.
   --dry-run       Show changes without committing them.
   --help          Show this message and exit.
 ```
@@ -466,6 +485,41 @@ Options:
   --help          Show this message and exit.
 ```
 
+## digiarch search
+
+```
+Usage: digiarch search [OPTIONS] ROOT ID...
+
+  Search for specific files in the database.
+
+  Files are displayed in YAML format.
+
+  The ID arguments are interpreted as a list of UUID's by default. This
+  behaviour can be changed with the --puid, --path, --path-like, --checksum,
+  and --warning options. If the --from-file option is used, each ID argument
+  is interpreted as the path to a file containing a list of IDs (one per line,
+  empty lines are ignored).
+
+  If there are no ID arguments, then the limit is automatically set to 100 if
+  not set with the --limit option.
+
+Options:
+  --uuid                          Use UUIDs as identifiers.  [default]
+  --puid                          Use PUIDs as identifiers.
+  --path                          Use relative paths as identifiers.
+  --path-like                     Use relative paths as identifiers, match
+                                  with LIKE.
+  --checksum                      Use checksums as identifiers.
+  --warning                       Use warnings as identifiers.
+  --from-file                     Interpret IDs as files from which to read
+                                  the IDs.
+  --order-by [relative_path|size|action]
+                                  Set sorting field.  [default: relative_path]
+  --sort [asc|desc]               Set sorting direction.  [default: asc]
+  --limit INTEGER RANGE           Limit the number of results.  [x>=1]
+  --help                          Show this message and exit.
+```
+
 ## digiarch history
 
 ```
@@ -479,7 +533,8 @@ Usage: digiarch history [OPTIONS] ROOT
   If multiple --uuid, --operation, or --reason options are used, the query
   will match any of them.
 
-  If no query option is given, only the first 100 results will be shown.
+  If no query option is given, then the limit is automatically set to 100 if
+  not set with the --limit option.
 
 Options:
   --from [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%dT%H:%M:%S.%f]
@@ -491,6 +546,7 @@ Options:
   --reason TEXT                   Event reason.
   --ascending / --descending      Sort by ascending or descending order.
                                   [default: ascending]
+  --limit INTEGER RANGE           Limit the number of results.  [x>=1]
   --help                          Show this message and exit.
 ```
 

digiarch/__version__.py

@@ -1 +1 @@
-__version__ = "3.2.16"
+__version__ = "3.3.0"

digiarch/cli.py

@@ -10,6 +10,7 @@
 from .history import command_history
 from .identify import command_identify
 from .identify import command_reidentify
+from .search import command_search
 from .upgrade import command_upgrade
 
 
@@ -24,6 +25,7 @@ def app():
 app.add_command(command_reidentify, command_reidentify.name)
 app.add_command(command_extract, command_extract.name)
 app.add_command(group_edit, group_edit.name)
+app.add_command(command_search, command_search.name)
 app.add_command(command_history, command_history.name)
 app.add_command(command_doctor, command_doctor.name)
 app.add_command(command_upgrade, command_upgrade.name)

digiarch/doctor.py

@@ -21,7 +21,7 @@
 from digiarch.common import option_dry_run
 from digiarch.common import start_program
 
-invalid_characters: str = r'\?%*|"<>,:;=+[]!@' + bytes(range(20)).decode("ascii") + "\x7f"
+invalid_characters: str = "\\#%&{}[]<>*?/$!'\":@+`|=" + bytes(range(32)).decode("ascii") + "\x7f"
 
 
 def sanitize_path(path: str | PathLike) -> Path:

digiarch/edit/action.py

@@ -40,6 +40,24 @@
 from .common import find_files
 
 
+def set_lock(
+    ctx: Context,
+    database: FileDB,
+    file: File,
+    reason: str,
+    dry_run: bool,
+    *loggers: Logger,
+):
+    if file.lock is True:
+        return
+    event = HistoryEntry.command_history(ctx, "lock", file.uuid, [file.lock, True], reason)
+    file.lock = True
+    if not dry_run:
+        database.files.update(file, {"uuid": file.uuid})
+        database.history.insert(event)
+    event.log(INFO, *loggers)
+
+
 def set_action(
     ctx: Context,
     database: FileDB,
@@ -83,6 +101,7 @@ def group_action():
     callback=param_regex("^(.[a-zA-Z0-9]+)+$"),
     help='The file extensions to generate.  [multiple; required for tools other than "copy"]',
 )
+@option("--lock", is_flag=True, default=False, help="Lock the edited files.")
 @option_dry_run()
 @pass_context
 def action_convert(
@@ -94,13 +113,16 @@ def action_convert(
     id_files: bool,
     tool: str,
     outputs: tuple[str, ...],
+    lock: bool,
     dry_run: bool,
 ):
     """
     Set files' action to "convert".
 
     The --outputs option may be omitted when using the "copy" tool.
 
+    To lock the file(s) after editing them, use the --lock option.
+
     To see the changes without committing them, use the --dry-run option.
 
     For details on the ID arguments, see the edit command.
@@ -118,6 +140,8 @@ def action_convert(
         with ExceptionManager(BaseException) as exception:
             for file in find_files(database, ids, id_type, id_files):
                 set_action(ctx, database, file, "convert", data, reason, dry_run, log_stdout)
+                if lock:
+                    set_lock(ctx, database, file, reason, dry_run, log_stdout)
 
         end_program(ctx, database, exception, dry_run, log_file, log_stdout)
 
@@ -133,6 +157,7 @@ def action_convert(
     callback=param_regex(r"^(.[a-zA-Z0-9]+)+$"),
     help="The extension the file must have for extraction to succeed.",
 )
+@option("--lock", is_flag=True, default=False, help="Lock the edited files.")
 @option_dry_run()
 @pass_context
 def action_extract(
@@ -144,11 +169,14 @@ def action_extract(
     id_files: bool,
     tool: str,
     extension: str | None,
+    lock: bool,
     dry_run: bool,
 ):
     """
     Set files' action to "extract".
 
+    To lock the file(s) after editing them, use the --lock option.
+
     To see the changes without committing them, use the --dry-run option.
 
     For details on the ID arguments, see the edit command.
@@ -163,6 +191,8 @@ def action_extract(
         with ExceptionManager(BaseException) as exception:
             for file in find_files(database, ids, id_type, id_files):
                 set_action(ctx, database, file, "extract", data, reason, dry_run, log_stdout)
+                if lock:
+                    set_lock(ctx, database, file, reason, dry_run, log_stdout)
 
         end_program(ctx, database, exception, dry_run, log_file, log_stdout)
 
@@ -186,6 +216,7 @@ def action_extract(
     callback=param_regex(r"^.*\S.*$"),
     help="The steps to take to process the file.",
 )
+@option("--lock", is_flag=True, default=False, help="Lock the edited files.")
 @option_dry_run()
 @pass_context
 def action_manual(
@@ -197,11 +228,14 @@ def action_manual(
     id_files: bool,
     data_reason: str | None,
     process: str,
+    lock: bool,
     dry_run: bool,
 ):
     """
     Set files' action to "manual".
 
+    To lock the file(s) after editing them, use the --lock option.
+
     To see the changes without committing them, use the --dry-run option.
 
     For details on the ID arguments, see the edit command.
@@ -216,6 +250,8 @@ def action_manual(
         with ExceptionManager(BaseException) as exception:
             for file in find_files(database, ids, id_type, id_files):
                 set_action(ctx, database, file, "manual", data, reason, dry_run, log_stdout)
+                if lock:
+                    set_lock(ctx, database, file, reason, dry_run, log_stdout)
 
         end_program(ctx, database, exception, dry_run, log_file, log_stdout)
 
@@ -238,6 +274,7 @@ def action_manual(
     callback=param_regex(r"^.*\S.*$"),
     help='The reason why the file is ignored.  [required for "text" template]',
 )
+@option("--lock", is_flag=True, default=False, help="Lock the edited files.")
 @option_dry_run()
 @pass_context
 @docstring_format(templates="\n".join(f"    * {t}" for t in TemplateTypeEnum).strip())
@@ -250,6 +287,7 @@ def action_ignore(
     id_files: bool,
     template: TTemplateType,
     data_reason: str | None,
+    lock: bool,
     dry_run: bool,
 ):
     """
@@ -261,6 +299,8 @@ def action_ignore(
 
     The --reason option may be omitted when using a template other than "text".
 
+    To lock the file(s) after editing them, use the --lock option.
+
     To see the changes without committing them, use the --dry-run option.
 
     For details on the ID arguments, see the edit command.
@@ -278,6 +318,8 @@ def action_ignore(
         with ExceptionManager(BaseException) as exception:
             for file in find_files(database, ids, id_type, id_files):
                 set_action(ctx, database, file, "ignore", data, reason, dry_run, log_stdout)
+                if lock:
+                    set_lock(ctx, database, file, reason, dry_run, log_stdout)
 
         end_program(ctx, database, exception, dry_run, log_file, log_stdout)
 
@@ -298,6 +340,7 @@ def action_ignore(
     callback=lambda _ctx, _param, value: Path(value) if value else None,
     help="Path to a YAML file containing file format actions.",
 )
+@option("--lock", is_flag=True, default=False, help="Lock the edited files.")
 @option_dry_run()
 @pass_context
 def command_copy(
@@ -310,6 +353,7 @@ def command_copy(
     id_type: str,
     id_files: bool,
     actions_file: Path | None,
+    lock: bool,
     dry_run: bool,
 ):
     """
@@ -324,7 +368,11 @@ def command_copy(
 
     If no actions file is give with --actions, the latest version will be downloaded from GitHub.
 
+    To lock the file(s) after editing them, use the --lock option.
+
     To see the changes without committing them, use the --dry-run option.
+
+    For details on the ID arguments, see the edit command.
     """  # noqa: D301
     check_database_version(ctx, ctx_params(ctx)["root"], (db_path := root / "_metadata" / "files.db"))
 
@@ -344,6 +392,8 @@ def command_copy(
         with ExceptionManager(BaseException) as exception:
             for file in find_files(database, ids, id_type, id_files):
                 set_action(ctx, database, file, action, data, reason, dry_run, log_stdout)
+                if lock:
+                    set_lock(ctx, database, file, reason, dry_run, log_stdout)
 
         end_program(ctx, database, exception, dry_run, log_file, log_stdout)