semvec/pypi-packages huggingface dataset:
pylineseek 0.1.2
A simple way to randomly access lines from a file without loading it in RAM. Supports compression and memory mapping.
License: MIT license

# PyLineSeek

[![PyPI version](https://img.shields.io/pypi/v/pylineseek.svg)](https://pypi.org/project/pylineseek/)  
[![Build Status](https://github.com/mireklzicar/pylineseek/actions/workflows/build-pipeline.yml/badge.svg)](https://github.com/mireklzicar/pylineseek/actions)  
[![Documentation Status](https://readthedocs.org/projects/pylineseek/badge/?version=latest)](https://pylineseek.readthedocs.io/en/latest/)  
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

PyLineSeek is a high-performance Python package designed for fast, random access to file lines without loading the entire file into memory. Whether you’re dealing with huge log files, datasets, or any large text files, PyLineSeek makes it simple and efficient by leveraging file compression, memory mapping, and concurrent read access.

## Features

- **Random File Access:** Retrieve any line or slice of lines quickly without reading the whole file.
- **Optional Compression:** Compress your files on the fly using *idzip* to save disk space.
- **Memory Mapping:** Utilize mmap for rapid access to large uncompressed files.
- **Concurrent Access:** Thread-safe retrieval with support for multiple workers.
- **Command-Line Interface:** Easily access functionality via a Typer-powered CLI.

## Installation

Install the stable release from PyPI:

```bash
pip install pylineseek
```

Or install the latest development version directly from GitHub:

```bash
pip install git+https://github.com/mireklzicar/pylineseek.git
```

## Usage

### Basic Usage Example

Here’s a simple example to demonstrate how to use PyLineSeek:

```python
from pylineseek import PyLineSeek

# Initialize PyLineSeek with a text file.
# The file 'example.txt' should have one record per line.
# Options: disable compression, do not treat the first line as a header,
# load the index in memory, and enable memory mapping.
pls = PyLineSeek("example.txt", compress=False, header=False, load_index=True, use_mmap=True)

# Retrieve the first line.
first_line = pls.get_line(0)
print("First line:", first_line.strip())

# Retrieve a slice of lines (e.g., lines 0 to 4).
lines = pls[0:5]
for line in lines:
    print(line.strip())

# Always close the file handles after use.
pls.close()
```

## Documentation

Full documentation—including API references, advanced usage, and examples—is available on Read the Docs:

[https://pylineseek.readthedocs.io/en/latest/](https://pylineseek.readthedocs.io/en/latest/)

## Acknowledgements

- Thanks to the developers of *python-idzip*, *tqdm*, *rich*, and *typer* for their amazing libraries.
- Inspired by the need for efficient, scalable file processing solutions.