Metadata-Version: 2.4
Name: pseek
Version: 3.0.0
Summary: Pseek is a Python CLI toolkit to search files, folders, and text
Author-email: Arian <ariannasiri86@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ArianN8610/pysearch
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click==8.1.8
Requires-Dist: lark==1.2.2
Requires-Dist: py7zr==1.0.0
Requires-Dist: rarfile==4.2
Requires-Dist: rapidfuzz==3.13.0
Dynamic: license-file

# Pseek

Fast and powerful command-line search tool for finding files, directories, and text content. 

## Features

* Search file names
* Search directory names
* Search file contents
* Search inside archive files
* Boolean query expressions (`and`, `or`, `not`)
* Regular expressions
* Fuzzy matching
* Whole-word matching
* Case-sensitive search
* Archive recursion depth control
* Extension filters
* Path filters
* Size filtering
* Full path output
* Highlight matches in output
* Cross-platform (Linux, macOS, Windows)

## Installation

### Install from PyPI (Recommended)

```bash
pip install pseek
```

### Install from Source

```bash
git clone https://github.com/ArianN8610/pysearch.git

cd pysearch

python -m venv venv

# Activate virtual environment

pip install click==8.1.8 lark==1.2.2 py7zr==1.0.0 rarfile==4.2 rapidfuzz==3.13.0
```

## Basic Usage

```bash
psk <query> [options]
```

Example:

```bash
psk "error"
```

If no search type is specified, Pseek searches:

- File names
- Directory names
- File contents

simultaneously.

## Command Options

| Option                           | Description                                                                                                                                                                                                                                                      |
|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--path`                         | Base directory to search in (default: current directory `.`)                                                                                                                                                                                                     |
| `--file`                         | Search only in file names                                                                                                                                                                                                                                        |
| `--directory`                    | Search only in directory names                                                                                                                                                                                                                                   |
| `--content`                      | Search within file contents                                                                                                                                                                                                                                      |
| `--ext`, `--exclude-ext`         | Filter by file extension (e.g., `txt`, `log`)                                                                                                                                                                                                                    |
| `--case-sensitive`               | Make the search case-sensitive (except when `--expr` is enabled, in which case you can make it case sensitive by putting `c` before term: `c"foo"`)                                                                                                              |
| `--regex`                        | Use regular expressions to search (except when `--expr` is enabled, in which case you can make it regex by putting `r` before term: `r"foo"`)                                                                                                                    |
| `--include`, `--exclude`         | Limit search results to specific set of directories or files                                                                                                                                                                                                     |
| `--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`                                                                                                  |
| `--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`)                                                                                                                                                                            |
| `--max-size`, `--min-size`       | Specify maximum and minimum sizes for files and directories                                                                                                                                                                                                      |
| `--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-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-max`, `--arc-min`         | Specify maximum and minimum sizes for files inside archive files (It doesn't work for directories because their size is zero in archive files)                                                                                                                   |
| `--rar-backend`                  | Path to RAR backend tool (e.g. UnRAR.exe, ...)                                                                                                                                                                                                                   |
| `--full-path`                    | Display full path of files and directories                                                                                                                                                                                                                       |
| `--paths-only`                   | Only show matching file paths for content search                                                                                                                                                                                                                 |

## Search Types

### Search File Names

```bash
psk "config" --file
```

### Search Directory Names

```bash
psk "backup" --directory
```

### Search File Contents

```bash
psk "TODO" --content
```

### Search Everywhere

```bash
psk "error"
```

Equivalent to:

```bash
psk "error" --file --directory --content
```

## Query Modes

By default, the query is treated as plain text.

Example:

```bash
psk "hello world"
```

### Case Sensitive Search

```bash
psk "Hello" --case-sensitive
```

Matches:

```text
Hello
```

Does not match:

```text
hello
HELLO
```

### Whole Word Search

```bash
psk "cat" --word
```

Matches:

```text
cat
```

Does not match:

```text
cats
concatenate
```

### Regular Expression Search

Enable regex mode:

```bash
psk "error\d+" --regex
```

Example matches:

```text
error1
error25
error999
```

## Fuzzy Search

Fuzzy search allows approximate matching.

Example:

```bash
psk "apple" --fuzzy
```

Can match:

```text
appl
appel
aple
```

### Fuzzy Similarity Threshold

```bash
psk "apple" --fuzzy --fuzzy-level 90
```

Range: `0-99`

Higher values require closer matches.

Examples:

| Level | Strictness  |
|-------|-------------|
| 60    | Loose       |
| 80    | Recommended |
| 95    | Very strict |

Default: `80`

## Expression Queries

Expression mode enables logical search expressions.

Enable:

```bash
psk '("error" or "warning") and not "debug"' --expr
```

### Supported Operators

#### AND

```bash
psk '"foo" and "bar"' --expr
```

Both terms must match.

#### OR

```bash
psk '"foo" or "bar"' --expr
```

At least one term must match.

#### NOT

```bash
psk 'not "foo"' --expr
```

Exclude matches containing the term.

#### PARENTHESES

```bash
psk '("foo" or "bar") and not "baz"' --expr
```

Used for grouping expressions.

### Expression Prefixes

Each term can have its own search mode.

#### Regex

```text
r"pattern"
```

Example:

```bash
psk 'r"error\d+"' --expr
```

#### Case Sensitive

```text
c"text"
```

Example:

```bash
psk 'c"Error"' --expr
```

#### Whole Word

```text
w"text"
```

Example:

```bash
psk 'w"cat"' --expr
```

#### Fuzzy

```text
f"text"
```

Example:

```bash
psk 'f"apple"' --expr
```

### Combined Prefixes

Prefixes can be combined.

Examples:

```text
rc"text"
cw"text"
cf"text"
wcf"text"
```

Example:

```bash
psk 'rc"Error\d+"' --expr
```

Meaning:

- regex
- case-sensitive

simultaneously.

Allowed modes: `r`, `c`, `w`, `f`, `rc`, `cr`, `cw`, `wc`, `cf`, `fc`, `wf`, `fw`, `cwf`, `cfw`, `wcf`, `wfc`, `fcw`, `fwc`

## Extension Filters

Include only specific extensions:

```bash
psk "TODO" --ext py --ext js
```

Exclude extensions:

```bash
psk "TODO" --exclude-ext exe --exclude-ext dll
```

## Path Filters

### Include Paths

```bash
psk "TODO" \
    --include src \
    --include tests
