### Install multivolumefile using pip

Source: https://github.com/miurahr/multivolume/blob/master/README.rst

Install the library using the pip package manager.

```bash
pip install multivolumefile
```

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

### Install multivolumefile using conda

Source: https://github.com/miurahr/multivolume/blob/master/README.rst

Install the library using the conda package manager from the conda-forge channel.

```bash
conda install -c conda-forge multivolumefile
```

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

### Instantiate MultiVolume with Custom Options

Source: https://context7.com/miurahr/multivolume/llms.txt

Directly instantiate the MultiVolume class for advanced configuration, such as custom volume sizes, extension formatting (digits or hex), and starting extension numbers.

```python
import multivolumefile

# Create multi-volume files with 10KB volumes and custom settings
with multivolumefile.MultiVolume(
    'output.7z',
    mode='wb',
    volume=10240,           # Volume size in bytes (10KB)
    ext_digits=3,           # Extension digits: .001, .002
    ext_start=0             # Start from .000
) as vol:
    vol.write(b'x' * 25000)  # Will create output.7z.000, output.7z.001, output.7z.002

# Hexadecimal extensions: .000, .001, ..., .00a, .00b, .00c
with multivolumefile.MultiVolume(
    'archive.bin',
    mode='wb',
    volume=1024,
    hex=True,               # Use hex extensions
    ext_digits=3,
    ext_start=0
) as vol:
    vol.write(b'data' * 5000)  # Creates .000 through .013 (hex)
```

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

### MultiVolume Class - Direct Instantiation

Source: https://context7.com/miurahr/multivolume/llms.txt

The MultiVolume class allows direct instantiation with advanced configuration options for volume size, extension formatting, and starting numbers.

```APIDOC
## MultiVolume Class - Direct Instantiation

### Description
Provides advanced configuration options for creating and managing multi-volume files, including custom volume sizes, extension digit formatting, hexadecimal extensions, and starting extension numbers.

### Method
`MultiVolume(filename, mode='rb', volume=10485760, ext_digits=4, ext_start=1, hex=False, **kwargs)`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The base filename for the multi-volume set.
- **mode** (string) - Required - The mode to open the file in (e.g., 'rb', 'wb').
- **volume** (int) - Optional - The size of each volume in bytes. Defaults to 10MB (10485760 bytes).
- **ext_digits** (int) - Optional - The number of digits for the volume extension (e.g., 3 for `.001`). Defaults to 4.
- **ext_start** (int) - Optional - The starting number for the volume extension. Defaults to 1.
- **hex** (bool) - Optional - If True, use hexadecimal extensions (e.g., `.00a`, `.00b`). Defaults to False.

### Request Example
```python
import multivolumefile

# Create multi-volume files with 10KB volumes and custom settings
with multivolumefile.MultiVolume(
    'output.7z',
    mode='wb',
    volume=10240,           # Volume size in bytes (10KB)
    ext_digits=3,           # Extension digits: .001, .002
    ext_start=0             # Start from .000
) as vol:
    vol.write(b'x' * 25000)

# Hexadecimal extensions
with multivolumefile.MultiVolume(
    'archive.bin',
    mode='wb',
    volume=1024,
    hex=True,               # Use hex extensions
    ext_digits=3,
    ext_start=0
) as vol:
    vol.write(b'data' * 5000)
```

### Response
#### Success Response (MultiVolume Object)
- **vol** (MultiVolume) - A file-like object for interacting with multi-volume files with custom configurations.

#### Response Example
```python
# Example of using the returned object
# vol.read(100)
# vol.write(b'more data')
```
```

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

### Get File Statistics with stat()

Source: https://context7.com/miurahr/multivolume/llms.txt

Retrieves aggregated file statistics from the first volume of a multi-volume file. Requires the file to be opened in binary read mode.

```python
import multivolumefile

with multivolumefile.open('archive.7z', mode='rb') as vol:
    st = vol.stat()
    print(f"Total size: {st.st_size} bytes")
    print(f"Mode: {st.st_mode}")
    print(f"Modified time: {st.st_mtime}")
    print(f"Access time: {st.st_atime}")
    print(f"Device: {st.st_dev}")
    print(f"UID: {st.st_uid}")
    print(f"GID: {st.st_gid}")
```

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

