sequencekit 0.1.1
Lightweight utility functions for working with strings, lists, and tuples.
Requires Python: >=3.7

# sequencekit

A lightweight, deterministic utility library for working with strings,
lists, and tuples.

`sequencekit` provides clean and efficient helpers for common sequence
operations such as frequency analysis, duplicate detection, and
order-preserving transformations. It eliminates repetitive boilerplate
while maintaining predictable and explicit behavior.

------------------------------------------------------------------------

## What is this project?

`sequencekit` is a focused utility toolkit built to simplify everyday
sequence manipulation tasks in Python.

While Python offers powerful built-ins, operations like:

-   Extracting elements that appear only once
-   Finding duplicates
-   Removing duplicates while preserving order
-   Determining the most or least frequent element

often require verbose or repetitive patterns.

This library provides:

-   Deterministic results
-   O(n) implementations
-   Explicit error handling
-   Configurable output formats
-   Clean, test-driven design

------------------------------------------------------------------------

## Features

-   Frequency counting (`frequency`)
-   Duplicate detection (`contains_duplicates`)
-   Extract elements appearing exactly once (`uniqueonly`)
-   Extract elements appearing more than once (`duplicates`)
-   Remove duplicates while preserving order (`remove_duplicates`)
-   Find most frequent element (`most_frequent`)
-   Find least frequent element (`least_frequent`)
-   Configurable output format (`list`, `tuple`, `str`)
-   Comprehensive test coverage
-   No third-party dependencies

------------------------------------------------------------------------

## Installation

### From PyPI

    pip install sequencekit

PyPI page: https://pypi.org/project/sequencekit/

------------------------------------------------------------------------

### Development Installation

    git clone https://github.com/IHac-er/sequencekit.git
    cd sequencekit
    pip install -e .

------------------------------------------------------------------------

## Usage

```python
from sequencekit import (
    frequency,
    contains_duplicates,
    uniqueonly,
    duplicates,
    most_frequent,
    least_frequent,
    remove_duplicates,
)

# ---------------------------------------------------
# Frequency Analysis
# ---------------------------------------------------

frequency("banana")
# {'b': 1, 'a': 3, 'n': 2}

frequency(["a", "b", "c", "a"])
# {'a': 2, 'b': 1, 'c': 1}

frequency((1, 2, 2, 3))
# {1: 1, 2: 2, 3: 1}


# ---------------------------------------------------
# Duplicate Detection
# ---------------------------------------------------

contains_duplicates("banana")
# True

contains_duplicates("abc")
# False

contains_duplicates([1, 2, 3, 4])
# False


# ---------------------------------------------------
# Elements Appearing Exactly Once
# ---------------------------------------------------

uniqueonly("banana")
# ['b']

uniqueonly("banana", out="tuple")
# ('b',)

uniqueonly("banana", out="str")
# 'b'


# ---------------------------------------------------
# Elements Appearing More Than Once
# ---------------------------------------------------

duplicates("banana")
# ['a', 'n']

duplicates([1, 2, 2, 3, 3])
# [2, 3]


# ---------------------------------------------------
# Remove Duplicates (Preserve Order)
# ---------------------------------------------------

remove_duplicates("banana")
# ['b', 'a', 'n']

remove_duplicates("banana", out="str")
# 'ban'

remove_duplicates((1, 2, 1, 3))
# [1, 2, 3]


# ---------------------------------------------------
# Most / Least Frequent
# ---------------------------------------------------

most_frequent("banana")
# 'a'
most_frequent([1, 2, 3, 1, 1, 4])
# 1

least_frequent("banana")
# 'b'
least_frequent([1, 2, 3, 1, 1, 4, 4, 1, 4, 3])
# 2

# Tie-breaking is deterministic (first occurrence wins)
most_frequent("aabb")
# 'a'

least_frequent("aabbcc")
# 'a' 
```
------------------------------------------------------------------------

## Output Format Control

Functions returning sequences support:

-   "list" (default)
-   "tuple"
-   "str"

Example:

    uniqueonly("banana", out="tuple")
    # ('b',)

    remove_duplicates("banana", out="str")
    # 'ban'

Invalid output types raise ValueError.

------------------------------------------------------------------------

## Running Tests

    pytest

All functionality and edge cases are covered by tests.

------------------------------------------------------------------------

## Project Structure

    sequencekit/
    ├── sequencekit/
    │   ├── __init__.py
    │   ├── core.py
    │   ├── _internals.py
    ├── tests/
    │   └── test_core.py
    ├── pyproject.toml
    └── README.md

------------------------------------------------------------------------

## License

Copyright 2026 THARUN R

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

------------------------------------------------------------------------

## Contributions

Contributions are welcome.

1.  Fork the repository
2.  Create a feature branch
3.  Write tests for new functionality
4.  Ensure all tests pass
5.  Submit a pull request

Bug reports and suggestions are appreciated.

------------------------------------------------------------------------

## Version

Current version: 0.1.1

------------------------------------------------------------------------

## Author

Tharun R GitHub: https://github.com/IHac-er