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)
• Circular rotation (rotate)
• 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

from sequencekit import (
    frequency,
    contains_duplicates,
    uniqueonly,
    duplicates,
    most_frequent,
    least_frequent,
    remove_duplicates,
    rotate,
)

# ---------------------------------------------------
# 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' 

# ---------------------------------------------------
# Circular Rotate
# ---------------------------------------------------

rotate("abcd", 1)
# ['b', 'c', 'd', 'a']

rotate("abcd", 1, direction="right")
# ['d', 'a', 'b', 'c']

---

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.2.0

---

Author

Tharun R GitHub: https://github.com/IHac-er