### Install patool using pip

Source: https://github.com/wummel/patool/blob/master/doc/install.md

Installs the patool library using Python's package installer, pip. This is the recommended and simplest installation method if pip is available on your system.

```Shell
pip install patool
```

--------------------------------

### Install patool from source for current user

Source: https://github.com/wummel/patool/blob/master/doc/install.md

Installs patool from its source code into the user's home directory. This method requires manual adjustment of the PATH and PYTHONPATH environment variables to ensure patool is discoverable.

```Shell
python setup.py install --home $HOME
```

--------------------------------

### Install essential Cygwin packages for patool on Windows

Source: https://github.com/wummel/patool/blob/master/doc/install.md

Runs the Cygwin installer in quiet mode to install 'file', 'grep', and 'diff' packages. These packages enhance patool's archive detection and functionality on Windows, especially for files with missing or non-standard extensions.

```Shell
setup-x86_64.exe -q -p file,grep,diff
```

--------------------------------

### Install patool from source as root

Source: https://github.com/wummel/patool/blob/master/doc/install.md

Installs patool directly from its source code with system-wide root privileges. This method is suitable for system administrators or when installing to a global Python environment.

```Shell
sudo python setup.py install
```

--------------------------------

### Initialize patool Development Environment

Source: https://github.com/wummel/patool/blob/master/doc/development.md

Runs the development installation script and initializes the project using make. This process installs required system packages, creates a virtual Python environment in '.venv/', and installs necessary Python modules for development.

```Shell
scripts/install_dev.sh
make init
```

--------------------------------

### Install Patool Bash Completion

Source: https://github.com/wummel/patool/blob/master/README.md

Instructions for setting up bash completion for the `patool` command using the `argcomplete` Python package. This enables tab-completion for commands and options after installation.

```Shell
apt-get install python3-argcomplete
eval "$(register-python-argcomplete patool)"
```

--------------------------------

### Configure environment variables for user-installed patool

Source: https://github.com/wummel/patool/blob/master/doc/install.md

Adds the user-specific installation paths for patool to the shell's PYTHONPATH and PATH environment variables. This allows the system to locate and execute patool scripts and modules after a user-level source installation.

```Shell
export PYTHONPATH=$HOME/lib/python
export PATH=$PATH:$HOME/bin
```

--------------------------------

### Clone patool Repository

Source: https://github.com/wummel/patool/blob/master/doc/development.md

Clones the patool source code repository from GitHub and changes into the base project directory to begin development.

```Shell
git clone https://github.com/wummel/patool.git && cd patool
```

--------------------------------

### Patool Command-Line Usage Examples

Source: https://github.com/wummel/patool/blob/master/doc/web/source/index.md

Demonstrates various command-line operations with Patool, including extracting, testing, listing, creating, comparing, searching, and repacking archives. These examples showcase the simplicity of Patool's interface for common archive management tasks.

```bash
# extract two archives
patool extract archive.zip otherarchive.rar

# test if archive is intact
patool test --verbose dist.tar.gz

# list files inside an archive
patool list package.deb

# create a new archive
patool create --verbose myfiles.zip file1.txt dir/

# list differences between two archive contents
patool diff release1.0.tar.gz release2.0.zip

# search archive contents
patool search "def urlopen" python-3.3.tar.gz

# compress the archive in a different format
patool repack linux-2.6.33.tar.gz linux-2.6.33.tar.bz2
```

--------------------------------

### Install Patool using pip on Windows

Source: https://github.com/wummel/patool/blob/master/doc/web/source/index.md

This command installs the Patool utility on Windows using the Python launcher. It requires Python 3.11 or later.

```bash
py.exe -m pip install patool
```

--------------------------------

### Creating Archives with patool

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Example of creating a new archive file from specified files and directories using the `patool create` command, with verbose output. The archive format is determined by the output file extension.

```Shell
patool --verbose create myfiles.zip file1.txt dir/
```

--------------------------------

### Patool Python API Usage Examples

Source: https://github.com/wummel/patool/blob/master/README.md