### Read Data with read(), readall(), readinto()

Source: https://context7.com/miurahr/multivolume/llms.txt

Read operations seamlessly handle data across volume boundaries. Use read() for chunked reading, readall() to get all data, and readinto() to populate a pre-allocated buffer.

```python
import multivolumefile
import hashlib

# Basic reading with chunked processing
with multivolumefile.open('archive.7z', mode='rb') as vol:
    sha = hashlib.sha256()
    while True:
        data = vol.read(8192)
        if not data:
            break
        sha.update(data)
    print(f"SHA256: {sha.hexdigest()}")

# Read all data at once
with multivolumefile.open('archive.7z', mode='rb') as vol:
    all_data = vol.readall()
    print(f"Total size: {len(all_data)} bytes")

# Read into pre-allocated buffer
with multivolumefile.open('archive.7z', mode='rb') as vol:
    buffer = bytearray(1024)
    vol.seek(5000)
    bytes_read = vol.readinto(buffer)
    print(f"Read {bytes_read} bytes into buffer")
```

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

### Navigate Position with seek() and tell()

Source: https://context7.com/miurahr/multivolume/llms.txt

Use seek() and tell() for standard file position navigation within the virtual multi-volume file. Supports SEEK_SET, SEEK_CUR, and SEEK_END modes, working across volume boundaries.

```python
import multivolumefile
import io

with multivolumefile.open('archive.7z', mode='rb') as vol:
    # Seek from beginning (SEEK_SET)
    pos = vol.seek(15000, io.SEEK_SET)
    print(f"Position: {pos}")  # 15000

    # Seek relative to current position (SEEK_CUR)
    vol.seek(40000)
    pos = vol.seek(-1001, io.SEEK_CUR)
    print(f"Position after relative seek: {pos}")  # 38999

    # Seek from end (SEEK_END)
    pos = vol.seek(-2337, io.SEEK_END)
    print(f"Position from end: {pos}")

    # Get current position
    current = vol.tell()
    print(f"Current position: {current}")
```

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

### open() - Open Multi-Volume Files

Source: https://context7.com/miurahr/multivolume/llms.txt

The open() function creates a MultiVolume file object for reading or writing split volume files. It automatically detects volume files with numeric extensions.

```APIDOC
## open() - Open Multi-Volume Files

### Description
Opens a MultiVolume file object for reading or writing split volume files. Automatically detects volume files with numeric extensions like `.0001`, `.0002`.

### Method
`open()`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The base filename for the multi-volume set.
- **mode** (string) - Required - The mode to open the file in (e.g., 'rb', 'wb').
- **volume** (int) - Optional - The size of each volume in bytes. Defaults to 10MB.

### Request Example
```python
import multivolumefile

# Reading multi-volume files
with multivolumefile.open('archive.7z', mode='rb') as vol:
    data = vol.read(1024)
    print(f"Read {len(data)} bytes")

# Writing multi-volume files with custom volume size
with multivolumefile.open('output.7z', mode='wb', volume=10240) as vol:
    vol.write(b'some data')
```

### Response
#### Success Response (MultiVolume Object)
- **vol** (MultiVolume) - A file-like object for interacting with multi-volume files.

#### Response Example
```python
# Example of using the returned object
# vol.read(100)
# vol.write(b'more data')
```
```

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

### read() / readall() / readinto() - Reading Data

Source: https://context7.com/miurahr/multivolume/llms.txt

Methods for reading data from multi-volume files, supporting seamless operations across volume boundaries.

```APIDOC
## read() / readall() / readinto() - Reading Data

### Description
Read operations work seamlessly across volume boundaries. `read()` reads up to a specified number of bytes, `readall()` reads the entire content, and `readinto()` reads into a pre-allocated buffer.

### Methods
- **read(size=-1)**: Reads and returns up to `size` bytes from the file. If `size` is negative or omitted, reads until EOF. Returns an empty bytes object on EOF.
- **readall()**: Reads and returns all remaining bytes from the file.
- **readinto(buffer)**: Reads bytes into the given mutable buffer and returns the number of bytes read. Returns 0 if EOF is reached immediately.

### Parameters
#### read(size)
- **size** (int) - Optional - The maximum number of bytes to read. Defaults to reading all remaining bytes.

#### readinto(buffer)
- **buffer** (bytearray or similar mutable buffer) - Required - The buffer to read data into.

### Request Example
```python
import multivolumefile
import hashlib

