pseek 3.1.1__tar.gz → 3.2.0__tar.gz

{pseek-3.1.1 → pseek-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pseek
-Version: 3.1.1
+Version: 3.2.0
 Summary: Pseek is a Python CLI toolkit to search files, folders, and text
 Author: Groot
 License-Expression: MIT
@@ -112,12 +112,14 @@ psk -- --path
 | `--re-include`, `--re-exclude` | Limit search results to specific directories or files with regex |
 | `--word` | Match the whole word only (except when `--expr` is enabled, in which case you can make it match whole word by putting `w` before term: `w"foo"`) |
 | `--expr` | Enable boolean query expressions. Example: `r"foo.*bar" and ("bar" or "baz") and not "qux"`. Prefixes: `r=regex`, `c=case-sensitive`, `w=whole-word`, `f=fuzzy` |
+| `--context` | Show N context lines before and after matches, or use N:M to specify before:after |
+| `--depth` | Limit directory traversal to given depth range. By default, there is no limit on search depth |
 | `--timeout` | Stop the search after the specified number of seconds |
 | `--fuzzy` | Enable fuzzy search (Highlighting and counting matches are disabled in this mode if `--word` is not enabled to prevent the program from slowing down). except when `--expr` is enabled, in which case you can make it fuzzy by putting `f` before term: `f"foo"` |
 | `--fuzzy-level` | Fuzzy matching threshold (0-99). Higher values require closer matches (default: `80`) |
 | `--size` | Limit results based on the size of files |
 | `--archive` | Enable search within archive files (e.g. `zip`, `rar`, `7z`, `gz`, `bz2`, `xz`, `tar`, `tar.gz`, `tar.bz2`, `tar.xz`) |
-| `--depth` | Maximum nested archive depth. Example: 2 allows searching up to two archive levels |
+| `--arc-depth` | Limit nested archive to given depth range. By default, there is no limit |
 | `--arc-ext`, `--arc-exc-ext` | Filter by file extension inside archive files |
 | `--arc-include`, `--arc-exclude` | Limit search results to specific set of directories or files inside archive files |
 | `--arc-size` | Limit results based on the size of files in the archive |
@@ -176,7 +178,7 @@ Example:
 psk "hello world"
 ```
 
-**Note:** To use case-sensitive, whole-word matching, regular expression search, and fuzzy search when `--expr` is enabled, we can use [expression prefixes](#expression-prefixes).
+> **Note:** To use case-sensitive, whole-word matching, regular expression search, and fuzzy search when `--expr` is enabled, we can use [expression prefixes](#expression-prefixes).
 
 ### Case Sensitive Search
 
@@ -364,7 +366,51 @@ simultaneously.
 
 Allowed modes: `r`, `c`, `w`, `f`, `rc`, `cr`, `cw`, `wc`, `cf`, `fc`, `wf`, `fw`, `cwf`, `cfw`, `wcf`, `wfc`, `fcw`, `fwc`
 
-**Note:** Whole word matching and regex matching cannot be used at the same time, because we can use `\b` in regex to enable whole word matching: `r"\btext\b"`
+> **Note:** Whole word matching and regex matching cannot be used at the same time, because we can use `\b` in regex to enable whole word matching: `r"\btext\b"`
+
+## Context
+
+Show context lines around each match. The value is specified as `BEFORE:AFTER`:
+
+```bash
+--context 2       # 2 lines before and after
+--context 2:0     # 2 lines before, none after
+--context 0:2     # none before, 2 lines after
+--context 2:5     # 2 lines before, 5 lines after
+--context 2:      # 2 lines before, none after
+--context :2      # none before, 2 lines after
+--context 0       # matching lines only
+```
+
+Nearby matches whose context ranges overlap or directly touch are combined into a single group.
+
+## Depth
+
+Controls how deep the search goes inside directories.
+
+A depth of `0` means that only base path's immediate contents are searched; subdirectories are not entered.
+
+```text
+project/                  ← base directory
+├── file.txt              ← depth 0
+├── folder1/              ← depth 0
+│   ├── file.txt          ← depth 1
+│   └── folder2/          ← depth 1
+│       └── file.txt      ← depth 2
+```
+
+`--depth` can be specified multiple times to search non-contiguous depth ranges:
+
+```bash
+--depth 0              # Direct contents only
+--depth 1              # One level inside
+--depth 2:4            # Depths 2 through 4
+--depth 2 --depth 5:7  # Depths 2 and 5 through 7
+--depth :2             # Depths 0 through 2
+--depth 3:             # Depth 3 and deeper
+```
+
+If `--depth` is not specified, the search has no depth limit.
 
 ## Extension Filters
 
@@ -402,7 +448,7 @@ psk TODO \
 
 Skip those paths.
 
-**Note:** The include and exclude paths will be combined with path argument.
+> **Note:** The include and exclude paths will be combined with path argument.
 
 ## Regex Path Filters
 
@@ -455,7 +501,7 @@ psk config \
 
 Files between `1 MiB` and `10 MiB` will not match.
 
-**Note:** Directory sizes are not calculated recursively. When `--size` is used, directories are automatically excluded from the search results.
+> **Note:** Directory sizes are not calculated recursively. When `--size` is used, directories are automatically excluded from the search results.
 
 ## Archive Search
 
@@ -487,15 +533,24 @@ backup.zip::source.7z::notes.txt
 
 ### Archive Depth
 
-Limit recursion depth:
+The concept of depth in archive is different from `--depth`. Depth in archive is calculated based on nested archives. Each archive that is inside another archive counts as one level of depth.
+
+| Syntax | Meaning                                                  |
+| ------ | -------------------------------------------------------- |
+| `2`    | exactly `2nd` depth                                      |
+| `:2`   | `2nd` depth or lower                                     |
+| `2:`   | `2nd` depth or higher                                    |
+| `2:4`  | between `2` and `4` (Both range boundaries are included) |
+
+`--arc-depth` can be specified multiple times:
 
 ```bash
-psk TODO --archive --depth 2
+psk TODO --archive --arc-depth :2 --arc-depth 5:
 ```
 
-Meaning `archive level 1` and `archive level 2` will be searched. Deeper levels will be skipped.
+Meaning `archive level 3` and `archive level 4` won't be searched.
 
-**Note:** `--depth 0` means perform the search only within this current archive and don't enter nested archives.
+> **Note:** `--arc-depth 0` means perform the search only within this current archive and don't enter nested archives.
 
 ## Archive Filters
 
@@ -535,7 +590,7 @@ This works exactly like the [--size](#size-filtering) option.
 psk TODO --archive --arc-size 10m:40m
 ```
 
-**Note:** Archive directory sizes are usually reported as zero by archive formats, so directory search is disabled if this filter is enabled to avoid incorrect results.
+> **Note:** Archive directory sizes are usually reported as zero by archive formats, so directory search is disabled if this filter is enabled to avoid incorrect results.
 
 ## RAR Backend
 

{pseek-3.1.1 → pseek-3.2.0}/README.md

@@ -83,12 +83,14 @@ psk -- --path
 | `--re-include`, `--re-exclude` | Limit search results to specific directories or files with regex |
 | `--word` | Match the whole word only (except when `--expr` is enabled, in which case you can make it match whole word by putting `w` before term: `w"foo"`) |
 | `--expr` | Enable boolean query expressions. Example: `r"foo.*bar" and ("bar" or "baz") and not "qux"`. Prefixes: `r=regex`, `c=case-sensitive`, `w=whole-word`, `f=fuzzy` |
+| `--context` | Show N context lines before and after matches, or use N:M to specify before:after |
+| `--depth` | Limit directory traversal to given depth range. By default, there is no limit on search depth |
 | `--timeout` | Stop the search after the specified number of seconds |
 | `--fuzzy` | Enable fuzzy search (Highlighting and counting matches are disabled in this mode if `--word` is not enabled to prevent the program from slowing down). except when `--expr` is enabled, in which case you can make it fuzzy by putting `f` before term: `f"foo"` |
 | `--fuzzy-level` | Fuzzy matching threshold (0-99). Higher values require closer matches (default: `80`) |
 | `--size` | Limit results based on the size of files |
 | `--archive` | Enable search within archive files (e.g. `zip`, `rar`, `7z`, `gz`, `bz2`, `xz`, `tar`, `tar.gz`, `tar.bz2`, `tar.xz`) |
-| `--depth` | Maximum nested archive depth. Example: 2 allows searching up to two archive levels |
+| `--arc-depth` | Limit nested archive to given depth range. By default, there is no limit |
 | `--arc-ext`, `--arc-exc-ext` | Filter by file extension inside archive files |
 | `--arc-include`, `--arc-exclude` | Limit search results to specific set of directories or files inside archive files |
 | `--arc-size` | Limit results based on the size of files in the archive |
@@ -147,7 +149,7 @@ Example:
 psk "hello world"
 ```
 
-**Note:** To use case-sensitive, whole-word matching, regular expression search, and fuzzy search when `--expr` is enabled, we can use [expression prefixes](#expression-prefixes).
+> **Note:** To use case-sensitive, whole-word matching, regular expression search, and fuzzy search when `--expr` is enabled, we can use [expression prefixes](#expression-prefixes).
 
 ### Case Sensitive Search
 
@@ -335,7 +337,51 @@ simultaneously.
 
 Allowed modes: `r`, `c`, `w`, `f`, `rc`, `cr`, `cw`, `wc`, `cf`, `fc`, `wf`, `fw`, `cwf`, `cfw`, `wcf`, `wfc`, `fcw`, `fwc`
 
-**Note:** Whole word matching and regex matching cannot be used at the same time, because we can use `\b` in regex to enable whole word matching: `r"\btext\b"`
+> **Note:** Whole word matching and regex matching cannot be used at the same time, because we can use `\b` in regex to enable whole word matching: `r"\btext\b"`
+
+## Context
+
+Show context lines around each match. The value is specified as `BEFORE:AFTER`:
+
+```bash
+--context 2       # 2 lines before and after
+--context 2:0     # 2 lines before, none after
+--context 0:2     # none before, 2 lines after
+--context 2:5     # 2 lines before, 5 lines after
+--context 2:      # 2 lines before, none after
+--context :2      # none before, 2 lines after
+--context 0       # matching lines only
+```
+
+Nearby matches whose context ranges overlap or directly touch are combined into a single group.
+
+## Depth
+
+Controls how deep the search goes inside directories.
+
+A depth of `0` means that only base path's immediate contents are searched; subdirectories are not entered.
+
+```text
+project/                  ← base directory
+├── file.txt              ← depth 0
+├── folder1/              ← depth 0
+│   ├── file.txt          ← depth 1
+│   └── folder2/          ← depth 1
+│       └── file.txt      ← depth 2
+```
+
+`--depth` can be specified multiple times to search non-contiguous depth ranges:
+
+```bash
+--depth 0              # Direct contents only
+--depth 1              # One level inside
+--depth 2:4            # Depths 2 through 4
+--depth 2 --depth 5:7  # Depths 2 and 5 through 7
+--depth :2             # Depths 0 through 2
+--depth 3:             # Depth 3 and deeper
+```
+
+If `--depth` is not specified, the search has no depth limit.
 
 ## Extension Filters
 
@@ -373,7 +419,7 @@ psk TODO \
 
 Skip those paths.
 
-**Note:** The include and exclude paths will be combined with path argument.
+> **Note:** The include and exclude paths will be combined with path argument.
 
 ## Regex Path Filters
 
@@ -426,7 +472,7 @@ psk config \
 
 Files between `1 MiB` and `10 MiB` will not match.
 
-**Note:** Directory sizes are not calculated recursively. When `--size` is used, directories are automatically excluded from the search results.
+> **Note:** Directory sizes are not calculated recursively. When `--size` is used, directories are automatically excluded from the search results.
 
 ## Archive Search
 
@@ -458,15 +504,24 @@ backup.zip::source.7z::notes.txt
 
 ### Archive Depth
 
-Limit recursion depth:
+The concept of depth in archive is different from `--depth`. Depth in archive is calculated based on nested archives. Each archive that is inside another archive counts as one level of depth.
+
+| Syntax | Meaning                                                  |
+| ------ | -------------------------------------------------------- |
+| `2`    | exactly `2nd` depth                                      |
+| `:2`   | `2nd` depth or lower                                     |
+| `2:`   | `2nd` depth or higher                                    |
+| `2:4`  | between `2` and `4` (Both range boundaries are included) |
+
+`--arc-depth` can be specified multiple times:
 
 ```bash
-psk TODO --archive --depth 2
+psk TODO --archive --arc-depth :2 --arc-depth 5:
 ```
 
-Meaning `archive level 1` and `archive level 2` will be searched. Deeper levels will be skipped.
+Meaning `archive level 3` and `archive level 4` won't be searched.
 
-**Note:** `--depth 0` means perform the search only within this current archive and don't enter nested archives.
+> **Note:** `--arc-depth 0` means perform the search only within this current archive and don't enter nested archives.
 
 ## Archive Filters
 
@@ -506,7 +561,7 @@ This works exactly like the [--size](#size-filtering) option.
 psk TODO --archive --arc-size 10m:40m
 ```
 
-**Note:** Archive directory sizes are usually reported as zero by archive formats, so directory search is disabled if this filter is enabled to avoid incorrect results.
+> **Note:** Archive directory sizes are usually reported as zero by archive formats, so directory search is disabled if this filter is enabled to avoid incorrect results.
 
 ## RAR Backend
 

{pseek-3.1.1 → pseek-3.2.0}/pseek/archive.py

@@ -1,6 +1,6 @@
 import io
 from pathlib import Path
-from .utils import get_path_suffix, EXCLUDED_EXTENSIONS
+from .utils import get_path_suffix, is_binary
 # Archive modules
 import zipfile, py7zr, tarfile, gzip, bz2, lzma, rarfile
 
@@ -39,7 +39,7 @@ def archive_should_skip(path_info: Path, config, p_size: float, file_ext, is_dir
     return False
 
 
-def extract_names_from_archive(file_path: Path, config, depth: int | None = None,
+def extract_names_from_archive(file_path: Path, config, depth: int = -1,
                                file_bytes: bytes | None = None, parent_label: list[str] | None = None):
     """
     Recursively extract files and directories name from archive files.
@@ -57,8 +57,7 @@ def extract_names_from_archive(file_path: Path, config, depth: int | None = None
 
     file_ext = get_path_suffix(file_path)
     label_prefix = [*parent_label, str(file_path)] if parent_label is not None else []
-    if depth is None:
-            depth = config.depth
+    new_depth = depth + 1
 
     try:
         # Decide the stream source: from disk or memory
@@ -72,8 +71,6 @@ def extract_names_from_archive(file_path: Path, config, depth: int | None = None
                     name = Path(info.filename)
                     new_path_ext = get_path_suffix(name)
                     is_dir = info.is_dir()
-                    # At each recursion, subtract 1 from depth if it's set
-                    new_depth = None if depth is None else depth - 1
 
                     if not archive_should_skip(
                             name,
@@ -82,10 +79,11 @@ def extract_names_from_archive(file_path: Path, config, depth: int | None = None
                             new_path_ext,
                             is_dir
                     ):
-                        yield label_prefix, name, is_dir
+                        if any(mi <= new_depth <= ma for mi, ma in config.arc_depth):
+                            yield label_prefix, name, is_dir
 
                         # Check if this is a nested archive
-                        if new_path_ext in ARCHIVE_EXTS[:-3] and (new_depth is None or new_depth >= 0):
+                        if new_path_ext in ARCHIVE_EXTS[:-3] and any(new_depth < d[1] for d in config.arc_depth):
                             yield from extract_names_from_archive(
                                 name,
                                 config,
@@ -100,7 +98,6 @@ def extract_names_from_archive(file_path: Path, config, depth: int | None = None
                     name = Path(info.filename)
                     new_path_ext = get_path_suffix(name)
                     is_dir = info.is_directory
-                    new_depth = None if depth is None else depth - 1
 
                     if not archive_should_skip(
                             name,
@@ -109,9 +106,10 @@ def extract_names_from_archive(file_path: Path, config, depth: int | None = None
                             new_path_ext,
                             is_dir
                     ):
-                        yield label_prefix, name, is_dir
+                        if any(mi <= new_depth <= ma for mi, ma in config.arc_depth):
+                            yield label_prefix, name, is_dir
 
-                        if new_path_ext in ARCHIVE_EXTS[:-3] and (new_depth is None or new_depth >= 0):
+                        if new_path_ext in ARCHIVE_EXTS[:-3] and any(new_depth < d[1] for d in config.arc_depth):
                             file_data = z.read([info.filename]).get(info.filename)
                             if file_data is None:
                                 continue
@@ -138,7 +136,6 @@ def extract_names_from_archive(file_path: Path, config, depth: int | None = None
                     name = Path(member.name)
                     new_path_ext = get_path_suffix(name)
                     is_dir = member.isdir()
-                    new_depth = None if depth is None else depth - 1
 
                     if not archive_should_skip(
                             name,
@@ -147,9 +144,10 @@ def extract_names_from_archive(file_path: Path, config, depth: int | None = None
                             new_path_ext,
                             is_dir
                     ):
-                        yield label_prefix, name, is_dir
+                        if any(mi <= new_depth <= ma for mi, ma in config.arc_depth):
+                            yield label_prefix, name, is_dir
 
-                        if new_path_ext in ARCHIVE_EXTS[:-3] and (new_depth is None or new_depth >= 0):
+                        if new_path_ext in ARCHIVE_EXTS[:-3] and any(new_depth < d[1] for d in config.arc_depth):
                             f = tf.extractfile(member)
                             if f is None:
                                 continue
@@ -165,7 +163,7 @@ def extract_names_from_archive(file_path: Path, config, depth: int | None = None
         return  # silently skip invalid or unreadable archives
 
 
-def extract_text_from_archive(file_path: Path, config, depth: int | None = None,
+def extract_text_from_archive(file_path: Path, config, depth: int = -1,
                               file_bytes: bytes | None = None, parent_label: list[str] | None = None):
     """
     Recursively extract (path_label, text_content) from any archive file.
@@ -183,8 +181,7 @@ def extract_text_from_archive(file_path: Path, config, depth: int | None = None,
 
     file_ext = get_path_suffix(file_path)
     label_prefix = [*parent_label, str(file_path)] if parent_label is not None else []
-    if depth is None:
-            depth = config.depth
+    new_depth = depth + 1
 
     try:
         # Decide the stream source: from disk or memory
@@ -195,10 +192,10 @@ def extract_text_from_archive(file_path: Path, config, depth: int | None = None,
             opener = {'zip': zipfile.ZipFile, 'rar': rarfile.RarFile}[file_ext]
             with opener(file_stream) as f:
                 for info in f.infolist():
+                    if info.is_dir():
+                        continue
+                    
                     file_name = Path(info.filename)
-                    data = f.read(info)
-                    # At each recursion, subtract 1 from depth if it's set
-                    new_depth = None if depth is None else depth - 1
                     new_path_ext = get_path_suffix(file_name)
                     
                     if archive_should_skip(
@@ -209,22 +206,33 @@ def extract_text_from_archive(file_path: Path, config, depth: int | None = None,
                     ):
                         continue
 
+                    with f.open(info) as entry:
+                        head = entry.read(8192)
+
+                        if is_binary(head) and new_path_ext not in ARCHIVE_EXTS:
+                            continue
+
+                        # 8 KiB has already been consumed from stream. If we use entry.read(), we will lose that 8 KiB
+                        data = head + entry.read()
+
                     # Check if this is a nested archive
-                    if new_path_ext in ARCHIVE_EXTS and (new_depth is None or new_depth >= 0):
-                        yield from extract_text_from_archive(file_name, config, new_depth, data, label_prefix)
-                    elif not (info.is_dir() or new_path_ext in EXCLUDED_EXTENSIONS):
+                    if new_path_ext in ARCHIVE_EXTS:
+                        if any(new_depth < d[1] for d in config.arc_depth):
+                            yield from extract_text_from_archive(file_name, config, new_depth, data, label_prefix)
+                    elif any(mi <= new_depth <= ma for mi, ma in config.arc_depth):
                         yield [*label_prefix, str(file_name)], data
         # Handle 7Z archives
         elif file_ext == '7z':
             with py7zr.SevenZipFile(file_stream, mode='r') as archive:
                 for info in archive.list():
+                    if info.is_directory:
+                        continue
+                    
                     file_data = archive.read([info.filename]).get(info.filename)
                     if file_data is None:
                         continue
 
                     file_name = Path(info.filename)
-                    data = file_data.read()
-                    new_depth = None if depth is None else depth - 1
                     new_path_ext = get_path_suffix(file_name)
                     
                     if archive_should_skip(
@@ -234,10 +242,16 @@ def extract_text_from_archive(file_path: Path, config, depth: int | None = None,
                         new_path_ext
                     ):
                         continue
-
-                    if new_path_ext in ARCHIVE_EXTS and (new_depth is None or new_depth >= 0):
-                        yield from extract_text_from_archive(file_name, config, new_depth, data, label_prefix)
-                    elif not (info.is_directory or new_path_ext in EXCLUDED_EXTENSIONS):
+                    
+                    head = file_data.read(8192)
+                    if is_binary(head) and new_path_ext not in ARCHIVE_EXTS:
+                        continue
+                    
+                    data = head + file_data.read()
+                    if new_path_ext in ARCHIVE_EXTS:
+                        if any(new_depth < d[1] for d in config.arc_depth):
+                            yield from extract_text_from_archive(file_name, config, new_depth, data, label_prefix)
+                    elif any(mi <= new_depth <= ma for mi, ma in config.arc_depth):
                         yield [*label_prefix, str(file_name)], data
         # Handle TAR and compressed TAR formats
         elif file_ext in ('tar', 'tar.gz', 'tar.bz2', 'tar.xz'):
@@ -250,13 +264,14 @@ def extract_text_from_archive(file_path: Path, config, depth: int | None = None,
 
             with tarfile.open(fileobj=file_stream, mode=mode) as tf:
                 for member in tf.getmembers():
+                    if member.isdir():
+                        continue
+                    
                     f = tf.extractfile(member)
                     if f is None:
                         continue
 
                     file_name = Path(member.name)
-                    data = f.read()
-                    new_depth = None if depth is None else depth - 1
                     new_path_ext = get_path_suffix(file_name)
                     
                     if archive_should_skip(
@@ -266,10 +281,16 @@ def extract_text_from_archive(file_path: Path, config, depth: int | None = None,
                         new_path_ext
                     ):
                         continue
+                    
+                    head = f.read(8192)
+                    if is_binary(head) and new_path_ext not in ARCHIVE_EXTS:
+                        continue
 
-                    if new_path_ext in ARCHIVE_EXTS and (new_depth is None or new_depth >= 0):
-                        yield from extract_text_from_archive(file_name, config, new_depth, data, label_prefix)
-                    elif not (member.isdir() or new_path_ext in EXCLUDED_EXTENSIONS):
+                    data = head + f.read()
+                    if new_path_ext in ARCHIVE_EXTS:
+                        if any(new_depth < d[1] for d in config.arc_depth):
+                            yield from extract_text_from_archive(file_name, config, new_depth, data, label_prefix)
+                    elif any(mi <= new_depth <= ma for mi, ma in config.arc_depth):
                         yield [*label_prefix, str(file_name)], data
         # Handle single compressed files like .gz, .bz2, .xz
         elif file_ext in ARCHIVE_EXTS[-3:]: