| Name | kotcollections JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | https://github.com/Lalcs/kotcollections |
| Summary | kotcollections is a Python library that fully reproduces Kotlin's Collections interfaces. It brings Kotlin's rich collection operations to Python developers with List, Set, and Map implementations. |
| upload_time | 2025-07-25 13:48:02 |
| maintainer | None |
| docs_url | None |
| author | Vatis |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
# KotCollections - Kotlin Collections API for Python
[](https://pypi.org/project/kotcollections/)
[](https://pypi.org/project/kotcollections/)
[](https://pypi.org/project/kotcollections/)
[](https://github.com/lalcs/kotcollections/graphs/contributors)
[](https://pypistats.org/packages/kotcollections)
[](https://github.com/Lalcs/kotcollections/actions/workflows/unittest.yml)
kotcollections is a Python library that fully reproduces Kotlin's Collections interfaces. It brings Kotlin's rich
collection operations to Python developers with List, Set, and Map implementations.
## Installation
```bash
pip install kotcollections
```
## Features
- Complete implementation of Kotlin's List, Set, and Map interfaces using Python's snake_case naming convention
- Pythonic `_none` aliases for all `_null` methods (e.g., both `first_or_null()` and `first_or_none()` are available)
- Provides read-only and mutable variants:
- `KotList` and `KotMutableList` for list operations
- `KotSet` and `KotMutableSet` for set operations
- `KotMap` and `KotMutableMap` for map operations
- Full type safety with type hints
- Runtime type checking to ensure single element type (similar to Kotlin's generic type system)
- 100% test coverage
## Type Safety
KotList and KotSet implement runtime type checking similar to Kotlin's type system. Once a collection is created with
elements of a specific type, it can only contain elements of that same type.
### How It Works
- The first element added to a collection determines its element type
- All subsequent elements must be of the same type
- Collections can be nested (similar to `List<List<T>>` or `Set<Set<T>>` in Kotlin)
- Type checking occurs on initialization and all modification operations
### Examples
```python
# Valid: All elements are the same type
lst = KotList([1, 2, 3]) # KotList[int]
s = KotSet(['a', 'b', 'c']) # KotSet[str]
# Invalid: Mixed types will raise TypeError
try:
lst = KotList([1, 'a', 2]) # TypeError!
except TypeError as e:
print(e) # Cannot add element of type 'str' to KotList[int]
# Valid: Nested collections
nested_lists = KotList(
[
KotList([1, 2]),
KotList([3, 4])
]
) # KotList[KotList]
nested_sets = KotSet(
[
KotSet([1, 2]),
KotSet([3, 4])
]
) # KotSet[KotSet]
# Mutable collections also enforce type safety
mutable_list = KotMutableList([1, 2, 3])
mutable_list.add(4) # OK: same type
mutable_set = KotMutableSet(['a', 'b', 'c'])
mutable_set.add('d') # OK: same type
try:
mutable_list.add('string') # TypeError!
except TypeError as e:
print(e) # Cannot add element of type 'str' to KotList[int]
# Empty collections determine type on first element
empty_list = KotMutableList()
empty_list.add('first') # Now it's KotList[str]
empty_set = KotMutableSet()
empty_set.add(42) # Now it's KotSet[int]
```
### Comparison with Kotlin
This type safety implementation provides similar guarantees to Kotlin's generic type system:
| Kotlin | kotcollections (Python) |
|--------------------------|-------------------------------------------------------|
| `List<Int>` | `KotList([1, 2, 3])` |
| `List<String>` | `KotList(['a', 'b', 'c'])` |
| `List<List<Int>>` | `KotList([KotList([1, 2]), KotList([3, 4])])` |
| `Set<Double>` | `KotSet([1.0, 2.0, 3.0])` |
| `Map<String, Int>` | `KotMap({"one": 1, "two": 2})` |
| `Map<Int, List<String>>` | `KotMap({1: KotList(["a", "b"]), 2: KotList(["c"])})` |
The main difference is that Kotlin performs compile-time type checking, while kotcollections performs runtime type
checking.
## Pythonic Aliases
To provide a more Pythonic API, all methods ending with `_null` have corresponding `_none` aliases:
```python
# All these _null methods have _none aliases
lst = KotList([1, 2, None, 3, None])
# Access methods
print(lst.get_or_null(10)) # None
print(lst.get_or_none(10)) # None (same result)
print(lst.first_or_none()) # 1
print(lst.last_or_none()) # None
# Transformation methods
result = lst.map_not_none(lambda x: x * 2 if x else None) # [2, 4, 6]
# Filtering
non_empty = lst.filter_not_none() # KotList([1, 2, 3])
# Aggregation
print(lst.max_or_none()) # 3
print(lst.min_or_none()) # 1
```
Both naming conventions are fully supported and can be used interchangeably based on your preference.
## Quick Start
```python
from kotcollections import KotList, KotMutableList, KotSet, KotMutableSet, KotMap, KotMutableMap
# Lists - ordered, allows duplicates
numbers = KotList([1, 2, 3, 2, 1])
print(numbers.distinct().to_list()) # [1, 2, 3]
# Sets - unordered, no duplicates
unique_numbers = KotSet([1, 2, 3, 2, 1])
print(unique_numbers.to_list()) # [1, 2, 3] (order not guaranteed)
# Maps - key-value pairs
scores = KotMap({"Alice": 90, "Bob": 85, "Charlie": 95})
print(scores.get("Alice")) # 90
# Functional operations work on all
doubled_list = numbers.map(lambda x: x * 2)
doubled_set = unique_numbers.map(lambda x: x * 2)
high_scores = scores.filter(lambda k, v: v >= 90)
# Mutable variants allow modifications
mutable_list = KotMutableList([1, 2, 3])
mutable_list.add(4)
mutable_set = KotMutableSet([1, 2, 3])
mutable_set.add(4)
mutable_map = KotMutableMap({"a": 1})
mutable_map.put("b", 2)
```
## Basic Usage
```python
from kotcollections import KotList, KotMutableList, KotMap, KotMutableMap
# Create a read-only list
lst = KotList([1, 2, 3, 4, 5])
# Create a mutable list
mutable_lst = KotMutableList([1, 2, 3, 4, 5])
# Create a read-only map
m = KotMap({"a": 1, "b": 2, "c": 3})
# Create a mutable map
mutable_m = KotMutableMap({"x": 10, "y": 20})
```
## Kotlin to Python Naming Convention
All Kotlin methods are available with Python's snake_case naming convention. Additionally, all methods ending with
`_null` have Pythonic `_none` aliases:
| Kotlin | Python (Primary) | Python (Alias) |
|-------------------|---------------------|---------------------|
| `getOrNull()` | `get_or_null()` | `get_or_none()` |
| `firstOrNull()` | `first_or_null()` | `first_or_none()` |
| `mapIndexed()` | `map_indexed()` | - |
| `filterNotNull()` | `filter_not_null()` | `filter_not_none()` |
| `associateBy()` | `associate_by()` | - |
| `joinToString()` | `join_to_string()` | - |
Note: Both naming styles (`_null` and `_none`) can be used interchangeably based on your preference.
## API Reference
For detailed documentation of all available methods, please refer to the [API Reference](docs/API_REFERENCE.md).
## Performance Considerations
- `KotList` internally uses Python's standard list, so basic operation performance is equivalent to standard lists
- `KotSet` internally uses Python's standard set, providing O(1) average case for add, remove, and contains operations
- `KotMap` internally uses Python's standard dict, providing O(1) average case for get, put, and contains operations
- When using method chaining extensively, be aware that each method creates a new collection, which may impact memory
usage
- For large datasets, consider generator-based implementations
## License
MIT License
Raw data
{
"_id": null,
"home_page": "https://github.com/Lalcs/kotcollections",
"name": "kotcollections",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Vatis",
"author_email": "vatis@lalcs.com",
"download_url": "https://files.pythonhosted.org/packages/8f/57/23aa2916835b64641d6e6206a1a7e2aa24d8876a31f67ae4a380d3d9145a/kotcollections-0.1.4.tar.gz",
"platform": null,
"description": "# KotCollections - Kotlin Collections API for Python\n\n[](https://pypi.org/project/kotcollections/)\n[](https://pypi.org/project/kotcollections/)\n[](https://pypi.org/project/kotcollections/)\n[](https://github.com/lalcs/kotcollections/graphs/contributors)\n[](https://pypistats.org/packages/kotcollections)\n[](https://github.com/Lalcs/kotcollections/actions/workflows/unittest.yml)\n\nkotcollections is a Python library that fully reproduces Kotlin's Collections interfaces. It brings Kotlin's rich\ncollection operations to Python developers with List, Set, and Map implementations.\n\n## Installation\n\n```bash\npip install kotcollections\n```\n\n## Features\n\n- Complete implementation of Kotlin's List, Set, and Map interfaces using Python's snake_case naming convention\n- Pythonic `_none` aliases for all `_null` methods (e.g., both `first_or_null()` and `first_or_none()` are available)\n- Provides read-only and mutable variants:\n - `KotList` and `KotMutableList` for list operations\n - `KotSet` and `KotMutableSet` for set operations\n - `KotMap` and `KotMutableMap` for map operations\n- Full type safety with type hints\n- Runtime type checking to ensure single element type (similar to Kotlin's generic type system)\n- 100% test coverage\n\n## Type Safety\n\nKotList and KotSet implement runtime type checking similar to Kotlin's type system. Once a collection is created with\nelements of a specific type, it can only contain elements of that same type.\n\n### How It Works\n\n- The first element added to a collection determines its element type\n- All subsequent elements must be of the same type\n- Collections can be nested (similar to `List<List<T>>` or `Set<Set<T>>` in Kotlin)\n- Type checking occurs on initialization and all modification operations\n\n### Examples\n\n```python\n# Valid: All elements are the same type\nlst = KotList([1, 2, 3]) # KotList[int]\ns = KotSet(['a', 'b', 'c']) # KotSet[str]\n\n# Invalid: Mixed types will raise TypeError\ntry:\n lst = KotList([1, 'a', 2]) # TypeError!\nexcept TypeError as e:\n print(e) # Cannot add element of type 'str' to KotList[int]\n\n# Valid: Nested collections\nnested_lists = KotList(\n [\n KotList([1, 2]),\n KotList([3, 4])\n ]\n) # KotList[KotList]\n\nnested_sets = KotSet(\n [\n KotSet([1, 2]),\n KotSet([3, 4])\n ]\n) # KotSet[KotSet]\n\n# Mutable collections also enforce type safety\nmutable_list = KotMutableList([1, 2, 3])\nmutable_list.add(4) # OK: same type\n\nmutable_set = KotMutableSet(['a', 'b', 'c'])\nmutable_set.add('d') # OK: same type\n\ntry:\n mutable_list.add('string') # TypeError!\nexcept TypeError as e:\n print(e) # Cannot add element of type 'str' to KotList[int]\n\n# Empty collections determine type on first element\nempty_list = KotMutableList()\nempty_list.add('first') # Now it's KotList[str]\n\nempty_set = KotMutableSet()\nempty_set.add(42) # Now it's KotSet[int]\n```\n\n### Comparison with Kotlin\n\nThis type safety implementation provides similar guarantees to Kotlin's generic type system:\n\n| Kotlin | kotcollections (Python) |\n|--------------------------|-------------------------------------------------------|\n| `List<Int>` | `KotList([1, 2, 3])` |\n| `List<String>` | `KotList(['a', 'b', 'c'])` |\n| `List<List<Int>>` | `KotList([KotList([1, 2]), KotList([3, 4])])` |\n| `Set<Double>` | `KotSet([1.0, 2.0, 3.0])` |\n| `Map<String, Int>` | `KotMap({\"one\": 1, \"two\": 2})` |\n| `Map<Int, List<String>>` | `KotMap({1: KotList([\"a\", \"b\"]), 2: KotList([\"c\"])})` |\n\nThe main difference is that Kotlin performs compile-time type checking, while kotcollections performs runtime type\nchecking.\n\n## Pythonic Aliases\n\nTo provide a more Pythonic API, all methods ending with `_null` have corresponding `_none` aliases:\n\n```python\n# All these _null methods have _none aliases\nlst = KotList([1, 2, None, 3, None])\n\n# Access methods\nprint(lst.get_or_null(10)) # None\nprint(lst.get_or_none(10)) # None (same result)\nprint(lst.first_or_none()) # 1\nprint(lst.last_or_none()) # None\n\n# Transformation methods \nresult = lst.map_not_none(lambda x: x * 2 if x else None) # [2, 4, 6]\n\n# Filtering\nnon_empty = lst.filter_not_none() # KotList([1, 2, 3])\n\n# Aggregation\nprint(lst.max_or_none()) # 3\nprint(lst.min_or_none()) # 1\n```\n\nBoth naming conventions are fully supported and can be used interchangeably based on your preference.\n\n## Quick Start\n\n```python\nfrom kotcollections import KotList, KotMutableList, KotSet, KotMutableSet, KotMap, KotMutableMap\n\n# Lists - ordered, allows duplicates\nnumbers = KotList([1, 2, 3, 2, 1])\nprint(numbers.distinct().to_list()) # [1, 2, 3]\n\n# Sets - unordered, no duplicates\nunique_numbers = KotSet([1, 2, 3, 2, 1])\nprint(unique_numbers.to_list()) # [1, 2, 3] (order not guaranteed)\n\n# Maps - key-value pairs\nscores = KotMap({\"Alice\": 90, \"Bob\": 85, \"Charlie\": 95})\nprint(scores.get(\"Alice\")) # 90\n\n# Functional operations work on all\ndoubled_list = numbers.map(lambda x: x * 2)\ndoubled_set = unique_numbers.map(lambda x: x * 2)\nhigh_scores = scores.filter(lambda k, v: v >= 90)\n\n# Mutable variants allow modifications\nmutable_list = KotMutableList([1, 2, 3])\nmutable_list.add(4)\n\nmutable_set = KotMutableSet([1, 2, 3])\nmutable_set.add(4)\n\nmutable_map = KotMutableMap({\"a\": 1})\nmutable_map.put(\"b\", 2)\n```\n\n## Basic Usage\n\n```python\nfrom kotcollections import KotList, KotMutableList, KotMap, KotMutableMap\n\n# Create a read-only list\nlst = KotList([1, 2, 3, 4, 5])\n\n# Create a mutable list\nmutable_lst = KotMutableList([1, 2, 3, 4, 5])\n\n# Create a read-only map\nm = KotMap({\"a\": 1, \"b\": 2, \"c\": 3})\n\n# Create a mutable map\nmutable_m = KotMutableMap({\"x\": 10, \"y\": 20})\n```\n\n## Kotlin to Python Naming Convention\n\nAll Kotlin methods are available with Python's snake_case naming convention. Additionally, all methods ending with\n`_null` have Pythonic `_none` aliases:\n\n| Kotlin | Python (Primary) | Python (Alias) |\n|-------------------|---------------------|---------------------|\n| `getOrNull()` | `get_or_null()` | `get_or_none()` |\n| `firstOrNull()` | `first_or_null()` | `first_or_none()` |\n| `mapIndexed()` | `map_indexed()` | - |\n| `filterNotNull()` | `filter_not_null()` | `filter_not_none()` |\n| `associateBy()` | `associate_by()` | - |\n| `joinToString()` | `join_to_string()` | - |\n\nNote: Both naming styles (`_null` and `_none`) can be used interchangeably based on your preference.\n\n## API Reference\n\nFor detailed documentation of all available methods, please refer to the [API Reference](docs/API_REFERENCE.md).\n\n## Performance Considerations\n\n- `KotList` internally uses Python's standard list, so basic operation performance is equivalent to standard lists\n- `KotSet` internally uses Python's standard set, providing O(1) average case for add, remove, and contains operations\n- `KotMap` internally uses Python's standard dict, providing O(1) average case for get, put, and contains operations\n- When using method chaining extensively, be aware that each method creates a new collection, which may impact memory\n usage\n- For large datasets, consider generator-based implementations\n\n## License\n\nMIT License",
"bugtrack_url": null,
"license": "MIT",
"summary": "kotcollections is a Python library that fully reproduces Kotlin's Collections interfaces. It brings Kotlin's rich collection operations to Python developers with List, Set, and Map implementations.",
"version": "0.1.4",
"project_urls": {
"Bug Tracker": "https://github.com/Lalcs/kotcollections/issues",
"Homepage": "https://github.com/Lalcs/kotcollections",
"Repository": "https://github.com/Lalcs/kotcollections"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6924d5178cf367d36cc6e4f2ce024d85eba5987ab2f7dbd2a9501d99bced718d",
"md5": "d70726e213a6f2d0c5ae1d8969ebf834",
"sha256": "42cf7c29341e3f109960ecb1559dd7b02cd2f6ab5214f7e09ce2e4aa1d217012"
},
"downloads": -1,
"filename": "kotcollections-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d70726e213a6f2d0c5ae1d8969ebf834",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 30670,
"upload_time": "2025-07-25T13:48:01",
"upload_time_iso_8601": "2025-07-25T13:48:01.273502Z",
"url": "https://files.pythonhosted.org/packages/69/24/d5178cf367d36cc6e4f2ce024d85eba5987ab2f7dbd2a9501d99bced718d/kotcollections-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f5723aa2916835b64641d6e6206a1a7e2aa24d8876a31f67ae4a380d3d9145a",
"md5": "cd795429fc185cc8e605a0e4f3f8139d",
"sha256": "15e8cb9d30736f71d2333c0463f70c9cc2c02583b5bde934ed701e645d60da76"
},
"downloads": -1,
"filename": "kotcollections-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "cd795429fc185cc8e605a0e4f3f8139d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 27050,
"upload_time": "2025-07-25T13:48:02",
"upload_time_iso_8601": "2025-07-25T13:48:02.519201Z",
"url": "https://files.pythonhosted.org/packages/8f/57/23aa2916835b64641d6e6206a1a7e2aa24d8876a31f67ae4a380d3d9145a/kotcollections-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 13:48:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Lalcs",
"github_project": "kotcollections",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "kotcollections"
}