This section demonstrates how to use the `patoolib` Python library to programmatically interact with archives. It includes examples for extracting, testing, listing, creating, comparing, searching, repacking, and checking if a file is an archive. Note that `PatoolError` is raised on errors.

```Python
import patoolib
patoolib.extract_archive("archive.zip", outdir="/tmp")
patoolib.test_archive("dist.tar.gz", verbosity=1)
patoolib.list_archive("package.deb")
patoolib.create_archive("/path/to/myfiles.zip", ("file1.txt", "dir/"))
patoolib.diff_archives("release1.0.tar.gz", "release2.0.zip")
patoolib.search_archive("def urlopen", "python3.3.tar.gz")
patoolib.repack_archive("linux-2.6.33.tar.gz", "linux-2.6.33.tar.bz2")
patoolib.is_archive("package.deb")
```

--------------------------------

### Run patool Tests

Source: https://github.com/wummel/patool/blob/master/doc/development.md

Executes the test suite for the patool project using make. This step is crucial for verifying code changes and ensuring functionality across different architectures and Python versions (3.11, 3.12, 3.13) as part of the GitHub workflow.

```Shell
make test
```

--------------------------------

### Patool Command-Line Archive Management Examples

Source: https://github.com/wummel/patool/blob/master/README.md

This section provides examples of common archive management tasks using the `patool` command-line utility. It covers extracting, testing, listing, creating, comparing, searching, and repacking archives, including options for password protection and verbose output.

```Shell
# Extract several archives with different formats
patool extract archive.zip otherarchive.rar

# Extract archive with password
patool extract --password somepassword archive.rar

# Test archive integrity
patool test --verbose dist.tar.gz

# List files stored in an archive
patool list package.deb

# Create a new archive
patool create --verbose /path/to/myfiles.zip file1.txt dir/

# Create a new archive with password
patool create --verbose --password somepassword /path/to/myfiles.zip file1.txt dir/

# Show differences between two archives
patool diff release1.0.tar.gz release2.0.zip

# Search for text inside archives
patool search "def urlopen" python-3.3.tar.gz

# Repackage an archive in a different format
patool repack linux-2.6.33.tar.gz linux-2.6.33.tar.bz2
```

--------------------------------

### Install Patool using pip on Linux/macOS

Source: https://github.com/wummel/patool/blob/master/doc/web/source/index.md

This command installs the Patool utility globally on Unix-like systems using pip. It requires Python 3.11 or later and administrative privileges.

```bash
sudo pip install patool
```

--------------------------------

### Repacking Archives with patool

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Example of repacking an archive from one format to another using the `patool repack` command. This converts a gzipped tarball to a bzipped tarball.

```Shell
patool repack linux-2.6.33.tar.gz linux-2.6.33.tar.bz2
```

--------------------------------

### Define Shell Aliases for patool Commands

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Examples of defining common Unix shell aliases to shorten frequently used patool commands, thereby saving typing and improving command-line efficiency.

```Shell
alias pl='patool list'
alias px='patool extract'
alias pc='patool create'
alias pd='patool diff'
```

--------------------------------

### Searching Archive Contents with patool

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Shows how to search for specific content within an archive file using the `patool search` command. This example searches for the string "def urlopen" in a Python tarball.

```Shell
patool search "def urlopen" python-3.3.tar.gz
```

--------------------------------

### patool Command Line Synopsis

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

General syntax for using the patool command-line tool, showing available global options, commands, and command-specific arguments.

```Shell
patool [global-options] (list|test|extract|create|diff|search|repack|formats|version) [command-options] [command-arguments]...
```

--------------------------------

### Accessing patool Help Options

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Provides help documentation for the patool utility itself or for specific commands. This is useful for understanding command-line arguments and usage details.

```Shell
patool --help
patool extract --help
```

--------------------------------

### patool create Command

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Documentation for the `create` command, used to compress and create a new archive from specified files and directories. The archive format is determined by the output file extension.

```APIDOC
COMMAND: create
  patool create <archive> <file-or-directory>...

  Description: Create an archive from given files. All of the given files to add to the archive must be readable by the current user. The format of the archive to create is determined by the archive file extension. If the archive program has options to maximize
```

