Skip to content

Commit 419e1ff

Browse files
cleooldcleoold
committed
Add sphinx-based docs; add api rst doc generator; add readthedocs config
1 parent 1083550 commit 419e1ff

19 files changed

+2732
-119
lines changed

‎.gitignore

+6
Original file line numberDiff line numberDiff line change
@@ -132,3 +132,9 @@ dmypy.json
132132
[Ii]nclude/
133133
[Ss]cripts/
134134
pyvenv.cfg
135+
136+
# sphinx
137+
doc/_build
138+
139+
# editor
140+
.vscode

‎.readthedocs.yaml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Build documentation in the docs/ directory with Sphinx
9+
sphinx:
10+
builder: html
11+
configuration: docs/conf.py
12+
13+
# Optionally build your docs in additional formats such as PDF
14+
formats:
15+
- pdf
16+
- epub
17+
18+
# Optionally set the version of Python and requirements required to build your docs
19+
python:
20+
version: 3.9
21+
install:
22+
- requirements: docs/requirements.txt

‎README.md

+3-119
Original file line numberDiff line numberDiff line change
@@ -1,123 +1,7 @@
11
# types-linq
22

3-
![Python](https://img.shields.io/badge/python-3.7%2B-blue.svg) [![pypi](https://img.shields.io/pypi/v/types-linq)](https://pypi.org/project/types-linq/) [![pytest](https://github.com/cleoold/types-linq/workflows/pytest/badge.svg)](https://github.com/cleoold/types-linq/actions?query=workflow%3Apytest) [![codecov](https://codecov.io/gh/cleoold/types-linq/branch/main/graph/badge.svg?token=HTUKZ0SQJ3)](https://codecov.io/gh/cleoold/types-linq)
3+
![Python](https://img.shields.io/badge/python-3.7%2B-blue.svg) [![pypi](https://img.shields.io/pypi/v/types-linq)](https://pypi.org/project/types-linq/) [![pytest](https://github.com/cleoold/types-linq/workflows/pytest/badge.svg)](https://github.com/cleoold/types-linq/actions?query=workflow%3Apytest) [![codecov](https://codecov.io/gh/cleoold/types-linq/branch/main/graph/badge.svg?token=HTUKZ0SQJ3)](https://codecov.io/gh/cleoold/types-linq) [![Documentation Status](https://readthedocs.org/projects/types-linq/badge/?version=latest)](https://types-linq.readthedocs.io/en/latest/?badge=latest)
44

5-
This is an attempt to implement linq methods seen in .NET ([link](https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable?view=net-5.0)). Currently WIP.
5+
types-linq is a lightweight Python library that attempts to implement LinQ (Language Integrated Query) features seen in .NET languages.
66

7-
Goal:
8-
* Incorporates Enumerable method specs as precise as possible
9-
* Handles infinite streams (generators) smoothly like in _SICP_
10-
* Deferred evaluations
11-
* Detailed typing support
12-
* Honours collections.abc interfaces
13-
14-
## Install
15-
16-
To install this library on your computer, do:
17-
```sh
18-
$ git clone https://github.com/cleoold/types-linq && cd types-linq
19-
$ pip install .
20-
# or
21-
$ python setup.py install
22-
```
23-
Or install from pypi:
24-
```sh
25-
$ pip install types-linq -U
26-
```
27-
28-
## Dev
29-
Execute the following commands (or something similar) to run the test cases:
30-
```sh
31-
# optionally set up venv
32-
$ python -m venv
33-
$ ./scripts/activate
34-
35-
$ pip install pytest
36-
$ python -m pytest
37-
```
38-
39-
## Examples
40-
41-
The usage is simple if you know about the interfaces in .NET as this library provides almost the exact methods.
42-
43-
### [Grouping](https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.groupjoin) & Transforming lists
44-
```py
45-
from typing import NamedTuple
46-
from types_linq import Enumerable as En
47-
48-
49-
class AnswerSheet(NamedTuple):
50-
subject: str
51-
score: int
52-
name: str
53-
54-
students = ['Jacque', 'Franklin', 'Romeo']
55-
papers = [
56-
AnswerSheet(subject='Calculus', score=78, name='Jacque'),
57-
AnswerSheet(subject='Calculus', score=98, name='Romeo'),
58-
AnswerSheet(subject='Algorithms', score=59, name='Romeo'),
59-
AnswerSheet(subject='Mechanics', score=93, name='Jacque'),
60-
AnswerSheet(subject='E & M', score=87, name='Jacque'),
61-
]
62-
63-
query = En(students) \
64-
.order_by(lambda student: student) \
65-
.group_join(papers,
66-
lambda student: student,
67-
lambda paper: paper.name,
68-
lambda student, papers: {
69-
'student': student,
70-
'papers': papers.order_by(lambda paper: paper.subject) \
71-
.select(lambda paper: {
72-
'subject': paper.subject,
73-
'score': paper.score,
74-
}).to_list(),
75-
'gpa': papers.average2(lambda paper: paper.score, None),
76-
}
77-
)
78-
79-
for obj in query:
80-
print(obj)
81-
82-
# output:
83-
# {'student': 'Franklin', 'papers': [], 'gpa': None}
84-
# {'student': 'Jacque', 'papers': [{'subject': 'E & M', 'score': 87}, {'subject': 'Mechanics', 'score': 93}, {'subject': 'Calculus', 'score': 78}], 'gpa': 86.0}
85-
# {'student': 'Romeo', 'papers': [{'subject': 'Algorithms', 'score': 59}, {'subject': 'Calculus', 'score': 98}], 'gpa': 78.5}
86-
```
87-
88-
### Working with generators
89-
```py
90-
import random
91-
from types_linq import Enumerable as En
92-
93-
def toss_coins():
94-
while True:
95-
yield random.choice(('Head', 'Tail'))
96-
97-
times_head = En(toss_coins()).take(5) \ # [:5] also works
98-
.count(lambda r: r == 'Head')
99-
100-
print(f'You tossed 5 times with {times_head} HEADs!')
101-
102-
# possible output:
103-
# You tossed 5 times with 2 HEADs!
104-
```
105-
106-
### Also querying stream output
107-
Mixing with builtin iterable type objects.
108-
```py
109-
import sys, subprocess
110-
from types_linq import Enumerable as En
111-
112-
proc = subprocess.Popen('kubectl logs -f my-pod', shell=True, stdout=subprocess.PIPE)
113-
stdout = iter(proc.stdout.readline, b'')
114-
115-
query = En(stdout).where(lambda line: line.startswith(b'CRITICAL: ')) \
116-
.select(lambda line: line[10:].decode())
117-
118-
for line in query:
119-
sys.stdout.write(line)
120-
sys.stdout.flush()
121-
122-
# whatever.
123-
```
7+
Usage, guide and API references are in the [documentation](https://types-linq.readthedocs.io/en/latest/) page.

‎doc/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/_static/override.css

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.rst-content code,
2+
.rst-content tt,
3+
code {
4+
font-size: 90%;
5+
border: none;
6+
border-bottom: 1px solid rgba(61, 110, 110, 0.288);
7+
}
8+
9+
span.pre {
10+
color: rgb(21, 77, 78);
11+
white-space: normal;
12+
}
13+
14+
.wy-menu .toctree-l1 span.pre {
15+
color: unset;
16+
}
17+
18+
.wy-nav-content {
19+
max-width: 1100px;
20+
}
21+
22+
.rst-content .linenodiv pre,
23+
.rst-content div[class^="highlight"] pre,
24+
.rst-content pre.literal-block {
25+
font-size: 14px;
26+
}

‎doc/api/types_linq.cached_enumerable.rst

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
module ``types_linq.cached_enumerable``
2+
########################################
3+
4+
class ``CachedEnumerable[TSource_co]``
5+
****************************************
6+
7+
Enumerable that stores the enumerated results which can be accessed repeatedly.
8+
9+
Bases
10+
======
11+
- ``Enumerable[TSource_co]``
12+
13+
Members
14+
========
15+
instancemethod ``as_cached(*, cache_capacity=None)``
16+
------------------------------------------------------
17+
18+
Parameters
19+
- `cache_capacity` (``Optional[int]``)
20+
21+
Returns
22+
- ``CachedEnumerable[TSource_co]``
23+
24+
Updates settings and returns the original Enumerable reference.
25+
26+
Raises `InvalidOperationError` if cache_capacity is negative.
27+
28+

0 commit comments

Comments
 (0)