# Basic reading with chunked processing
with multivolumefile.open('archive.7z', mode='rb') as vol:
    sha = hashlib.sha256()
    while True:
        data = vol.read(8192)
        if not data:
            break
        sha.update(data)
    print(f"SHA256: {sha.hexdigest()}")

# Read all data at once
with multivolumefile.open('archive.7z', mode='rb') as vol:
    all_data = vol.readall()
    print(f"Total size: {len(all_data)} bytes")

# Read into pre-allocated buffer
with multivolumefile.open('archive.7z', mode='rb') as vol:
    buffer = bytearray(1024)
    vol.seek(5000)
    bytes_read = vol.readinto(buffer)
    print(f"Read {bytes_read} bytes into buffer")
```

### Response
#### Success Response
- **read() / readall()**: Returns `bytes` containing the data read.
- **readinto()**: Returns `int` representing the number of bytes read.

#### Response Example
```python
# Example return values
# data = b'...' (bytes)
# bytes_read = 1024 (int)
```
```

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

### write() - Writing Data

Source: https://context7.com/miurahr/multivolume/llms.txt

Methods for writing data to multi-volume files, automatically creating new volume files as needed.

```APIDOC
## write() - Writing Data

### Description
Write operations automatically create new volume files when the current volume reaches its size limit. Data is split transparently across volumes.

### Method
`write(data)`

### Parameters
#### write(data)
- **data** (bytes) - Required - The bytes to write to the file.

### Request Example
```python
import multivolumefile

# Write data split into 10KB volumes
data = b'A' * 50000  # 50KB of data

with multivolumefile.open('output.7z', mode='wb', volume=10240) as vol:
    vol.write(data)
    vol.flush() # Ensure all data is written
    print(f"Data written, position: {vol.tell()}")

# Write with default 10MB volume size
with multivolumefile.open('large_archive.7z', mode='wb') as vol:
    for i in range(100):
        vol.write(b'chunk_data_' * 1000)
```

### Response
#### Success Response
- **write()**: Returns the number of bytes written.

#### Response Example
```python
# Example return value
# bytes_written = 50000 (int)
```
```

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

### seek() / tell() - Position Navigation

Source: https://context7.com/miurahr/multivolume/llms.txt

Standard file navigation methods for seeking to specific positions and retrieving the current position within the virtual multi-volume file.

```APIDOC
## seek() / tell() - Position Navigation

### Description
Navigate within the virtual file using standard seek operations. Seeking works across volume boundaries with support for `SEEK_SET`, `SEEK_CUR`, and `SEEK_END` modes.

### Methods
- **seek(offset, whence=io.SEEK_SET)**: Changes the file's current position. `whence` defaults to `io.SEEK_SET` (absolute positioning from the beginning).
- **tell()**: Returns the current file position as an integer.

### Parameters
#### seek(offset, whence)
- **offset** (int) - Required - The number of bytes to move the position.
- **whence** (int) - Optional - The reference point for the offset. Can be `io.SEEK_SET` (0), `io.SEEK_CUR` (1), or `io.SEEK_END` (2). Defaults to `io.SEEK_SET`.

### Request Example
```python
import multivolumefile
import io

with multivolumefile.open('archive.7z', mode='rb') as vol:
    # Seek from beginning (SEEK_SET)
    pos = vol.seek(15000, io.SEEK_SET)
    print(f"Position: {pos}")

    # Seek relative to current position (SEEK_CUR)
    vol.seek(40000)
    pos = vol.seek(-1001, io.SEEK_CUR)
    print(f"Position after relative seek: {pos}")

    # Seek from end (SEEK_END)
    pos = vol.seek(-2337, io.SEEK_END)
    print(f"Position from end: {pos}")

    # Get current position
    current = vol.tell()
    print(f"Current position: {current}")
```

### Response
#### Success Response
- **seek()**: Returns the new absolute position in the file.
- **tell()**: Returns the current absolute position in the file.

#### Response Example
```python
# Example return values
# pos = 15000 (int)
# current = 38999 (int)
```
```

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

### Capability Checks