--------------------------------

### Comparing Archives with patool

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Demonstrates how to compare the contents of two different archive files using the `patool diff` command.

```Shell
patool diff release1.0.tar.xz release2.0.zip
```

--------------------------------

### Extracting Archives with patoolib in Python

Source: https://github.com/wummel/patool/blob/master/doc/api.md

Demonstrates how to extract an archive using `patoolib.extract` and handle potential `PatoolError` exceptions. This snippet shows basic usage for integrating patoolib into Python applications.

```Python
import patoolib
try:
    patoolib.extract("myarchive.zip", verbose=True)
    print("Success.")
except patoolib.util.PatoolError as msg:
    print("Error:", msg)
```

--------------------------------

### Listing Archive Contents with patool

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Illustrates how to list the files contained within an archive using the `patool list` command.

```Shell
patool list package.deb
```

--------------------------------

### patool list Command

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Documentation for the `list` command, which displays the contents of specified archive files.

```APIDOC
COMMAND: list
  patool list <archive>...

  Description: List files in archives.
```

--------------------------------

### patoolib.repack_archive API Reference

Source: https://github.com/wummel/patool/blob/master/doc/api.md

Extracts the contents of an existing archive and repacks them into a new archive. It checks that the source archive exists and is readable, and that the new archive does not already exist to prevent overwriting.

```APIDOC
def repack_archive(archive, archive_new, verbosity=0)
  archive: The path to the source archive file.
  archive_new: The path for the new archive file to create.
  verbosity: An integer controlling the verbosity level (defaults to 0).
```

--------------------------------

### List Supported Archive Formats with patool

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Displays all archive formats that patool currently supports on the system. This is determined by which helper applications are available and accessible.

```APIDOC
patool formats
```

--------------------------------

### patoolib.create_archive API Reference

Source: https://github.com/wummel/patool/blob/master/doc/api.md

Creates a new archive from a list of filenames. The archive type is inferred from the output archive's filename extension. It checks for existing archives to prevent overwriting and ensures all input files exist and are readable.

```APIDOC
def create_archive(archive, filenames, verbosity=0, program=None)
  archive: The path for the new archive file to create.
  filenames: A list of filenames to include in the archive.
  verbosity: An integer controlling the verbosity level (defaults to 0).
  program: The external archive program to use (defaults to auto-detection).
```

--------------------------------

### Extracting Archives with patool

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Demonstrates how to extract one or more archive files using the `patool extract` command. This command preserves the original archives and extracts contents to the current directory by default, or a specified output directory.

```Shell
patool extract archive.zip otherarchive.rar
```

--------------------------------

### Testing Archive Integrity with patool

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Shows how to test the integrity of an archive file using the `patool test` command, with verbose output to display more details about the operation and helper application output.

```Shell
patool --verbose test dist.tar.gz
```

--------------------------------

### patool Global Options

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Reference for global options that can be applied to any patool command, affecting its overall behavior such as verbosity or interactivity.

```APIDOC
GLOBAL OPTIONS:
  -v, --verbose
    Display more info about what patool does, and display the output of helper applications. Can be given multiple times to increase the output even more.
  -q, --quiet
    Work quietly, exept the commands formats and version still print their output. Conflicts with --verbose. If given twice suppresses error output from archive commands.
  --non-interactive
    Try to prevent any interactive user input (i.e. prompting for passwords or for overwriting duplicate files). Use this option with care since overwriting files or ignoring password prompts could lead to unintended consequences. This only works for archive programs that allow preventing user prompts. Currently those are arj, 7z and rar.
```

--------------------------------

### Display patool Version Information

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Prints the current version information for the patool utility, including copyright details.

```APIDOC
patool version
```

--------------------------------

### Compare Archives with patool diff

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Shows differences between two archives using the standard diff(1) program. The diff options used are -urN, providing a unified, recursive, and new-file-aware comparison.

```APIDOC
patool diff <archive1> <archive2>
```

