sequencekit

A lightweight Python utility library for working with strings, lists, and tuples.
View on PyPI »  ·  Open an Issue »

---

Table of Contents

1. About The Project
2. Features
3. Built With
4. Getting Started
   • Prerequisites
   • Installation
5. Usage
6. Performance Notes
7. Project Structure
8. Testing
9. Contributing
10. License
11. Contact

---

About The Project

sequencekit is a focused utility library built to simplify everyday sequence manipulation in Python.

Python already provides powerful built-ins and standard-library tools. sequencekit focuses on turning common, repetitive sequence logic into a small and consistent API with predictable behavior, explicit validation, and configurable output formats.

It currently supports:

• Frequency analysis
• Duplicate detection and extraction
• Order-preserving deduplication
• Most/least frequent element lookup
• Circular sequence rotation
• Output conversion to list, tuple, or str

The project is intentionally small and focused on readability and usability rather than replacing specialized standard-library tools.

---

Features

• frequency() — count occurrences of each element
• contains_duplicates() — detect whether duplicates exist
• uniqueonly() — extract elements appearing exactly once
• duplicates() — extract elements appearing more than once
• remove_duplicates() — remove duplicates while preserving order
• most_frequent() — find the most frequent element
• least_frequent() — find the least frequent element
• rotate() — circular left/right rotation
• Consistent output control with list, tuple, and str
• Deterministic ordering and tie-breaking
• Explicit error handling
• No third-party runtime dependencies

---

Built With

• Python
• pytest for testing
• setuptools for package building
• PyPI for distribution

---

Getting Started

Prerequisites

• Python 3.7+
• pip

Check your Python version:

python --version

Installation

Install the latest release from PyPI:

pip install sequencekit

Or clone the repository for development:

git clone https://github.com/IHac-er/sequencekit.git
cd sequencekit
pip install -e .

---

Usage

Frequency Analysis

from sequencekit import frequency

frequency("banana")
# {'b': 1, 'a': 3, 'n': 2}

frequency([1, 2, 2, 3])
# {1: 1, 2: 2, 3: 1}

Duplicate Detection

from sequencekit import contains_duplicates

contains_duplicates("banana")
# True

contains_duplicates("abc")
# False

Unique Elements

from sequencekit import uniqueonly

uniqueonly("banana")
# ['b']

uniqueonly("banana", out="tuple")
# ('b',)

uniqueonly("banana", out="str")
# 'b'

Duplicate Elements

from sequencekit import duplicates

duplicates("banana")
# ['a', 'n']

duplicates([1, 2, 2, 3, 3])
# [2, 3]

Remove Duplicates

from sequencekit import remove_duplicates

remove_duplicates("banana")
# ['b', 'a', 'n']

remove_duplicates("banana", out="str")
# 'ban'

Most / Least Frequent

from sequencekit import most_frequent, least_frequent

most_frequent("aabb")
# 'a'

least_frequent("aabbcc")
# 'a'

When multiple elements have the same frequency, the first occurring element is returned.

Circular Rotation

from sequencekit import rotate

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

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

rotate("abcd", 1, direction="right", out="str")
# 'dabc'

rotate() accepts str, list, and tuple inputs and supports left/right rotation through the direction argument.

---

Output Format Control

Functions that return sequences support:

• list — default
• tuple
• str

Example:

uniqueonly("banana", out="tuple")
# ('b',)

remove_duplicates("banana", out="str")
# 'ban'

Invalid output types raise ValueError.

When out="str" is used, the result elements must be strings.

---

Performance Notes

sequencekit is primarily focused on readability, abstraction, consistency, and user-friendliness, rather than specialized performance optimization.

The core utilities are designed around linear-time operations under normal Python hashing assumptions. rotate() currently creates a new rotated sequence instead of performing an in-place mutation.

For performance-critical or repeated in-place rotations, Python's standard-library collections.deque.rotate() is a better-suited tool.

Performance-focused implementations may be explored in future versions while keeping the same public API and overall design.

---

Project Structure

sequencekit/
├── sequencekit/
│   ├── __init__.py
│   ├── core.py
│   └── _internals.py
├── tests/
│   └── test_core.py
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore

Module Responsibilities

• __init__.py — public API and package version
• core.py — public utility implementations
• _internals.py — shared private helpers for validation, frequency mapping, and output conversion
• test_core.py — automated tests
• pyproject.toml — package metadata and build configuration

---

Testing

Run the test suite with:

pytest

The current v0.2.0 release has a test suite covering normal behavior, output formats, empty inputs, invalid arguments, deterministic tie-breaking, and the rotate() feature.

Contributing

Contributions, bug reports, and feature suggestions are highly welcomed.

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/AmazingFeature

3. Add or update tests
4. Ensure the test suite passes

   pytest

5. Commit your changes

   git commit -m "feat: add AmazingFeature"

6. Push your branch

   git push origin feature/AmazingFeature

7. Open a Pull Request

---

License

Distributed under the MIT License. See LICENSE for more information.

---

Contact

Tharun R

• GitHub: IHac-er
• Email: rtharun2012@gmail.com

Project Link: https://github.com/IHac-er/sequencekit

PyPI: https://pypi.org/project/sequencekit/

---