Source: https://context7.com/miurahr/multivolume/llms.txt

Methods to verify the capabilities of the file object based on the mode it was opened with.

```APIDOC
## readable() / writable() / seekable()

### Description
Check the capabilities of the current file object based on the mode it was opened with.

### Response
- **readable** (bool) - Returns True if the file is readable.
- **writable** (bool) - Returns True if the file is writable.
- **seekable** (bool) - Returns True if the file supports seeking.
```

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

### Open and Read Multi-Volume Files

Source: https://context7.com/miurahr/multivolume/llms.txt

Use the open() function to read split volume files. It automatically detects numbered volume extensions. Ensure files are opened in binary mode ('rb').

```python
import multivolumefile

# Reading multi-volume files (archive.7z.001, archive.7z.002, etc.)
with multivolumefile.open('archive.7z', mode='rb') as vol:
    # Read first 1024 bytes
    data = vol.read(1024)
    print(f"Read {len(data)} bytes")

    # Seek to specific position and read
    vol.seek(5000)
    chunk = vol.read(100)
    print(f"Position after read: {vol.tell()}")
```

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

### Write to a multi-volume file

Source: https://github.com/miurahr/multivolume/blob/master/README.rst

Open a multi-volume file in binary write mode and write data. The file will be created with a 4-digit extension (e.g., archive.7z.001). Supports seeking.

```python
data = b'abcdefg'
with multivolumefile.open('archive.7z', 'wb') as vol:
    size = vol.write(data)
    vol.seek(0)
```

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

### Read from a multi-volume file

Source: https://github.com/miurahr/multivolume/blob/master/README.rst

Open a multi-volume file in binary read mode and read data. Supports seeking within the file.

```python
with multivolumefile.open('archive.7z', 'rb') as vol:
    data = vol.read(100)
    vol.seek(500)
```

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

### Exclusive Write Mode ('xb') - Prevent Overwriting

Source: https://context7.com/miurahr/multivolume/llms.txt

Creates new multi-volume files using exclusive write mode. Raises `FileExistsError` if any of the volume files already exist, preventing accidental overwrites.

```python
import multivolumefile

# Create new volumes (fails if they exist)
try:
    with multivolumefile.open('new_archive.7z', mode='xb', volume=10240) as vol:
        vol.write(b'exclusive_data' * 1000)
        print("Successfully created new archive")
except FileExistsError:
    print("Archive already exists!")
```

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

### Check File Object Capabilities (readable, writable, seekable)

Source: https://context7.com/miurahr/multivolume/llms.txt

Determines the capabilities of a multi-volume file object based on the mode it was opened with. Use `readable()`, `writable()`, and `seekable()` methods.

```python
import multivolumefile

# Read mode capabilities
with multivolumefile.open('archive.7z', mode='rb') as vol:
    print(f"Readable: {vol.readable()}")    # True
    print(f"Writable: {vol.writable()}")    # False
    print(f"Seekable: {vol.seekable()}")    # True
    print(f"Is TTY: {vol.isatty()}")        # False

# Write mode capabilities
with multivolumefile.open('output.7z', mode='wb', volume=10240) as vol:
    print(f"Readable: {vol.readable()}")    # False
    print(f"Writable: {vol.writable()}")    # True
    print(f"Seekable: {vol.seekable()}")    # True

# Append mode capabilities
with multivolumefile.open('output.7z', mode='ab', volume=10240) as vol:
    print(f"Seekable: {vol.seekable()}")    # False (append mode)
```

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

### stat() - File Statistics

Source: https://context7.com/miurahr/multivolume/llms.txt

Retrieves file statistics for the combined multi-volume file, returning a stat_result object with aggregated metadata.

```APIDOC
## stat()

### Description
Get file statistics for the combined multi-volume file. Returns a `stat_result` object with aggregated size and metadata from the first volume.

### Response
- **stat_result** (object) - Contains st_size, st_mode, st_mtime, st_atime, st_dev, st_uid, st_gid.
```

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

### Write Data to Multi-Volume Files

Source: https://context7.com/miurahr/multivolume/llms.txt

Write operations automatically create new volume files when the current volume's size limit is reached. Data is transparently split across these volumes. Ensure files are opened in binary mode ('wb').