--------------------------------

### patoolib.list_archive API Reference

Source: https://github.com/wummel/patool/blob/master/doc/api.md

Lists the contents of the specified archive filename to standard output. It verifies that the archive exists and is readable before attempting to list its contents.

```APIDOC
def list_archive(archive, verbosity=1, program=None)
  archive: The path to the archive file to list.
  verbosity: An integer controlling the verbosity level (defaults to 1).
  program: The external archive program to use (defaults to auto-detection).
```

--------------------------------

### Repack Archives to Different Formats with patool

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Extracts an existing archive and then re-compresses its contents into a new archive with a potentially different format. The target archive format is automatically determined by the file extension of the new archive_new.

```APIDOC
patool repack <archive> <archive_new>
```

--------------------------------

### patool extract Command

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Documentation for the `extract` command, used to decompress and extract files from one or more archives. It details the command's syntax, options, and behavior regarding output directories and error handling.

```APIDOC
COMMAND: extract
  patool extract [--outdir directory] <archive>...

  Description: Extract files from given archives. The original archives will never be removed and are left as is.

  Options:
    --outdir directory
      Extract to the given output directory. Default is to extract to the current working directory.

  Behavior:
    - If the archive contains exactly one file or directory, the archive contents are extracted directly to the output directory.
    - Else the files are extracted in a newly created subdirectory of the output directory, named after the archive filename without the extension.
    - All extracted files are ensured that they are readable by the current user.
    - If extracting an archive has an error in the middle of operation, patool does not remove the temporary extraction directory. This directory whose name starts with Unpack_ has all files that have been extracted before the error.
```

--------------------------------

### patoolib.diff_archives API Reference

Source: https://github.com/wummel/patool/blob/master/doc/api.md

Compares the contents of two archives by extracting them and recursively using the `diff(1)` program. It verifies that both archives exist and are readable before comparison.

```APIDOC
def diff_archives(archive1, archive2, verbosity=0)
  archive1: The path to the first archive file.
  archive2: The path to the second archive file.
  verbosity: An integer controlling the verbosity level (defaults to 0).
```

--------------------------------

### patoolib.search_archive API Reference

Source: https://github.com/wummel/patool/blob/master/doc/api.md

Searches for a given pattern within the contents of an archive file using `grep(1)`. It ensures the archive exists and is readable before performing the search.

```APIDOC
def search_archive(pattern, archive, verbosity=0)
  pattern: The pattern to search for within the archive.
  archive: The path to the archive file to search.
  verbosity: An integer controlling the verbosity level (defaults to 0).
```

--------------------------------

### Search Archive Contents with patool search

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Unpacks the specified archive into a temporary directory and searches its contents for a given pattern using the grep(1) program. The grep options used are -r; additional options can be supplied via the GREP_OPTIONS environment variable.

```APIDOC
patool search <pattern> <archive>
```

--------------------------------

### Patoolib Python API Reference

Source: https://github.com/wummel/patool/blob/master/doc/web/source/index.md

Reference for the `patoolib` Python module, providing functions to programmatically interact with archive files. Errors are raised as `PatoolError`, and log output goes to `sys.stdout` and `sys.stderr`. Customization for specific archive programs is not supported.

