lsseq 4.2.0__tar.gz → 4.3.1__tar.gz

{lsseq-4.2.0 → lsseq-4.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lsseq
-Version: 4.2.0
+Version: 4.3.1
 Summary: ls-like command for image-sequences
 Home-page: https://github.com/jrowellfx/lsseq
 Author: James Philip Rowell
@@ -94,8 +94,10 @@ however it can print sequences in a variety of formats useful for `nuke`,
 ```
     python3 -m pip install lsseq --upgrade
 ```
+If installing locally, it's probably best to install in a virtual-environment
+or [`venv`](https://docs.python.org/3/library/venv.html). 
 
-There is additional installation-information below in an
+There is additional installation-information in an
 [addendum](https://github.com/jrowellfx/lsseq#addendum---more-on-installing-command-line-tools)
 below with a helpful technique for installing `lsseq` system-wide.
 
@@ -267,7 +269,7 @@ extend `lsseq's` capability.
     bbb/bbx.[0097-0103].tif
     bbb/bby.[0197-0203].tif
 
-    5$ lsseq --prepend-path-abs --skip-missing --format rv *
+    5$ lsseq --prepend-path-abs --format rv *
     /user/jrowellfx/test/ccc.0101.exr
     /user/jrowellfx/test/aaa/aaa.97-103@@@.tif
     /user/jrowellfx/test/bbb/bbx.97-103#.tif
@@ -318,12 +320,13 @@ the following EXIT codes will be combined bitwise to return
 possibly more than one different warning and/or error.
 
 ```
-EXIT_NO_ERROR               = 0 # Clean exit.
-EXIT_LS_ERROR               = 1 # A call to 'ls' returned an error code.
-EXIT_ARGPARSE_ERROR         = 2 # A bad option was passed to lsseq. Exit lsseq.
-EXIT_LSSEQ_SOFTLINK_WARNING = 4 # warning - broken softlink found
-EXIT_LSSEQ_PADDING_WARNING  = 8 # warning - two images with same name, same frame-num, but diff padding
-EXIT_CD_PERMISSION_WARNING  = 16 # warning - recursive descent blocked - no execute permission on dir
+EXIT_NO_ERROR                 =  0 # Clean exit.
+EXIT_LS_WARNING               =  1 # A call to 'ls' returned an error or another internal issue
+EXIT_ARGPARSE_ERROR           =  2 # The default code that argparse exits with if bad option.
+EXIT_LSSEQ_SOFTLINK_WARNING   =  4 # warning - broken softlink
+EXIT_LSSEQ_PADDING_WARNING    =  8 # warning - two images with same name, same frame-num, diff padding
+EXIT_CD_PERMISSION_WARNING    = 16 # warning - recursive descent blocked - no execute permission on dir
+EXIT_LSSEQ_NOSUCHFILE_WARNING = 32 # A non-existent sequence-file was listed on the command line.
 ```
 
 ## `lsseq --help`
@@ -332,8 +335,8 @@ A full listing of all the command-line options follows, as displayed when runnin
 ```
 usage: lsseq [-h | --help] [OPTION]... [FILE]...
 
-List directory contents like /bin/ls except condense image
-sequences to one entry each. Filenames that are part of image
+List directory contents like /bin/ls (see LS(1)) except condense
+image sequences to one entry each. Filenames that are part of image
 sequences are assumed to be of the form:
 
     <descriptiveName>.<frameNum>.<imgExtension>
@@ -353,128 +356,187 @@ list of image sequences as such:
 positional arguments:
   FILE                  file names
 
-optional arguments:
-  -h, --help            show this help message and exit
+miscellaneous options:
+  --help, -h            show this help message and exit
   --version             show program's version number and exit
-  --format FORMAT, -f FORMAT
-                        list image sequences in various formats. The choices are
-                        'native' (default), 'nuke', 'rv', 'shake', 'glob', 'mplay',
-                        and 'houdini'. Note that glob prints correct results only
-                        if the frame numbers are padded. Further note that
-                        reporting of missing/bad/etc frames (e.g. --show-missing)
-                        only happens with 'native' format.
+  --silent, --quiet     suppress error and warning messages.
+  --                    end of options, all subsequent arguments are
+                        positional arguments.
+
+sequence interpretation:
+  --split-sequence      prints sequences with missing frames as separate
+                        sequences as if there are multiple sequences with the
+                        same name, but with different frame ranges. Note: this
+                        option only affects the printing of a sequence, not in
+                        how sequence times are calculated. In other words,
+                        sorting by time might not produce the results you
+                        would expect when splitting sequences with this
+                        option.
+  --no-split-sequence   consider frames with the same name as all being part
+                        of the same sequence. [default]
+  --strict-num-separator, -s
+                        strictly enforce the use of '.' (dot) as a separator
+                        between the descriptiveName and frameNumber when
+                        looking to interpret filenames as image sequences.
+                        i.e., <descriptiveName>.<frameNum>.<imgExtension>
+                        (also see --loose-num-separator) [default]
+  --loose-num-separator, -l
+                        allow the use of '_' (underscore), in addition to '.'
+                        (dot) as a separator between the descriptiveName and
+                        frameNumber when looking to interpret filenames as
+                        image sequences. i.e.,
+                        <descriptiveName>_<frameNum>.<imgExtension> (also see
+                        --strict-num-separator)
+
+display of error frames:
   --show-missing, -m    show list of missing frames as 'm:[<list>]' [default]
   --skip-missing, -M    do not show list of missing frames.
-  --show-zero, -z       show list of zero length images as 'z:[<list>]' [default]
+  --show-zero, -z       show list of zero length images as 'z:[<list>]'
+                        [default]
   --skip-zero, -Z       do not show list of zero length images.
   --show-bad-frames, -b
-                        lists potentially bad frames based on the minimum size of a
-                        good frame (see --good-frame-min-size). Reported as
-                        'b:[<list>]'
+                        lists potentially bad frames based on the minimum size
+                        of a good frame (see --good-frame-min-size). Reported
+                        as 'b:[<list>]'
   --skip-bad-frames, -B
                         do not show list of potentially bad frames. [default]
   --good-frame-min-size BYTES
-                        any frame size less than BYTES is a bad frame. Short forms
-                        for byte sizes are accepted as in '1K' (i.e., 1024) or
-                        '1.5K' for example. [default: 512]
+                        any frame size less than BYTES is a bad frame. Short
+                        forms for byte sizes are accepted as in '1K' (i.e.,
+                        1024) or '1.5K' for example. [default: 512]
   --show-bad-padding    report badly padded frame numbers which occurs when a
-                        number is padded but shouldn't be, or isn't padded but it
-                        should be. Reported as 'p:[<list>]' [default]
+                        number is padded but shouldn't be, or isn't padded but
+                        it should be. Reported as 'p:[<list>]' [default]
   --skip-bad-padding    do not show list of badly padded frames.
-  --combine-lists, -c   combine the lists of zero, missing and bad frames into one
-                        list. Reported as 'e:[<list>]'
-  --no-combine-lists    Don't combine the error lists.
-  --no-error-lists, -n  Skip printing ALL error lists. Note: Setting
-                        --show-bad-padding (for example) AFTER this option on the
-                        command line has the effect of ONLY showing the bad-padding
-                        error list
-  --split-sequence      prints sequences with missing frames as separate sequences
-                        as if there are multiple sequences with the same name, but
-                        with different frame ranges. Note: this option only affects
-                        the printing of a sequence, not in how sequence times are
-                        calculated. In other words, sorting by time might not
-                        produce the results you would expect when splitting
-                        sequences with this option.
-  --no-split-sequence   consider frames with the same name as all being part of the
-                        same sequence. [default]
-  --loose-num-separator, -l
-                        allow the use of '_' (underscore), in addition to '.' (dot)
-                        as a separator between the descriptiveName and frameNumber
-                        when looking to interpret filenames as image sequences.
-                        i.e., <descriptiveName>_<frameNum>.<imgExtension> (also see
-                        --strict-num-separator)
-  --strict-num-separator, -s
-                        strictly enforce the use of '.' (dot) as a separator
-                        between the descriptiveName and frameNumber when looking to
-                        interpret filenames as image sequences. i.e.,
-                        <descriptiveName>.<frameNum>.<imgExtension> (also see
-                        --loose-num-separator) [default]
+  --combine-lists, -c   combine the lists of zero, missing and bad frames into
+                        one list. Reported as 'e:[<list>]'
+  --no-combine-lists    don't combine the error lists [default].
+  --no-error-lists, -n  Skip printing ALL error lists. Note: Setting --show-
+                        bad-padding (for example) AFTER this option on the
+                        command line has the effect of ONLY showing the bad-
+                        padding error list
+
+sequence-category filters:
+  --img-ext, -i         print list of image, cache and movie file extensions
+                        and exit.
+  --list-all-files      list all sequences plus regular /bin/ls output.
+                        [default]
   --only-sequences, -o  omit any regular /bin/ls output, only list sequences.
-  --list-all-files      list all sequences plus regular /bin/ls output. [default]
   --only-images, -O     strictly list only image sequences (i.e., no movies or
                         caches).
-  --not-images          Omit image files from being considered as sequences. Image
-                        files will be listed with regular /bin/ls output unless
-                        --only-sequences has been specified on the command line.
+  --not-images          omit image files from being considered as sequences.
+                        Image files will be listed with regular /bin/ls output
+                        unless --only-sequences has been specified on the
+                        command line.
   --only-movies         strictly list only movies (i.e., no images or caches).
-  --not-movies          Omit movies from being considered as sequences. movie files
-                        will be listed with regular /bin/ls output unless
-                        --only-sequences has been specified on the command line.
+  --not-movies          omit movies from being considered as sequences. movie
+                        files will be listed with regular /bin/ls output
+                        unless --only-sequences has been specified on the
+                        command line.
   --only-caches         strictly list only cache sequences (i.e., no images or
                         movies).
-  --not-caches          Omit caches from being considered as sequences. cache files
-                        will be listed with regular /bin/ls output unless
-                        --only-sequences has been specified on the command line.
-  --img-ext, -i         print list of image, cache and movie file extensions and
-                        exit.
+  --not-caches          omit caches from being considered as sequences. cache
+                        files will be listed with regular /bin/ls output
+                        unless --only-sequences has been specified on the
+                        command line.
+
+sequence display-modifiers:
+  --format FORMAT, -f FORMAT
+                        list image sequences in various formats. The choices
+                        are 'native' (default), 'nuke', 'rv', 'shake', 'glob',
+                        'mplay', and 'houdini'. Note that glob prints correct
+                        results only if the frame numbers are padded. Further
+                        note that reporting of missing/zero/bad/etc. frames
+                        (e.g. --show-missing) only happens with 'native'
+                        format.
   --prepend-path-abs, -p
                         prepend the absolute path name to the image name. This
                         option implies the option --only-sequences and also
-                        suppresses printing directory name headers when listing
-                        directory contents.
+                        suppresses printing directory name headers when
+                        listing directory contents.
   --prepend-path-rel, -P
                         prepend the relative path name to the image name. This
-                        option implies the option --only-sequences and will also
-                        suppress printing directory name headers when listing
-                        directory contents.
-  --extremes, -e        only list the first and last frame of an image or cache-
-                        sequence on a separate line each. This option implies
-                        --prepend-path-abs (unless --prepend-path-rel is explicitly
-                        specified) as well as --only-sequences and --not-movies.
-  --single, -1          list one non-sequence entry per line (see ls(1))
-  --all, -a             do not ignore entries starting with '.' while omitting
-                        implied '.' and '..' directories (see ls(1) --almost-all)
-  --by-columns, -C      list non-sequence entries by columns (see ls(1))
-  --by-rows, -x         list non-sequence entries by lines instead of by columns
-                        (see ls(1))
-  --directory, -d       list directory entries instead of contents, and do not
-                        dereference symbolic links (see ls(1))
-  --classify, -F        append indicator (one of */=>@|) to entries (see ls(1))
-  --reverse, -r         reverse order while sorting.
+                        option implies the option --only-sequences and will
+                        also suppress printing directory name headers when
+                        listing directory contents.
+  --extremes, -e        only list the first and last frame of an image or
+                        cache-sequence on a separate line each. This option
+                        implies --prepend-path-abs (unless --prepend-path-rel
+                        is explicitly specified) as well as --only-sequences
+                        and --not-movies.
+
+sequence sorting and display:
   --recursive, -R       list subdirectories recursively.
-  --sort-by-time, -t    sort by modification time, the default comparison time is
-                        between the most recently modified (newest) frames in each
-                        sequence. (see --time) (see ls(1))
-  --time FRAME_AGE      which frame in the sequence to use to compare times between
-                        sequences when sorting by time. The possible values for
-                        'FRAME_AGE' are 'oldest', 'median' and 'newest'. [default:
-                        'newest']
+  --reverse, -r         reverse order while sorting.
+  --sort-by-time, -t    sort by modification time, the default comparison time
+                        is between the most recently modified (newest) frames
+                        in each sequence. (see --time) (see LS(1))
+  --time FRAME_AGE      which frame in the sequence to use to compare times
+                        between sequences when sorting by time. The possible
+                        values for 'FRAME_AGE' are 'oldest', 'median' and
+                        'newest'. [default: 'newest']
+  --global-sort-by-time, -G
+                        when using either --prepend-path-abs or --prepend-
+                        path-rel then this option will sort ALL sequences by
+                        time compared to each other, as opposed to only
+                        sorting sequences by time within their common
+                        directory. If the above conditions are NOT met, then
+                        this option is simply ignored.
   --only-show TENSE [CC]YYMMDD[-hh[mm[ss]]]
                         where TENSE is either 'before' or 'since'; only list
-                        sequences up to (and including) or after (and including)
-                        the time specified. The --time argument specifies which
-                        frame to use for the cutoff comparison. The optional CC
-                        (century) defaults to the current century. The optional
-                        '-hh' (hours), 'mm' (minutes) or 'ss' (seconds) default to
-                        zero if not specified.
-  --global-sort-by-time, -G
-                        when using either --prepend-path-abs or --prepend-path-rel
-                        then this option will sort ALL sequences by time compared
-                        to each other, as opposed to only sorting sequences by time
-                        within their common directory. If the above conditions are
-                        NOT met, then this option is simply ignored.
-  --silent, --quiet     suppress error and warning messages.
-
+                        sequences up to (and including) or after (and
+                        including) the time specified. The --time argument
+                        specifies which frame to use for the cutoff
+                        comparison. The optional CC (century) defaults to the
+                        current century. The optional '-hh' (hours), 'mm'
+                        (minutes) or 'ss' (seconds) default to zero if not
+                        specified.
+
+symbolic-link handling:
+  Control for whether or not to follow symbolic links to
+  the final target of files and/or directories. Regardless,
+  lsseq shall always write the name of the link itself and
+  not the file referenced by the link.
+
+  --dereference-command-line, -H
+                        only follow symbolic links of files and directories
+                        listed on the command line. [default]
+  --dereference, -L     follow all symbolic links to the final target of files
+                        and directories.
+  --no-dereference      do not follow any symbolic links.
+  --dereference-command-line-symlink-to-dir
+                        only follow each command line symbolic link that
+                        points to a directory, (i.e. do not follow links to
+                        files).
+  --dereference-symlink-to-dir
+                        only follow all symbolic links that point to
+                        directories, (i.e. do not follow links to files).
+  --no-dereference-dir  do not follow any symbolic links to directories.
+  --dereference-command-line-symlink-to-file
+                        only follow each command line symbolic link that
+                        points to a regular file, (i.e. do not follow links to
+                        directories).
+  --dereference-symlink-to-file
+                        only follow all symbolic links that point to regular
+                        files, (i.e. do not follow links to directories).
+  --no-dereference-file
+                        do not follow any symbolic links to regular files.
+
+LS(1) control for non-sequences:
+  --single, -1          list one non-sequence entry per line (see LS(1))
+  --all, -a             do not ignore entries starting with '.' while omitting
+                        implied '.' and '..' directories (see LS(1) --almost-
+                        all)
+  --by-columns, -C      list non-sequence entries by columns (see LS(1))
+  --by-rows, -x         list non-sequence entries by lines instead of by
+                        columns (see LS(1))
+  --directory, -d       list directory entries instead of contents, and do not
+                        follow symbolic links (see LS(1))
+  --classify, -F        append indicator (one of */=>@|) to entries, and do
+                        not follow symbolic links to directories. (see LS(1)
+                        for the meanings of the symbols.) Note: the '@' will
+                        also be appended to any sequences made up of symbolic
+                        links.
 ```
 
 ## Addendum - more on installing command-line tools
@@ -503,7 +565,7 @@ so that they are accessible to all users. This works on both MacOS and Linux.
     # ln -s /usr/local/venv/bin/fixseqpadding /usr/local/bin/fixseqpadding
     # exit
     $ lsseq --version
-    4.2.0
+    4.3.1
 ```
 
 At this point any user should be able to run any of the commands linked in the example above.
@@ -575,7 +637,8 @@ the transition quite painless. Especially if you make use
 of [`runsed`](https://github.com/jrowellfx/vfxTdUtils) which if you haven't used it before,
 now is the time, it's extremely helpful.
 
-There are two files provided at the root-level of the repo, namely:
+There are two files provided at the root-level of the repo in
+the directory [`updateLongOpts`](https://github.com/jrowellfx/lsseq/tree/master/updateLongOpts), namely:
 `sed.script.jrowellfx.doubleDashToKebab` and `sed.script.lsseq.v3tov4`.
 
 The first one can be used to fix the long-option names for ALL the 
@@ -590,14 +653,13 @@ on your system.
 ```
 $ cd ~/bin
 $ ls
-myScriptThatUsesLsseq
+myScriptThatUsesLsseq  sed.script.jrowellfx.doubleDashToKebab
 $ cat myScriptThatUsesLsseq
 #!/bin/bash
 
 lsseq --globalSortByTime --recursive --prependPathAbs /Volumes/myProjectFiles
 
-$ mv ~/Downloads/sed.script.jrowellfx.doubleDashToKebab sed.script
-$ runsed myScriptThatUsesLsseq
+$ runsed -f sed.script.jrowellfx.doubleDashToKebab myScriptThatUsesLsseq
 $ ./.runsed.diff.runsed
 + /usr/bin/diff ./.myScriptThatUsesLsseq.runsed myScriptThatUsesLsseq
 3c3