diff --git a/docs/index.md b/docs/index.md
index 000ea34..8b48116 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,17 +1,112 @@
-# Welcome to MkDocs
+# Qwery List
+Qwery List is a small library introducing a new way to use higher order functions
+with lists, with **lazy evaluation**.
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+### Quick comparison
+#### The standard python way
+```python
+xs = ['1', '2', '3', '4']
+s = reduce(lambda acc, x: acc + x, filter(lambda x: x < 3, map(int, xs)), 0)
+```
+#### Qwery List way
+```python
+xs = QList(['1', '2', '3', '4'])
+s = xs.map(int).filter(lambda x: x < 3).fold(lambda acc, x: acc + x, 0)
+```
+Chaining methods makes code much more readable and follows the natural flow
+of reading left to right.
+As a bonus you get `len()` **method**, so no longer will you be forced to wrapp your
+lists in this type of code `len(xs)` and simply call `xs.len()` (I understand it is negligibly
+slower but look how much nicer it looks!)
-## Commands
+---
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
+# Installation
+This package is available on [PyPI](https://pypi.org/project/qwlist/)
+```
+pip install qwlist
+```
+
+---
+
+# Quick tutorial
+Let's say we want to read numbers from a file and choose only the even ones. No problem at all!
+```python
+from qwlist import QList
+
+with open('path/to/file.txt', 'r') as file:
+ qlist = QList(file.readlines())
+even = qlist.map(int).filter(lambda x: x % 2 == 0).collect()
+```
+Why is there this `collect` at the end? Because all operations on the QList are **lazy evaluated**,
+so in order to finally apply all the operations you need to express that.
+
+There is also an eagerly evaluated `EagerQList` in case all the actions performed on the list should
+be evaluated instantaneously. This object is in the `qwlist.eager` module, but it is also
+possible to transform `QList` into `EagerQList` simply by calling `eager()`
+```python
+>>> from qwlist import QList
+>>> QList(range(3)).eager().map(str)
+['0', '1', '2']
+```
+EagerQList has the same methods that QList has (`filter`, `map`, `foreach`, ...) but not lazy evaluated so
+there is no need to call `collect` at the end.
+
+---
+# Examples
+Making QList from an iterable
+```python
+>>> QList([1, 2, 3, 4])
+[1, 2, 3, 4]
+```
+Making QList from a generator
+```python
+>>> QList(range(3))
+[0, 1, 2]
+```
+Making a list of pairs: `int` and `str`
+```python
+>>> qlist = QList([1, 2, 3])
+>>> qlist.zip(qlist.map(str)).collect()
+[(1, '1'), (2, '2'), (3, '3')]
+```
+Summing only the even numbers
+```python
+>>> QList(range(10)).filter(lambda x: x % 2 == 0).fold(lambda acc, x: acc + x, 0)
+20
+```
+---
+
+## Side note
+This syntax resembles **Rust** syntax:
+
+
+
+Rust |
+Python |
+
+
+
+
+```rust
+let xs = vec![1, 2, 3, 4];
+let double_xs: Vec = xs.iter().map(|&x| x * 2).collect();
+println!("{double_xs:?}");
+// [2, 4, 6, 8]
+```
+
+ |
+
+
+```python
+xs = QList([1, 2, 3, 4])
+double_xs = xs.map(lambda x: x * 2).collect()
+print(double_xs)
+# [2, 4, 6, 8]
+```
+
+ |
+
+
-## Project layout
- mkdocs.yml # The configuration file.
- docs/
- index.md # The documentation homepage.
- ... # Other markdown pages, images and other files.
diff --git a/mkdocs.yml b/mkdocs.yml
index 2145ccf..afaee30 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -17,6 +17,10 @@ theme:
toggle:
icon: material/weather-night
name: Switch to dark mode
+ icon:
+ repo: fontawesome/brands/github
+ repo_url: https://github.com/WitoldFracek/qlist/tree/main
+
nav:
- Home: index.md
diff --git a/site/index.html b/site/index.html
index a4d631d..9e5e986 100644
--- a/site/index.html
+++ b/site/index.html
@@ -75,7 +75,7 @@
-
+
Skip to content
@@ -235,17 +235,30 @@
@@ -386,17 +399,30 @@
@@ -414,21 +440,100 @@
-
Welcome to MkDocs
-
For full documentation visit mkdocs.org.
-
Commands
-
-mkdocs new [dir-name]
- Create a new project.
-mkdocs serve
- Start the live-reloading docs server.
-mkdocs build
- Build the documentation site.
-mkdocs -h
- Print help message and exit.
-
-
Project layout
-
mkdocs.yml # The configuration file.
-docs/
- index.md # The documentation homepage.
- ... # Other markdown pages, images and other files.
+Qwery List
+Qwery List is a small library introducing a new way to use higher order functions
+with lists, with lazy evaluation.
+Quick comparison
+The standard python way
+xs = ['1', '2', '3', '4']
+s = reduce(lambda acc, x: acc + x, filter(lambda x: x < 3, map(int, xs)), 0)
+
+Qwery List way
+xs = QList(['1', '2', '3', '4'])
+s = xs.map(int).filter(lambda x: x < 3).fold(lambda acc, x: acc + x, 0)
+Chaining methods makes code much more readable and follows the natural flow
+of reading left to right.
+As a bonus you get len()
method, so no longer will you be forced to wrapp your
+lists in this type of code len(xs)
and simply call xs.len()
(I understand it is negligibly
+slower but look how much nicer it looks!)
+
+Installation
+This package is available on PyPI
+pip install qwlist
+
+
+Quick tutorial
+Let's say we want to read numbers from a file and choose only the even ones. No problem at all!
+from qwlist import QList
+
+with open('path/to/file.txt', 'r') as file:
+ qlist = QList(file.readlines())
+even = qlist.map(int).filter(lambda x: x % 2 == 0).collect()
+
+Why is there this collect
at the end? Because all operations on the QList are lazy evaluated,
+so in order to finally apply all the operations you need to express that.
+There is also an eagerly evaluated EagerQList
in case all the actions performed on the list should
+be evaluated instantaneously. This object is in the qwlist.eager
module, but it is also
+possible to transform QList
into EagerQList
simply by calling eager()
+>>> from qwlist import QList
+>>> QList(range(3)).eager().map(str)
+['0', '1', '2']
+
+EagerQList has the same methods that QList has (filter
, map
, foreach
, ...) but not lazy evaluated so
+there is no need to call collect
at the end.
+
+Examples
+Making QList from an iterable
+>>> QList([1, 2, 3, 4])
+[1, 2, 3, 4]
+
+Making QList from a generator
+>>> QList(range(3))
+[0, 1, 2]
+
+Making a list of pairs: int
and str
+>>> qlist = QList([1, 2, 3])
+>>> qlist.zip(qlist.map(str)).collect()
+[(1, '1'), (2, '2'), (3, '3')]
+
+Summing only the even numbers
+>>> QList(range(10)).filter(lambda x: x % 2 == 0).fold(lambda acc, x: acc + x, 0)
+20
+
+
+Side note
+This syntax resembles Rust syntax:
+
+
+Rust |
+Python |
+
+
+
+
+
+let xs = vec![1, 2, 3, 4];
+let double_xs: Vec<i32> = xs.iter().map(|&x| x * 2).collect();
+println!("{double_xs:?}");
+// [2, 4, 6, 8]
+
+
+
+ |
+
+
+
+xs = QList([1, 2, 3, 4])
+double_xs = xs.map(lambda x: x * 2).collect()
+print(double_xs)
+# [2, 4, 6, 8]
+
+
+
+ |
+
+
diff --git a/site/lazy/index.html b/site/lazy/index.html
index 1328c16..51e6753 100644
--- a/site/lazy/index.html
+++ b/site/lazy/index.html
@@ -609,6 +609,7 @@ Lazy
Object representing lazy evaluation of called methods.
Calling any method consumes the current Lazy
object. Using the same object
again may cause errors due to the draining of the generator.
+Found in qwlist.Lazy
@@ -858,13 +859,17 @@ Lazy
240
241
242
-243
class Lazy(Generic[T]):
+243
+244
+245
| class Lazy(Generic[T]):
"""
Object representing lazy evaluation of called methods.
Calling any method **consumes** the current `Lazy` object. **Using the same object
again may cause errors** due to the draining of the generator.
+ Found in `qwlist.Lazy`
+
Examples:
>>> qlist = QList([1, 2, 3, 4])
>>> filtered = qlist.filter(lambda x: x < 3)
@@ -1156,12 +1161,12 @@
Source code in src\qwlist\qwlist.py
- 23
-24
-25
+ | def __init__(self, gen: Iterable[T]):
+28
+29
+30
| def __init__(self, gen: Iterable[T]):
"""
Args:
gen (Iterable[T]): generator used to yield values on collecting items.
@@ -1193,15 +1198,15 @@
Source code in src\qwlist\qwlist.py
- 156
-157
-158
+ 158
159
160
161
162
163
-164 | def collect(self):
+164
+165
+166
| def collect(self):
"""
Evaluates the `Lazy` object into `QList`.
Same as calling `qlist()`
@@ -1245,9 +1250,7 @@
Source code in src\qwlist\qwlist.py
- 222
-223
-224
+ 224
225
226
227
@@ -1266,7 +1269,9 @@
240
241
242
-243 | def cycle(self):
+243
+244
+245
| def cycle(self):
"""
Returns a `Lazy[T]` that cycles through the elements of the `Lazy` object, that means
on achieving the last element the iteration starts from the beginning. The
@@ -1351,9 +1356,7 @@
Source code in src\qwlist\qwlist.py
- 50
-51
-52
+ 52
53
54
55
@@ -1369,7 +1372,9 @@
65
66
67
-68 | def filter(self, pred: Callable[[T], bool]):
+68
+69
+70
| def filter(self, pred: Callable[[T], bool]):
"""
Returns a `Lazy` object containing all values from this `Lazy` object for which
the predicate holds true.
@@ -1450,9 +1455,7 @@
Source code in src\qwlist\qwlist.py
- 121
-122
-123
+ 123
124
125
126
@@ -1466,7 +1469,9 @@
134
135
136
-137 | def flatmap(self, mapper: Callable[[T], Iterable[K]]):
+137
+138
+139
| def flatmap(self, mapper: Callable[[T], Iterable[K]]):
"""
Applies the mapper function to each of the yielded elements and flattens the results.
@@ -1516,9 +1521,7 @@
Source code in src\qwlist\qwlist.py
- 206
-207
-208
+ 208
209
210
211
@@ -1530,7 +1533,9 @@
217
218
219
-220 | def flatten(self) -> "Lazy[T]":
+220
+221
+222
| def flatten(self) -> "Lazy[T]":
"""
If `self` is a `Lazy` object of `Iterable[T]`, flatten concatenates all iterables into a
single list and returns a `Lazy[T]` object.
@@ -1625,9 +1630,7 @@
Source code in src\qwlist\qwlist.py
- 85
- 86
- 87
+ 87
88
89
90
@@ -1647,7 +1650,9 @@
104
105
106
-107 | def fold(self, operation: Callable[[K, T], K], init: K) -> K:
+107
+108
+109
| def fold(self, operation: Callable[[K, T], K], init: K) -> K:
"""
Given the combination operator reduces the `Lazy` object by processing
its constituent parts, building up the final value.
@@ -1725,9 +1730,7 @@
Source code in src\qwlist\qwlist.py
- 109
-110
-111
+ 111
112
113
114
@@ -1735,7 +1738,9 @@
116
117
118
-119 | def foreach(self, action: Callable[[T], None]):
+119
+120
+121
| def foreach(self, action: Callable[[T], None]):
"""
Applies the given function to each of yielded elements.
@@ -1771,13 +1776,13 @@
Source code in src\qwlist\qwlist.py
- 33
-34
-35
+ | def list(self) -> list[T]:
+39
+40
+41
| def list(self) -> list[T]:
"""
Evaluates the `Lazy` object into `list`.
@@ -1840,9 +1845,7 @@
Source code in src\qwlist\qwlist.py
- 70
-71
-72
+ 72
73
74
75
@@ -1853,7 +1856,9 @@
80
81
82
-83 | def map(self, mapper: Callable[[T], K]):
+83
+84
+85
| def map(self, mapper: Callable[[T], K]):
"""
Returns a `Lazy` object containing all values from this `Lazy` object with
the mapping function applied on them.
@@ -1893,14 +1898,14 @@
Source code in src\qwlist\qwlist.py
- 41
-42
-43
+ | def qlist(self):
+48
+49
+50
| def qlist(self):
"""
Evaluates the `Lazy` object into `QList`.
Same as calling `collect()`
@@ -1942,9 +1947,7 @@
Source code in src\qwlist\qwlist.py
- 169
-170
-171
+ 171
172
173
174
@@ -1958,7 +1961,9 @@
182
183
184
-185 | def skip(self, n: int) -> "Lazy[T]":
+185
+186
+187
| def skip(self, n: int) -> "Lazy[T]":
"""
Skips n first elements of the `Lazy` object.
Args:
@@ -2009,9 +2014,7 @@
Source code in src\qwlist\qwlist.py
- 187
-188
-189
+ 189
190
191
192
@@ -2026,7 +2029,9 @@
201
202
203
-204 | def take(self, n: int) -> "Lazy[T]":
+204
+205
+206
| def take(self, n: int) -> "Lazy[T]":
"""
Takes n first elements of the `Lazy` object.
Args:
@@ -2108,9 +2113,7 @@
Source code in src\qwlist\qwlist.py
- 139
-140
-141
+ 141
142
143
144
@@ -2123,7 +2126,9 @@
151
152
153
-154 | def zip(self, other: Iterable[K]) -> "Lazy[tuple[T, K]]":
+154
+155
+156
| def zip(self, other: Iterable[K]) -> "Lazy[tuple[T, K]]":
"""
Combines this `Lazy` object with the given `Iterable` elementwise as tuples.
The returned `Lazy` objects yields at most the number of elements of
diff --git a/site/qlist/index.html b/site/qlist/index.html
index ce8e822..4ec1289 100644
--- a/site/qlist/index.html
+++ b/site/qlist/index.html
@@ -633,12 +633,14 @@ QList
Bases: list
+
+ QList is a python list extension that adds several chainable, lazy
+evaluated methods to the standard 'list'.
+Found in qwlist.QList
Source code in src\qwlist\qwlist.py
- 246
-247
-248
+ 248
249
250
251
@@ -902,7 +904,21 @@ QList
509
510
511
-512 | class QList(list):
+512
+513
+514
+515
+516
+517
+518
+519
+520
| class QList(list):
+ """
+ `QList` is a python list extension that adds several chainable, lazy
+ evaluated methods to the standard 'list'.
+
+ Found in `qwlist.QList`
+ """
@overload
def __getitem__(self, item: slice) -> "QList[T]":
@@ -1213,15 +1229,7 @@
Source code in src\qwlist\qwlist.py
- 491
-492
-493
-494
-495
-496
-497
-498
-499
+ 499
500
501
502
@@ -1234,7 +1242,15 @@
509
510
511
-512 | def cycle(self):
+512
+513
+514
+515
+516
+517
+518
+519
+520
| def cycle(self):
"""
Returns a Lazy[T] that cycles through the elements of the QList that means
on achieving the last element the iteration starts from the beginning. The
@@ -1281,14 +1297,14 @@
Source code in src\qwlist\qwlist.py
- 286
-287
-288
-289
-290
-291
-292
-293 | def eager(self) -> "EagerQList[T]":
+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|