10000 Readme update (#208) · blog2i2j/pyexcel.._..pyexcel@ec1059a · GitHub
[go: up one dir, main page]
Skip to content

Commit ec1059a

Browse files
chfwchfw
authored
Readme update (pyexcel#208)
* 📚 experiment with one lines in readme * 📚 experiment with one lines in readme * 📚 update readme with better one liners * 📚 update readme with better one liners * 📚 include two liners in readme * 🚜 re-arrange brief intro to doc index
1 parent 8c09192 commit ec1059a

File tree

14 files changed

+1114
-319
lines changed

14 files changed

+1114
-319
lines changed

‎.gitignore

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@ parts/
2525
sdist/
2626
var/
2727
wheels/
28-
pip-wheel-metadata/
2928
share/python-wheels/
3029
*.egg-info/
3130
.installed.cfg
@@ -143,10 +142,6 @@ dmypy.json
143142
# Cython debug symbols
144143
cython_debug/
145144

146-
# static files generated from Django application using `collectstatic`
147-
media
148-
static
149-
150145
# VirtualEnv rules
151146
# Virtualenv
152147
# http://iamzed.com/2009/05/07/a-primer-on-virtualenv/
@@ -431,6 +426,9 @@ tmtags
431426
!.vscode/extensions.json
432427
*.code-workspace
433428

429+
# Local History for Visual Studio Code
430+
.history/
431+
434432
# Xcode rules
435433
# Xcode
436434
#

‎.moban.d/docs/source/pyexcel-index.rst.jj2

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,127 @@ Installation
2323

2424
{%include "installation.rst.jj2" %}
2525

26+
Suppose you have the following data in a dictionary:
27+
28+
========= ====
29+
Name Age
30+
========= ====
31+
Adam 28
32+
Beatrice 29
33+
Ceri 30
34+
Dean 26
35+
========= ====
36+
37+
you can easily save it into an excel file using the following code:
38+
39+
.. code-block:: python
40+
41+
>>> import pyexcel
42+
>>> # make sure you had pyexcel-xls installed
43+
>>> a_list_of_dictionaries = [
44+
... {
45+
... "Name": 'Adam',
46+
... "Age": 28
47+
... },
48+
... {
49+
... "Name": 'Beatrice',
50+
... "Age": 29
51+
... },
52+
... {
53+
... "Name": 'Ceri',
54+
... "Age": 30
55+
... },
56+
... {
57+
... "Name": 'Dean',
58+
... "Age": 26
59+
... }
60+
... ]
61+
>>> pyexcel.save_as(records=a_list_of_dictionaries, dest_file_name="your_file.xls")
62+
63+
And here's how to obtain the records:
64+
65+
.. code-block:: python
66+
67+
>>> import pyexcel as p
68+
>>> records = p.iget_records(file_name="your_file.xls")
69+
>>> for record in records:
70+
... print("%s is aged at %d" % (record['Name'], record['Age']))
71+
Adam is aged at 28
72+
Beatrice is aged at 29
73+
Ceri is aged at 30
74+
Dean is aged at 26
75+
>>> p.free_resources()
76+
77+
78+
Custom data rendering:
79+
80+
.. code-block:: python
81+
82+
>>> # pip install pyexcel-text==0.2.7.1
83+
>>> import pyexcel as p
84+
>>> ccs_insight2 = p.Sheet()
85+
>>> ccs_insight2.name = "Worldwide Mobile Phone Shipments (Billions), 2017-2021"
86+
>>> ccs_insight2.ndjson = """
87+
... {"year": ["2017", "2018", "2019", "2020", "2021"]}
88+
... {"smart phones": [1.53, 1.64, 1.74, 1.82, 1.90]}
89+
... {"feature phones": [0.46, 0.38, 0.30, 0.23, 0.17]}
90+
... """.strip()
91+
>>> ccs_insight2
92+
pyexcel sheet:
93+
+----------------+------+------+------+------+------+
94+
| year | 2017 | 2018 | 2019 | 2020 | 2021 |
95+
+----------------+------+------+------+------+------+
96+
| smart phones | 1.53 | 1.64 | 1.74 | 1.82 | 1.9 |
97+
+----------------+------+------+------+------+------+
98+
| feature phones | 0.46 | 0.38 | 0.3 | 0.23 | 0.17 |
99+
+----------------+------+------+------+------+------+
100+
101+
102+
Advanced usage :fire:
103+
----------------------
104+
105+
If you are dealing with big data, please consider these usages:
106+
107+
.. code-block:: python
108+
109+
>>> def increase_everyones_age(generator):
110+
... for row in generator:
111+
... row['Age'] += 1
112+
... yield row
113+
>>> def duplicate_each_record(generator):
114+
... for row in generator:
115+
... yield row
116+
... yield row
117+
>>> records = p.iget_records(file_name="your_file.xls")
118+
>>> io=p.isave_as(records=duplicate_each_record(increase_everyones_age(records)),
119+
... dest_file_type='csv', dest_lineterminator='\n')
120+
>>> print(io.getvalue())
121+
Age,Name
122+
29,Adam
123+
29,Adam
124+
30,Beatrice
125+
30,Beatrice
126+
31,Ceri
127+
31,Ceri
128+
27,Dean
129+
27,Dean
130+
<BLANKLINE>
131+
132+
133+
Two advantages of above method:
134+
135+
#. Add as many wrapping functions as you want.
136+
#. Constant memory consumption
137+
138+
139+
.. testcode::
140+
:hide:
141+
142+
>>> import os
143+
>>> os.unlink("your_file.xls")
144+
145+
146+
26147
For individual excel file formats, please install them as you wish:
27148

28149
{%include "plugins-list.rst.jj2"%}

‎.moban.d/pyexcel-README.rst.jj2

Lines changed: 4 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -13,126 +13,16 @@ Feature Highlights
1313
* Django Model
1414
* Python data structures: dictionary, records and array
1515
2. One API to read and write data in various excel file formats.
16-
3. For large data sets, data streaming are supported. A genenerator can be returned to you. Checkout iget_records, iget_array, isave_as and isave_book_as.
16+
3. For large data sets, data streaming are supported. A genenerator can be returned to you. Checkout iget_records, iget_array, isave_as and isave_book_as.
1717

1818
{% endblock %}
1919

2020
{%block usage%}
2121

22-
Usage
23-
===============
22+
{%include "one-liners.rst.jj2"%}
23+
24+
{%include "two-liners.rst.jj2"%}
2425

25-
Suppose you have the following data in a dictionary:
26-
27-
========= ====
28-
Name Age
29-
========= ====
30-
Adam 28
31-
Beatrice 29
32-
Ceri 30
33-
Dean 26
34-
========= ====
35-
36-
you can easily save it into an excel file using the following code:
37-
38-
.. code-block:: python
39-
40-
>>> import pyexcel
41-
>>> # make sure you had pyexcel-xls installed
42-
>>> a_list_of_dictionaries = [
43-
... {
44-
... "Name": 'Adam',
45-
... "Age": 28
46-
... },
47-
... {
48-
... "Name": 'Beatrice',
49-
... "Age": 29
50-
... },
51-
... {
52-
... "Name": 'Ceri',
53-
... "Age": 30
54-
... },
55-
... {
56-
... "Name": 'Dean',
57-
... "Age": 26
58-
... }
59-
... ]
60-
>>> pyexcel.save_as(records=a_list_of_dictionaries, dest_file_name="your_file.xls")
61-
62-
And here's how to obtain the records:
63-
64-
.. code-block:: python
65-
66-
>>> import pyexcel as p
67-
>>> records = p.iget_records(file_name="your_file.xls")
68-
>>> for record in records:
69-
... print("%s is aged at %d" % (record['Name'], record['Age']))
70-
Adam is aged at 28
71-
Beatrice is aged at 29
72-
Ceri is aged at 30
73-
Dean is aged at 26
74-
>>> p.free_resources()
75-
76-
77-
Custom data rendering:
78-
79-
.. code-block:: python
80-
81-
>>> # pip install pyexcel-text==0.2.7.1
82-
>>> import pyexcel as p
83-
>>> ccs_insight2 = p.Sheet()
84-
>>> ccs_insight2.name = "Worldwide Mobile Phone Shipments (Billions), 2017-2021"
85-
>>> ccs_insight2.ndjson = """
86-
... {"year": ["2017", "2018", "2019", "2020", "2021"]}
87-
... {"smart phones": [1.53, 1.64, 1.74, 1.82, 1.90]}
88-
... {"feature phones": [0.46, 0.38, 0.30, 0.23, 0.17]}
89-
... """.strip()
90-
>>> ccs_insight2
91-
pyexcel sheet:
92-
+----------------+------+------+------+------+------+
93-
| year | 2017 | 2018 | 2019 | 2020 | 2021 |
94-
+----------------+------+------+------+------+------+
95-
| smart phones | 1.53 | 1.64 | 1.74 | 1.82 | 1.9 |
96-
+----------------+------+------+------+------+------+
97-
| feature phones | 0.46 | 0.38 | 0.3 | 0.23 | 0.17 |
98-
+----------------+------+------+------+------+------+
99-
100-
101-
Advanced usage :fire:
102-
----------------------
103-
104-
If you are dealing with big data, please consider these usages:
105-
106-
.. code-block:: python
107-
108-
>>> def increase_everyones_age(generator):
109-
... for row in generator:
110-
... row['Age'] += 1
111-
... yield row
112-
>>> def duplicate_each_record(generator):
113-
... for row in generator:
114-
... yield row
115-
... yield row
116-
>>> records = p.iget_records(file_name="your_file.xls")
117-
>>> io=p.isave_as(records=duplicate_each_record(increase_everyones_age(records)),
118-
... dest_file_type='csv', dest_lineterminator='\n')
119-
>>> print(io.getvalue())
120-
Age,Name
121-
29,Adam
122-
29,Adam
123-
30,Beatrice
124-
30,Beatrice
125-
31,Ceri
126-
31,Ceri
127-
27,Dean
128-
27,Dean
129-
<BLANKLINE>
130-
131-
132-
Two advantages of above method:
133-
134-
#. Add as many wrapping functions as you want.
135-
#. Constant memory consumption
13626

13727
Available Plugins
13828
=================
@@ -147,12 +37,6 @@ All great work have been done by odf, ezodf, xlrd, xlwt, tabulate and other
14737
individual developers. This library unites only the data access code.
14838

14939

150-
.. testcode::
151-
:hide:
152-
153-
>>> import os
154-
>>> os.unlink("your_file.xls")
155-
15640
{%endblock%}
15741

15842
{%block development_guide%}

‎.moban.d/test.bat.jj2

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎.moban.d/test.sh.jj2

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎.moban.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ configuration:
44
targets:
55
- setup.py: custom_setup.py.jj2
66
- "docs/source/conf.py": "docs/source/custom_conf.py.jj2"
7+
- "docs/source/quickstart.rst": "docs/source/quickstart.rst.jj2"
78
- .travis.yml: pyexcel-travis.yml.jj2
89
- MANIFEST.in: CUSTOM_MANIFEST.in.jj2
910
- README.rst: pyexcel-README.rst.jj2

0 commit comments

Comments
 (0)
0