```

Only search inside those paths.

### Exclude Paths

```bash
psk "TODO" \
    --exclude build \
    --exclude .git
```

Skip those paths.

## Regex Path Filters

### Include

```bash
psk "TODO" \
    --re-include "src/.*"
```

### Exclude

```bash
psk "TODO" \
    --re-exclude "node_modules|dist"
```

## Size Filters

Limit search by size.

Maximum:

```bash
psk "TODO" --max-size 100
```

Only search files/directories up to: `100 MB`

Minimum:

```bash
psk "TODO" --min-size 10
```

Only search files/directories larger than: `10 MB`

## Archive Search

Enable archive support:

```bash
psk "TODO" --archive
```

Supported formats: `zip`, `rar`, `7z`, `gz`, `bz2`, `xz`, `tar`, `tar.gz`, `tar.bz2`, `tar.xz`

### Nested Archives

Pseek supports recursive archive traversal.

Example:

```text
backup.zip
 └── source.7z
      └── notes.txt
```

Pseek can search:

```text
backup.zip::source.7z::notes.txt
```

### Archive Depth

Limit recursion depth:

```bash
psk "TODO" --archive --depth 2
```

Meaning:

```text
archive level 1
archive level 2
```

will be searched.

Deeper levels will be skipped.

## Archive Filters

### Extension Filters

```bash
psk "TODO" --archive --arc-ext py
```

Only search `.py` files inside archives.

```bash
psk "TODO" --archive --arc-exc-ext jpg
```

Exclude `.jpg` files inside archives.

### Path Filters

Include:

```bash
psk "TODO" --archive --arc-include src
```

Exclude:

```bash
psk "TODO" --archive --arc-exclude cache
```

### Size Filters

Maximum:

```bash
psk "TODO" --archive --arc-max 10
```

Minimum:

```bash
psk "TODO" --archive --arc-min 1
```

Values are in MB.

**Note:** Archive directory sizes are usually reported as zero by archive formats, therefore archive size filtering is mainly useful for files.

## RAR Backend

RAR archives require an external backend that must be set up.

Supported backends include:

- UnRAR
- 7-Zip
- BSDTar
- Unar

Example:

```bash
psk "unrar" --rar-backend /usr/bin/unrar
```

Windows:

```bash
psk "unrar" --rar-backend "C:\Program Files\WinRAR\UnRAR.exe"
```

Enter the file type in the query (e.g. `unrar`, `bsdtar`, `unar`, `7z`).

## Output Options

### Show Full Paths

```bash
psk "TODO" --full-path
```

### Paths Only

Only display matching file paths:

```bash
psk "TODO" --content --paths-only
```

Useful for very large result sets.

## Timeout

Stop the search automatically after a specified number of seconds.

Example:

```bash
psk "TODO" --timeout 30
```

If the search exceeds the limit, it will be terminated.

## Requirements

* Python `3.8+`
* `unrar`, `bsdtar`, `unar` or `7zip` for the [rarfile](https://pypi.org/project/rarfile/) library to support searching inside `.rar` files (optional)
