hashlist 0.1.0__tar.gz

hashlist-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

hashlist-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

hashlist-0.1.0/CMakeLists.txt

@@ -0,0 +1,11 @@
+cmake_minimum_required(VERSION 3.15)
+project(hashlist LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(pybind11 CONFIG REQUIRED)
+
+pybind11_add_module(hashlist_backend src/main.cpp)
+
+install(TARGETS hashlist_backend DESTINATION hashlist)

hashlist-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.1
+Name: hashlist
+Version: 0.1.0
+Summary: A high-performance hybrid list with O(1) hashing speed for Python.
+Author-Email: Fort66 <mamonov.1966@yandex.ru>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+*Read this in other languages: [Русский](README_RU.md).*
+# hashlist
+
+A high-performance, drop-in replacement for the standard Python `list` with **O(1) search and index speed** powered by a native C++17 backend via `pybind11`.
+
+## 🚀 The Problem & Our Solution
+
+In Python, checking if an item exists in a standard `list` (`item in my_list`) or finding its position (`my_list.index(item)`) takes **O(N) linear time**. As your dataset grows to millions of elements, these operations become a massive bottleneck for the CPU.
+
+`hashlist` solves this by introducing a highly optimized hybrid data structure. It combines a fast native C++ `std::vector` (preserving original insertion order, indices, and slices) with an advanced C++ `std::unordered_map<ssize_t, std::vector<size_t>>` lookup bucket map on the machine-instruction level.
+
+The result? Lookups, counter extractions, and index resolutions run in **O(1) constant time**, making it over **6,100x faster** than a standard Python list on heavy heterogeneous workloads.
+
+## ✨ Features
+
+- **⚡ Blazing Fast Lookups:** Constant time O(1) searches regardless of the list size.
+- **🚀 Ultra-Fast Index Resolution:** Unlike standard lists, finding the position of an element takes constant O(1) time due to low-level continuous index bucket tracking.
+- **🧠 100% Type Agnostic & Safe:** Safely handles standard hashable types (ints, strings) as well as mutable unhashable structures (nested `list`, `dict`, `set`) through a deterministic C++ recursive freeze algorithm.
+- **📦 Drop-in Replacement:** Fully implements the CPython `MutableSequence` protocol. Supports extended slices (`hl[0:5:2]`), negative indexing, mathematical operators (`+`, `*`, `+=`, `*=`), and global functions like `sorted()` and `reversed()`.
+- **🪶 Memory Optimized:** Built using `__slots__` at the wrapper level. An empty `hashlist` takes only **40 bytes** of memory due to lazy structures initialization.
+
+## 📊 Performance Benchmark
+
+Searching for a nested mutable dictionary at the very end of a **5,000,000** element heterogeneous collection:
+
+| Container Type | Search Time (Seconds) | Algorithmic Complexity | Performance Boost |
+| :--- | :--- | :--- | :--- |
+| Standard Python `list` | ~0.14096335 s | O(N) (Linear scan) | Baseline |
+| **`hashlist` (C++ Backend)** | **0.00002302 s** | **O(1) (Constant map)** | **6,123x Faster** |
+
+*Benchmark executed under Python 3.13.15 on CachyOS (Arch Linux, GCC 16.2.1).*
+
+## 🛠️ Complete Methods Specification
+
+`hashlist` fully supports all 12 canonical Python list mutation and lookup methods with unique C++ architectural optimizations:
+
+| Method | Description | Complexity | C++ Advantage |
+| :--- | :--- | :--- | :--- |
+| `hl.append(x)` | Appends element `x` to the end. Supports nested structures. | **O(1)** amortized | Native C++ memory allocation efficiency |
+| `hl.extend(iterable)` | Appends all elements from the iterable to the end. | **O(M)** | Fast sequential batch insertion |
+| `hl.insert(i, x)` | Inserts element `x` at position `i` shifting vectors. | O(N-i) native shift | Direct block memory shift on native CPU instructions level |
+| `hl.remove(x)` | Removes the first occurrence of value `x`. | **O(1) lookup check** + O(N) shift | **Instant failure** if item is missing (completely avoids linear vector scans) |
+| `hl.clear()` | Removes all elements, completely resetting container. | **O(1)** | Instant bucket and vector memory deallocation |
+| `hl.index(x)` | Returns the integer index of the first occurrence of `x`. | **🚀 O(1) constant** | **Instant index resolution** directly from the C++ bucket map without linear scans |
+| `hl.pop(i=-1)` | Removes and returns the element at index `i`. | **🔥 O(1) for end pop** / O(N-i) shift | Activated **Fast-Path optimization** during end pop operations |
+| `hl.count(x)` | Returns the number of times `x` appears in the list. | **🚀 O(1) constant** | Blazing fast value counter extracted directly from hash-map |
+| `hl.sort()` | Sorts the items on place. Supports `key` and `reverse`. | \(O(N \log N)\) | Fast Timsort pass directly over continuous native storage |
+| `hl.reverse()` | Reverses the elements of the list on place. | **O(N)** | Highly optimized `std::reverse` pointer swapping |
+| `hl.copy()` | Returns a shallow copy of the container. | **O(N)** | Fast iteration and element mirroring |
+
+## 💻 Quick Start
+
+```python
+from hashlist import hl, hashlist
+
+# 1. Quick creation using the factory function
+my_list = hl(10, 20, 30, "apple")
+
+# 2. Add complex nested unhashable structures safely
+my_list.append({"name": "Ivan", "id": 66})
+
+# 3. Instant O(1) searches and index resolution on C++ level
+print("apple" in my_list)  # True
+print(my_list.index("apple"))  # 3 (Instant O(1) extraction!)
+print({"id": 66, "name": "Ivan"} in my_list)  # True (Order independent!)
+
+# 4. Standard Python functions and slices work seamlessly
+for item in reversed(my_list):
+    print(item)
+
+sub_slice = my_list[1:4]
+print(20 in sub_slice)  # True
+```
+
+## 🏗️ Development & Testing
+
+The package uses `scikit-build-core` and `pybind11` for seamless native compilation inside `uv` environments.
+
+To run the complete automated test suite (including performance, memory, and stress testing):
+```bash
+uv run pytest -v -s
+```
+
+## 📄 License
+
+Distributed under the MIT License. Developed by Fort66 (mamonov.1966@yandex.ru).
+
+
+
+
+
+
+
+# hashlist
+
+Высокопроизводительная замена стандартного Python `list` с **O(1) скоростью поиска и разрешения индексов**, работающая на нативном C++17 бэкенде через `pybind11`.
+
+## 🚀 Проблема и наше решение
+
+В Python проверка наличия элемента в стандартном списке (`item in my_list`) или поиск его позиции (`my_list.index(item)`) занимает **O(N) линейное время**. По мере того как ваш набор данных растет до миллионов элементов, эти операции превращаются в критическое «узкое место» для процессора.
+
+`hashlist` решает эту проблему за счет внедрения оптимизированной гибридной структуры данных. Она сочетает в себе быстрый нативный C++ `std::vector` (сохраняющий исходный порядок вставки, индексы и срезы) с продвинутой хэш-картой `std::unordered_map<ssize_t, std::vector<size_t>>` на уровне машинных инструкций.
+
+Результат? Поиск, подсчет вхождений и извлечение индексов выполняются за **константное время O(1)**, что делает контейнер более чем в **6100 раз быстрее** стандартного Python-списка на тяжелых разнородных нагрузках.
+
+## ✨ Особенности
+
+- **⚡ Молниеносный поиск:** Константное время O(1) для оператора `in` независимо от размера списка.
+- **🚀 Моментальное разрешение индексов:** В отличие от стандартных списков, метод `.index()` находит позицию элемента за O(1) благодаря непрерывному низкоуровневому отслеживанию бакетов.
+- **🧠 100% всеядность и безопасность типов:** Надежно обрабатывает как стандартные хэшируемые типы (числа, строки), так и изменяемые нехэшируемые структуры (вложенные `list`, `dict`, `set`) с помощью детерминированного алгоритма рекурсивной «заморозки» на C++.
+- **📦 Полноценная drop-in замена:** Полностью реализует протокол `MutableSequence` в CPython. Из коробки поддерживаются сложные срезы (`hl[0:5:2]`), отрицательная индексация, математические операторы (`+`, `*`, `+=`, `*=`) и глобальные встроенные функции `sorted()` и `reversed()`.
+- **🪶 Оптимизация памяти:** Построена с использованием `__slots__` на уровне Python-оболочки. Пустой `hashlist` занимает всего **40 байт** памяти благодаря ленивой инициализации внутренних C++ структур.
+
+## 📊 Бенчмарк производительности
+
+Поиск сложного вложенного изменяемого словаря в самом конце перемешанной коллекции из **5 000 000** разнородных элементов:
+
+| Тип контейнера | Время поиска (Секунды) | Алгоритмическая сложность | Прирост скорости |
+| :--- | :--- | :--- | :--- |
+| Стандартный Python `list` | ~0.14096335 сек | O(N) (Линейный проход) | Базовый уровень |
+| **`hashlist` (C++ ядро)** | **0.00002302 сек** | **O(1) (Константная карта)** | **В 6123.5 раза быстрее** |
+
+*Тестирование проводилось под Python 3.13.15 на операционной системе CachyOS (Arch Linux, компилятор GCC 16.2.1).*
+
+## 🛠️ Спецификация поддерживаемых методов
+
+`hashlist` полностью поддерживает все 12 канонических методов мутации и поиска стандартного списка со специальными архитектурными оптимизациями C++:
+
+| Метод | Описание | Сложность | Преимущество C++ бэкенда |
+| :--- | :--- | :--- | :--- |
+| `hl.append(x)` | Добавляет элемент `x` в конец. Поддерживает вложенные структуры. | **O(1)** амортизировано | Эффективность нативного выделения памяти C++ |
+| `hl.extend(iterable)` | Добавляет в конец все элементы из переданной последовательности. | **O(M)** | Быстрая последовательная пакетная вставка (зависит только от размера принесенных данных) |
+| `hl.insert(i, x)` | Вставляет элемент `x` на позицию `i` со сдвигом вектора. | O(N-i) нативный сдвиг | Прямой сдвиг блока памяти на уровне машинных инструкций процессора |
+| `hl.remove(x)` | Удаляет первое вхождение значения `x`. | **O(1) проверка поиска** + O(N) сдвиг | **Мгновенный вылет с ошибкой** за O(1), если элемента нет (без линейного сканирования вектора) |
+| `hl.clear()` | Удаляет все элементы, полностью освобождая память. | **O(1)** | Моментальная очистка бакетов хэш-карты и деаллокация вектора |
+| `hl.index(x)` | Возвращает целочисленный индекс первого вхождения `x`. | **🚀 O(1) константа** | **Мгновенное разрешение индекса** напрямую из карты бакетов без линейных переборов |
+| `hl.pop(i=-1)` | Удаляет и возвращает элемент по индексу `i`. | **🔥 O(1) для извлечения с конца** / O(N-i) сдвиг | Активация оптимизации **Fast-Path** при дефолтном удалении последнего элемента |
+| `hl.count(x)` | Возвращает количество повторений элемента `x` в списке. | **🚀 O(1) константа** | Молниеносное извлечение размера вектора индексов напрямую из хэш-карты |
+| `hl.sort()` | Сортирует элементы на месте. Поддерживает `key` и `reverse`. | \(O(N \log N)\) | Быстрый проход алгоритма Timsort напрямую по непрерывному C-массиву |
+| `hl.reverse()` | Разворачивает элементы списка на месте. | **O(N)** | Высокооптимизированная перестановка указателей через `std::reverse` |
+| `hl.copy()` | Создает поверхностную копию контейнера. | **O(N)** | Быстрая нативная итерация и зеркалирование элементов |
+
+## 💻 Быстрый старт
+
+```python
+from hashlist import hl, hashlist
+
+# 1. Быстрое создание через фабричную функцию
+my_list = hl(10, 20, 30, "яблоко")
+
+# 2. Безопасное добавление сложных нехэшируемых структур
+my_list.append({"имя": "Иван", "id": 66})
+
+# 3. Моментальный O(1) поиск и извлечение индексов на уровне C++
+print("яблоко" in my_list)  # True
+print(my_list.index("яблоко"))  # 3 (Мгновенно за O(1)!)
+print({"id": 66, "имя": "Иван"} in my_list)  # True (Независимо от порядка ключей!)
+
+# 4. Стандартные функции Python и срезы работают бесшовно
+for item in reversed(my_list):
+    print(item)
+
+sub_slice = my_list[1:4]
+print(20 in sub_slice)  # True
+```
+
+## 🏗️ Разработка и тестирование
+
+Для автоматической компиляции и сборки расширения внутри изолированных окружений `uv` используются `scikit-build-core` и `pybind11`.
+
+Чтобы запустить полный автоматизированный набор тестов (включая нагрузочное стресс-тестирование и бенчмарки скорости):
+```bash
+uv run pytest -v -s
+```
+
+## 📄 Лицензия
+
+Распространяется под лицензией MIT. Разработчик: Fort66 (mamonov.1966@yandex.ru).

hashlist-0.1.0/README.md

@@ -0,0 +1,178 @@
+*Read this in other languages: [Русский](README_RU.md).*
+# hashlist
+
+A high-performance, drop-in replacement for the standard Python `list` with **O(1) search and index speed** powered by a native C++17 backend via `pybind11`.
+
+## 🚀 The Problem & Our Solution
+
+In Python, checking if an item exists in a standard `list` (`item in my_list`) or finding its position (`my_list.index(item)`) takes **O(N) linear time**. As your dataset grows to millions of elements, these operations become a massive bottleneck for the CPU.
+
+`hashlist` solves this by introducing a highly optimized hybrid data structure. It combines a fast native C++ `std::vector` (preserving original insertion order, indices, and slices) with an advanced C++ `std::unordered_map<ssize_t, std::vector<size_t>>` lookup bucket map on the machine-instruction level.
+
+The result? Lookups, counter extractions, and index resolutions run in **O(1) constant time**, making it over **6,100x faster** than a standard Python list on heavy heterogeneous workloads.
+
+## ✨ Features
+
+- **⚡ Blazing Fast Lookups:** Constant time O(1) searches regardless of the list size.
+- **🚀 Ultra-Fast Index Resolution:** Unlike standard lists, finding the position of an element takes constant O(1) time due to low-level continuous index bucket tracking.
+- **🧠 100% Type Agnostic & Safe:** Safely handles standard hashable types (ints, strings) as well as mutable unhashable structures (nested `list`, `dict`, `set`) through a deterministic C++ recursive freeze algorithm.
+- **📦 Drop-in Replacement:** Fully implements the CPython `MutableSequence` protocol. Supports extended slices (`hl[0:5:2]`), negative indexing, mathematical operators (`+`, `*`, `+=`, `*=`), and global functions like `sorted()` and `reversed()`.
+- **🪶 Memory Optimized:** Built using `__slots__` at the wrapper level. An empty `hashlist` takes only **40 bytes** of memory due to lazy structures initialization.
+
+## 📊 Performance Benchmark
+
+Searching for a nested mutable dictionary at the very end of a **5,000,000** element heterogeneous collection:
+
+| Container Type | Search Time (Seconds) | Algorithmic Complexity | Performance Boost |
+| :--- | :--- | :--- | :--- |
+| Standard Python `list` | ~0.14096335 s | O(N) (Linear scan) | Baseline |
+| **`hashlist` (C++ Backend)** | **0.00002302 s** | **O(1) (Constant map)** | **6,123x Faster** |
+
+*Benchmark executed under Python 3.13.15 on CachyOS (Arch Linux, GCC 16.2.1).*
+
+## 🛠️ Complete Methods Specification
+
+`hashlist` fully supports all 12 canonical Python list mutation and lookup methods with unique C++ architectural optimizations:
+
+| Method | Description | Complexity | C++ Advantage |
+| :--- | :--- | :--- | :--- |
+| `hl.append(x)` | Appends element `x` to the end. Supports nested structures. | **O(1)** amortized | Native C++ memory allocation efficiency |
+| `hl.extend(iterable)` | Appends all elements from the iterable to the end. | **O(M)** | Fast sequential batch insertion |
+| `hl.insert(i, x)` | Inserts element `x` at position `i` shifting vectors. | O(N-i) native shift | Direct block memory shift on native CPU instructions level |
+| `hl.remove(x)` | Removes the first occurrence of value `x`. | **O(1) lookup check** + O(N) shift | **Instant failure** if item is missing (completely avoids linear vector scans) |
+| `hl.clear()` | Removes all elements, completely resetting container. | **O(1)** | Instant bucket and vector memory deallocation |
+| `hl.index(x)` | Returns the integer index of the first occurrence of `x`. | **🚀 O(1) constant** | **Instant index resolution** directly from the C++ bucket map without linear scans |
+| `hl.pop(i=-1)` | Removes and returns the element at index `i`. | **🔥 O(1) for end pop** / O(N-i) shift | Activated **Fast-Path optimization** during end pop operations |
+| `hl.count(x)` | Returns the number of times `x` appears in the list. | **🚀 O(1) constant** | Blazing fast value counter extracted directly from hash-map |
+| `hl.sort()` | Sorts the items on place. Supports `key` and `reverse`. | \(O(N \log N)\) | Fast Timsort pass directly over continuous native storage |
+| `hl.reverse()` | Reverses the elements of the list on place. | **O(N)** | Highly optimized `std::reverse` pointer swapping |
+| `hl.copy()` | Returns a shallow copy of the container. | **O(N)** | Fast iteration and element mirroring |
+
+## 💻 Quick Start
+
+```python
+from hashlist import hl, hashlist
+
+# 1. Quick creation using the factory function
+my_list = hl(10, 20, 30, "apple")
+
+# 2. Add complex nested unhashable structures safely
+my_list.append({"name": "Ivan", "id": 66})
+
+# 3. Instant O(1) searches and index resolution on C++ level
+print("apple" in my_list)  # True
+print(my_list.index("apple"))  # 3 (Instant O(1) extraction!)
+print({"id": 66, "name": "Ivan"} in my_list)  # True (Order independent!)
+
+# 4. Standard Python functions and slices work seamlessly
+for item in reversed(my_list):
+    print(item)
+
+sub_slice = my_list[1:4]
+print(20 in sub_slice)  # True
+```
+
+## 🏗️ Development & Testing
+
+The package uses `scikit-build-core` and `pybind11` for seamless native compilation inside `uv` environments.
+
+To run the complete automated test suite (including performance, memory, and stress testing):
+```bash
+uv run pytest -v -s
+```
+
+## 📄 License
+
+Distributed under the MIT License. Developed by Fort66 (mamonov.1966@yandex.ru).
+
+
+
+
+
+
+
+# hashlist
+
+Высокопроизводительная замена стандартного Python `list` с **O(1) скоростью поиска и разрешения индексов**, работающая на нативном C++17 бэкенде через `pybind11`.
+
+## 🚀 Проблема и наше решение
+
+В Python проверка наличия элемента в стандартном списке (`item in my_list`) или поиск его позиции (`my_list.index(item)`) занимает **O(N) линейное время**. По мере того как ваш набор данных растет до миллионов элементов, эти операции превращаются в критическое «узкое место» для процессора.
+
+`hashlist` решает эту проблему за счет внедрения оптимизированной гибридной структуры данных. Она сочетает в себе быстрый нативный C++ `std::vector` (сохраняющий исходный порядок вставки, индексы и срезы) с продвинутой хэш-картой `std::unordered_map<ssize_t, std::vector<size_t>>` на уровне машинных инструкций.
+
+Результат? Поиск, подсчет вхождений и извлечение индексов выполняются за **константное время O(1)**, что делает контейнер более чем в **6100 раз быстрее** стандартного Python-списка на тяжелых разнородных нагрузках.
+
+## ✨ Особенности
+
+- **⚡ Молниеносный поиск:** Константное время O(1) для оператора `in` независимо от размера списка.
+- **🚀 Моментальное разрешение индексов:** В отличие от стандартных списков, метод `.index()` находит позицию элемента за O(1) благодаря непрерывному низкоуровневому отслеживанию бакетов.
+- **🧠 100% всеядность и безопасность типов:** Надежно обрабатывает как стандартные хэшируемые типы (числа, строки), так и изменяемые нехэшируемые структуры (вложенные `list`, `dict`, `set`) с помощью детерминированного алгоритма рекурсивной «заморозки» на C++.
+- **📦 Полноценная drop-in замена:** Полностью реализует протокол `MutableSequence` в CPython. Из коробки поддерживаются сложные срезы (`hl[0:5:2]`), отрицательная индексация, математические операторы (`+`, `*`, `+=`, `*=`) и глобальные встроенные функции `sorted()` и `reversed()`.
+- **🪶 Оптимизация памяти:** Построена с использованием `__slots__` на уровне Python-оболочки. Пустой `hashlist` занимает всего **40 байт** памяти благодаря ленивой инициализации внутренних C++ структур.
+
+## 📊 Бенчмарк производительности
+
+Поиск сложного вложенного изменяемого словаря в самом конце перемешанной коллекции из **5 000 000** разнородных элементов:
+
+| Тип контейнера | Время поиска (Секунды) | Алгоритмическая сложность | Прирост скорости |
+| :--- | :--- | :--- | :--- |
+| Стандартный Python `list` | ~0.14096335 сек | O(N) (Линейный проход) | Базовый уровень |
+| **`hashlist` (C++ ядро)** | **0.00002302 сек** | **O(1) (Константная карта)** | **В 6123.5 раза быстрее** |
+
+*Тестирование проводилось под Python 3.13.15 на операционной системе CachyOS (Arch Linux, компилятор GCC 16.2.1).*
+
+## 🛠️ Спецификация поддерживаемых методов
+
+`hashlist` полностью поддерживает все 12 канонических методов мутации и поиска стандартного списка со специальными архитектурными оптимизациями C++:
+
+| Метод | Описание | Сложность | Преимущество C++ бэкенда |
+| :--- | :--- | :--- | :--- |
+| `hl.append(x)` | Добавляет элемент `x` в конец. Поддерживает вложенные структуры. | **O(1)** амортизировано | Эффективность нативного выделения памяти C++ |
+| `hl.extend(iterable)` | Добавляет в конец все элементы из переданной последовательности. | **O(M)** | Быстрая последовательная пакетная вставка (зависит только от размера принесенных данных) |
+| `hl.insert(i, x)` | Вставляет элемент `x` на позицию `i` со сдвигом вектора. | O(N-i) нативный сдвиг | Прямой сдвиг блока памяти на уровне машинных инструкций процессора |
+| `hl.remove(x)` | Удаляет первое вхождение значения `x`. | **O(1) проверка поиска** + O(N) сдвиг | **Мгновенный вылет с ошибкой** за O(1), если элемента нет (без линейного сканирования вектора) |
+| `hl.clear()` | Удаляет все элементы, полностью освобождая память. | **O(1)** | Моментальная очистка бакетов хэш-карты и деаллокация вектора |
+| `hl.index(x)` | Возвращает целочисленный индекс первого вхождения `x`. | **🚀 O(1) константа** | **Мгновенное разрешение индекса** напрямую из карты бакетов без линейных переборов |
+| `hl.pop(i=-1)` | Удаляет и возвращает элемент по индексу `i`. | **🔥 O(1) для извлечения с конца** / O(N-i) сдвиг | Активация оптимизации **Fast-Path** при дефолтном удалении последнего элемента |
+| `hl.count(x)` | Возвращает количество повторений элемента `x` в списке. | **🚀 O(1) константа** | Молниеносное извлечение размера вектора индексов напрямую из хэш-карты |
+| `hl.sort()` | Сортирует элементы на месте. Поддерживает `key` и `reverse`. | \(O(N \log N)\) | Быстрый проход алгоритма Timsort напрямую по непрерывному C-массиву |
+| `hl.reverse()` | Разворачивает элементы списка на месте. | **O(N)** | Высокооптимизированная перестановка указателей через `std::reverse` |
+| `hl.copy()` | Создает поверхностную копию контейнера. | **O(N)** | Быстрая нативная итерация и зеркалирование элементов |
+
+## 💻 Быстрый старт
+
+```python
+from hashlist import hl, hashlist
+
+# 1. Быстрое создание через фабричную функцию
+my_list = hl(10, 20, 30, "яблоко")
+
+# 2. Безопасное добавление сложных нехэшируемых структур
+my_list.append({"имя": "Иван", "id": 66})
+
+# 3. Моментальный O(1) поиск и извлечение индексов на уровне C++
+print("яблоко" in my_list)  # True
+print(my_list.index("яблоко"))  # 3 (Мгновенно за O(1)!)
+print({"id": 66, "имя": "Иван"} in my_list)  # True (Независимо от порядка ключей!)
+
+# 4. Стандартные функции Python и срезы работают бесшовно
+for item in reversed(my_list):
+    print(item)
+
+sub_slice = my_list[1:4]
+print(20 in sub_slice)  # True
+```
+
+## 🏗️ Разработка и тестирование
+
+Для автоматической компиляции и сборки расширения внутри изолированных окружений `uv` используются `scikit-build-core` и `pybind11`.
+
+Чтобы запустить полный автоматизированный набор тестов (включая нагрузочное стресс-тестирование и бенчмарки скорости):
+```bash
+uv run pytest -v -s
+```
+
+## 📄 Лицензия
+
+Распространяется под лицензией MIT. Разработчик: Fort66 (mamonov.1966@yandex.ru).

hashlist-0.1.0/hashlist/__init__.py

@@ -0,0 +1,136 @@
+# ruff: noqa: I001
+from collections.abc import MutableSequence
+from .hashlist_backend import HashListCpp
+
+class hashlist(MutableSequence):
+    __slots__ = ('_backend',)
+
+    def __init__(self, iterable=None):
+        """Промышленный тип данных с высокопроизводительным ядром на C++"""
+        self._backend = HashListCpp()
+        if iterable is not None:
+            self.extend(iterable)
+
+    def append(self, item):
+        """Добавляет элемент x в конец списка a."""
+        self._backend.append(item)
+
+    def extend(self, iterable):
+        """Добавляет в конец a все элементы списка b."""
+        self._backend.extend(iterable)
+
+    def insert(self, index, item):
+        """Вставляет элемент x на позицию i."""
+        self._backend.insert(index, item)
+
+    def remove(self, item):
+        """Удаляет в a первый элемент, значение которого равно x."""
+        self._backend.remove(item)
+
+    def clear(self):
+        """Удаляет все элементы из списка a и делает его пустым."""
+        self._backend.clear()
+
+    def index(self, item, *args):
+        """Возвращает индекс элемента списка."""
+        if args:
+            items_list = [self[i] for i in range(len(self))]
+            return items_list.index(item, *args)
+        return self._backend.index_of(item)
+
+    def pop(self, index=-1):
+        """Удаляет элемент по индексу и возвращает его."""
+        return self._backend.pop(index)
+
+    def count(self, item):
+        """Считает, сколько раз элемент повторяется в списке за O(1)."""
+        return self._backend.count(item)
+
+    def sort(self, *args, **kwargs):
+        """Сортирует список на месте."""
+        self._backend.sort(*args, **kwargs)
+
+    def reverse(self):
+        """Разворачивает список на месте."""
+        self._backend.reverse()
+
+    def copy(self):
+        """Создаёт поверхностную копию списка."""
+        new_hl = hashlist()
+        for i in range(len(self)):
+            new_hl.append(self[i])
+        return new_hl
+
+    # --- Новые методы поддержки глобальных функций sorted() и reversed() ---
+    def __reversed__(self):
+        """Обеспечивает корректную работу глобальной функции reversed(hl)"""
+        # Возвращаем генератор, который идет с конца структуры к началу
+        for i in range(len(self) - 1, -1, -1):
+            yield self[i]
+
+    # --- Поддержка синтаксического контракта Python ---
+    def __len__(self):
+        return self._backend.__len__()
+
+    def __getitem__(self, index):
+        result = self._backend.getitem(index)
+        if isinstance(result, HashListCpp):
+            new_hl = hashlist()
+            new_hl._backend = result
+            return new_hl
+        return result
+
+    def __setitem__(self, index, value):
+        self._backend.setitem(index, value)
+
+    def __delitem__(self, index):
+        self._backend.delitem(index)
+
+    def __contains__(self, item):
+        return self._backend.__contains__(item)
+
+    def __iter__(self):
+        """Поддержка стандартного перебора для sorted()"""
+        for i in range(len(self)):
+            yield self[i]
+
+    def __add__(self, other):
+        if not hasattr(other, '__iter__'): return NotImplemented
+        result = self.copy()
+        result.extend(other)
+        return result
+
+    def __iadd__(self, other):
+        if not hasattr(other, '__iter__'): return NotImplemented
+        self.extend(other)
+        return self
+
+    def __mul__(self, value):
+        if not isinstance(value, int): return NotImplemented
+        result = hashlist()
+        for _ in range(value):
+            result.extend([self[i] for i in range(len(self))])
+        return result
+
+    def __imul__(self, value):
+        if not isinstance(value, int): return NotImplemented
+        old_items = [self[i] for i in range(len(self))]
+        for _ in range(value - 1):
+            self.extend(old_items)
+        return self
+
+    def __eq__(self, other):
+        if isinstance(other, hashlist):
+            if len(self) != len(other): return False
+            return [self[i] for i in range(len(self))] == [other[i] for i in range(len(other))]
+        if isinstance(other, list):
+            return [self[i] for i in range(len(self))] == other
+        return False
+
+    def __repr__(self):
+        items_repr = [self[i] for i in range(len(self))]
+        return f"hashlist({repr(items_repr)})"
+
+def hl(*args):
+    """Удобная фабрика для создания hashlist через запятую"""
+    return hashlist(args)

hashlist-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "hashlist"
+version = "0.1.0"
+description = "A high-performance hybrid list with O(1) hashing speed for Python."
+readme = "README.md"
+authors = [
+    { name = "Fort66", email = "mamonov.1966@yandex.ru" }
+]
+requires-python = ">=3.13"
+dependencies = []
+
+[build-system]
+requires = ["scikit-build-core==0.10.7", "pybind11==2.13.6"]
+build-backend = "scikit_build_core.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+]