```python
import multivolumefile

# Write data split into 10KB volumes
data = b'A' * 50000  # 50KB of data

with multivolumefile.open('output.7z', mode='wb', volume=10240) as vol:
    vol.write(data)
    vol.flush()
    print(f"Data written, position: {vol.tell()}")
# Creates: output.7z.0001 (10KB), output.7z.0002 (10KB),
#          output.7z.0003 (10KB), output.7z.0004 (10KB), output.7z.0005 (10KB)

# Write with default 10MB volume size
with multivolumefile.open('large_archive.7z', mode='wb') as vol:
    for i in range(100):
        vol.write(b'chunk_data_' * 1000)
```

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

### Append Data to Existing Volumes in Append Mode ('ab')

Source: https://context7.com/miurahr/multivolume/llms.txt

Appends data to an existing multi-volume file. New volumes are created as needed. Note that append mode is not seekable.

```python
import multivolumefile

# First, create initial volume with partial data
with open('archive.7z.0001', 'wb') as f:
    f.write(b'initial_data' * 100)

# Append more data, creating new volumes as needed
with multivolumefile.open('archive.7z', mode='ab', volume=10240) as vol:
    # Note: append mode is not seekable
    print(f"Seekable: {vol.seekable()}")  # False

    # Append additional data
    vol.write(b'appended_data' * 5000)
    vol.flush()
# New volume files created as needed
```

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

### Truncate Multi-Volume File with truncate()

Source: https://context7.com/miurahr/multivolume/llms.txt

Truncates a multi-volume file to a specified size, removing any excess volume files. Ensure the file is opened in binary write mode. The function returns the new size of the file.

```python
import multivolumefile

# Create test data across multiple volumes
with multivolumefile.open('data.7z', mode='wb', volume=10240) as vol:
    vol.write(b'x' * 52337)  # Creates 6 volume files

# Truncate to 15000 bytes
with multivolumefile.open('data.7z', mode='wb', volume=10240) as vol:
    # Read existing data (in practice you'd write first)
    vol.write(b'x' * 52337)
    vol.seek(0)
    result = vol.truncate(15000)
    print(f"Truncated to: {result} bytes")
# Result: data.7z.0001 (10240 bytes), data.7z.0002 (4760 bytes)
# data.7z.0003+ are deleted
```

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

### stat_result Class for File Statistics

Source: https://context7.com/miurahr/multivolume/llms.txt

The `stat_result` class provides an interface similar to `os.stat_result` for accessing combined file statistics across all volumes. It can be constructed manually or obtained via `MultiVolume.stat()`.

```python
from multivolumefile import stat_result
import os

# Typically obtained via MultiVolume.stat(), but can be constructed manually
file_stat = os.stat('somefile')
custom_stat = stat_result(file_stat, total_size=100000)

# Available properties
print(f"st_size: {custom_stat.st_size}")        # Combined size
print(f"st_mode: {custom_stat.st_mode}")        # File mode
print(f"st_ino: {custom_stat.st_ino}")          # Always 0 for multi-volume
print(f"st_dev: {custom_stat.st_dev}")          # Device ID
print(f"st_nlink: {custom_stat.st_nlink}")      # Number of links
print(f"st_uid: {custom_stat.st_uid}")          # Owner UID
print(f"st_gid: {custom_stat.st_gid}")          # Owner GID
print(f"st_atime: {custom_stat.st_atime}")      # Access time
print(f"st_mtime: {custom_stat.st_mtime}")      # Modification time
print(f"st_ctime: {custom_stat.st_ctime}")      # Change time
print(f"st_atime_ns: {custom_stat.st_atime_ns}")  # Access time (nanoseconds)
print(f"st_mtime_ns: {custom_stat.st_mtime_ns}")  # Modification time (nanoseconds)
print(f"st_ctime_ns: {custom_stat.st_ctime_ns}")  # Change time (nanoseconds)
```

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

### truncate() - Truncate File

Source: https://context7.com/miurahr/multivolume/llms.txt

Truncates the multi-volume file to a specified size, automatically removing unnecessary volume files.

```APIDOC
## truncate(size)

### Description
Truncate the multi-volume file to the specified size. Removes volume files that are no longer needed.

### Parameters
#### Request Body
- **size** (int) - Required - The target size in bytes.
```

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