```APIDOC
patoolib module:
  list_formats():
    description: Lists all archive formats supported by patool.
    returns: list[str]
  supported_formats(format_name: str):
    description: Checks if a specific archive format is supported.
    format_name: The name of the format to check (e.g., 'zip', 'tar').
    returns: bool
  list_archive(archive_path: str):
    description: Lists the contents of an archive file.
    archive_path: Path to the archive file.
    returns: list[str] (list of file paths inside archive)
  extract_archive(archive_path: str, destination_dir: str = '.'):
    description: Extracts the contents of an archive file.
    archive_path: Path to the archive file.
    destination_dir: Directory where contents will be extracted.
  test_archive(archive_path: str):
    description: Tests the integrity of an archive file.
    archive_path: Path to the archive file.
    returns: bool (True if intact, False otherwise)
  create_archive(archive_path: str, files_to_add: list[str]):
    description: Creates a new archive from specified files and directories.
    archive_path: Path for the new archive file.
    files_to_add: List of file and directory paths to include in the archive.
  diff_archives(archive1_path: str, archive2_path: str):
    description: Compares the contents of two archive files.
    archive1_path: Path to the first archive file.
    archive2_path: Path to the second archive file.
    returns: list[str] (list of differences)
  search_archive(archive_path: str, pattern: str):
    description: Searches for a pattern within the contents of an archive file.
    archive_path: Path to the archive file.
    pattern: The string pattern to search for.
    returns: list[str] (list of files containing the pattern)
  repack_archive(source_archive_path: str, target_archive_path: str):
    description: Repacks an archive from one format to another.
    source_archive_path: Path to the original archive file.
    target_archive_path: Path for the new archive file in the desired format.
  is_archive(file_path: str):
    description: Checks if a given file is an archive.
    file_path: Path to the file to check.
    returns: bool
```

--------------------------------

### Test Archives with patool

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

Tests the integrity of specified archives. If the underlying helper application does not support direct testing, patool will list the archive contents instead.

```APIDOC
patool test <archive>...
```

--------------------------------

### patoolib.extract_archive API Reference

Source: https://github.com/wummel/patool/blob/master/doc/api.md

Extracts the given archive filename to the current working directory or a specified output directory. It performs checks to ensure the archive exists and is readable before extraction.

```APIDOC
def extract_archive(archive, verbosity=0, outdir=None, program=None)
  archive: The path to the archive file to extract.
  verbosity: An integer controlling the verbosity level (defaults to 0).
  outdir: The directory to extract the archive contents into (defaults to current working directory).
  program: The external archive program to use (defaults to auto-detection).
```

--------------------------------

### patoolib.test_archive API Reference

Source: https://github.com/wummel/patool/blob/master/doc/api.md

Tests the integrity of the given archive filename. It ensures the archive exists and is readable prior to performing the test.

```APIDOC
def test_archive(archive, verbosity=0, program=None)
  archive: The path to the archive file to test.
  verbosity: An integer controlling the verbosity level (defaults to 0).
  program: The external archive program to use (defaults to auto-detection).
```

--------------------------------

### patool Command Rules

Source: https://github.com/wummel/patool/blob/master/doc/patool.txt

General rules that apply to all patool commands, ensuring data integrity and preventing unintended side effects during archive operations.

```APIDOC
COMMAND RULES:
  - Existing files are never overwritten.
  - The original archive will never be removed.
  - Files outside the output directory will never be created. This relies on archive program options to prevent unpacking of files with an absolute path name (e.g. --no-absolute-filenames for cpio(1)).
```

--------------------------------

### Patool Python Library (patoolib) API Reference

Source: https://github.com/wummel/patool/blob/master/README.md

Reference for the `patoolib` Python library, which allows programmatic interaction with archive files. It outlines the main functions available for archive operations, noting that log output goes to `sys.stdout`/`sys.stderr` and `PatoolError` is raised on errors.

```APIDOC
patoolib:
  extract_archive(archive: str, outdir: str)
    archive: Path to the archive file.
    outdir: Directory to extract contents to.
  test_archive(archive: str, verbosity: int)
    archive: Path to the archive file.
    verbosity: Verbosity level (e.g., 1 for verbose).
  list_archive(archive: str)
    archive: Path to the archive file.
  create_archive(archive_path: str, files: tuple)
    archive_path: Path for the new archive file.
    files: Tuple of files/directories to add to the archive.
  diff_archives(archive1: str, archive2: str)
    archive1: Path to the first archive.
    archive2: Path to the second archive.
  search_archive(text: str, archive: str)
    text: Text to search for within the archive.
    archive: Path to the archive file.
  repack_archive(source_archive: str, target_archive: str)
    source_archive: Path to the archive to repack.
    target_archive: Path for the new repacked archive.
  is_archive(file_path: str) -> bool
    file_path: Path to the file to check.
    Returns: True if the file is an archive, False otherwise.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.