mirror of
https://github.com/kennethreitz/tablib.git
synced 2026-06-05 23:10:17 +00:00
Documentation update.
This commit is contained in:
Kenneth Reitz
@@ -0,0 +1,10 @@
|
||||
* Roll documetation out.
|
||||
* http://tablib.org.
|
||||
* add required header parameter for col append.
|
||||
* Write exhausive unit-tests.
|
||||
* Write stress tests.
|
||||
|
||||
* ``Dataset.traspose()`` support
|
||||
|
||||
|
||||
|
||||
+38
-8
@@ -5,18 +5,18 @@ Development
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
||||
|
||||
.. _future:
|
||||
Future of Tablib
|
||||
----------------
|
||||
There's a todo list.
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
|
||||
.. include:: ../TODO.rst
|
||||
|
||||
|
||||
.. _design:
|
||||
|
||||
---------------------
|
||||
Design Considerations
|
||||
---------------------
|
||||
|
||||
Tablib was developed with a few `The Zen of Python`_ idioms in mind.
|
||||
Tablib was developed with a few :pep:`20` idioms in mind.
|
||||
|
||||
#. Beautiful is better than ugly.
|
||||
#. Explicit is better than implicit.
|
||||
@@ -26,17 +26,35 @@ Tablib was developed with a few `The Zen of Python`_ idioms in mind.
|
||||
|
||||
It strives to be as simple to use as possible.
|
||||
|
||||
.. _git:
|
||||
|
||||
.. _scm:
|
||||
|
||||
--------------
|
||||
Source Control
|
||||
--------------
|
||||
|
||||
|
||||
Tablib source is controlled with Git_, the lean, mean, distributed source control machine.
|
||||
|
||||
**Branch Structure**
|
||||
|
||||
``develop``
|
||||
The "next release" branch. Likely unstable.
|
||||
``master``
|
||||
Current production release (|version|) on PyPi.
|
||||
|
||||
Git.
|
||||
GitHub.
|
||||
git.kennethreitz.com
|
||||
|
||||
Git Flow
|
||||
|
||||
.. _Git: http://git-scm.org
|
||||
|
||||
.. _newformats:
|
||||
|
||||
|
||||
------------------
|
||||
Adding New Formats
|
||||
------------------
|
||||
|
||||
@@ -44,14 +62,19 @@ Don't.
|
||||
|
||||
|
||||
.. _testing:
|
||||
|
||||
--------------
|
||||
Testing Tablib
|
||||
--------------
|
||||
|
||||
Testing is crucial to Tablib's stability. This stable project is used in production by many companies and developers, so it is important to be certian that every version released is fully operational. When developing a new feature for Tablib, be sure to write proper tests for it as well.
|
||||
|
||||
|
||||
++++++++++++++++++++++
|
||||
Running the Test Suite
|
||||
++++++++++++++++++++++
|
||||
|
||||
|
||||
When developing a feature for Tablib, the easiest way to test your changes for potential issues is to simply run the test suite directly. ::
|
||||
|
||||
$ ./test_tablib.py
|
||||
@@ -71,9 +94,12 @@ This will generate a **nosetests.xml** file, which can then be analyzed.
|
||||
|
||||
.. _Nose: http://somethingaboutorange.com/mrl/projects/nose/
|
||||
|
||||
|
||||
++++++++++++++++++++++++
|
||||
Extending the Test Suite
|
||||
++++++++++++++++++++++++
|
||||
|
||||
|
||||
Example: ::
|
||||
|
||||
import tablib.formats.sql.test_sql
|
||||
@@ -93,18 +119,20 @@ Anyone may view the build status and history at any time.
|
||||
If you are trustworthy and plan to contribute to tablib on a regular basis, please contact `Kenneth Reitz`_ to get an account on the Hudson Server.
|
||||
|
||||
|
||||
Additional reports will also be included here in the future, including PEP 8 checks and stress reports for extremely large datasets.
|
||||
Additional reports will also be included here in the future, including :pep:`8` checks and stress reports for extremely large datasets.
|
||||
|
||||
.. _`Hudson CI`: http://hudson.dev.java.net
|
||||
.. _`Kenneth Reitz`: http://kennethreitz.com/contact-me/
|
||||
|
||||
|
||||
.. _docs:
|
||||
|
||||
-----------------
|
||||
Building the Docs
|
||||
-----------------
|
||||
|
||||
Documentation is written in the powerful, flexible, and standard Python documentation format, `reStructured Text`_.
|
||||
Documentation builds are powered by powerful Pocoo project, Sphinx_. The :ref:`API Documentation <api>` is mostly documented inline throught the module.
|
||||
Documentation builds are powered by the powerful Pocoo project, Sphinx_. The :ref:`API Documentation <api>` is mostly documented inline throught the module.
|
||||
|
||||
The Docs live in ``tablib/docs``. In order to build them, you will first need to install Sphinx. ::
|
||||
|
||||
@@ -148,4 +176,6 @@ You can also generate the documentation in **ebpub**, **latex**, **json**, *&c*
|
||||
.. _Jeckyl: http://github.com/mojombo/jekyll
|
||||
.. _`sphinx-to-github`: http://github.com/michaeljones/sphinx-to-github
|
||||
|
||||
----------
|
||||
|
||||
Make sure to check out the :ref:`API Documentation <api>`.
|
||||
+1
-1
@@ -6,7 +6,7 @@
|
||||
Tablib: Pythonic Tabular Data
|
||||
=============================
|
||||
|
||||
Welcome to Tablib's docuemtation.
|
||||
Welcome to Tablib's documentation.
|
||||
|
||||
.. Contents:
|
||||
..
|
||||
|
||||
+4
-2
@@ -6,6 +6,8 @@ This part of the documentation covers the installation of Tablib. The first step
|
||||
|
||||
|
||||
.. _installing:
|
||||
|
||||
-----------------
|
||||
Installing Tablib
|
||||
-----------------
|
||||
|
||||
@@ -19,7 +21,7 @@ Or, if you must: ::
|
||||
|
||||
But, you really shouldn't do that.
|
||||
|
||||
|
||||
-------------------
|
||||
Download the Source
|
||||
-------------------
|
||||
|
||||
@@ -34,7 +36,7 @@ Once you have a copy of the source, you can embed it in your Python package, or
|
||||
$ python setup.py install
|
||||
|
||||
|
||||
To download the full source history from Git, see :ref:`Source Control <git>`.
|
||||
To download the full source history from Git, see :ref:`Source Control <scm>`.
|
||||
|
||||
.. _tarball: http://github.com/kennethreitz/tablib/tarball/master
|
||||
.. _zipball: http://github.com/kennethreitz/tablib/zipball/master
|
||||
|
||||
+1
-1
@@ -41,7 +41,7 @@ MIT License
|
||||
|
||||
A large number of open source projects you find today are `GPL Licensed`_. While the GPL certianly has essential applications, it should most certianly not be your go-to license for your next open source project.
|
||||
|
||||
A project that was released as GPL cannot be usd in any commercial product without the product itself also being offered as open source. The MIT and BSD licenses are fantastic alternatives to this *major* problem.
|
||||
A project that is released as GPL cannot be usd in any commercial product without the product itself also being offered as open source. The MIT and BSD licenses are great alternatives to the GPL that allow your open-source software to be used in proprietary, closed-source software.
|
||||
|
||||
Tablib is released under terms of `The MIT License`_.
|
||||
|
||||
|
||||
+124
-10
@@ -72,16 +72,14 @@ It's time enhance our :class:`Dataset` by giving our columns some titles. To do
|
||||
|
||||
data.headers = ['First Name', 'Last Name']
|
||||
|
||||
Let's view the data in YAML this time. ::
|
||||
Now our data looks a little different. ::
|
||||
|
||||
>>> data.yaml
|
||||
- {First Name: Kenneth, Last Name: Reitz}
|
||||
- {First Name: Bessie, Last Name: Monke}
|
||||
>>> data.dict
|
||||
[{'Last Name': 'Reitz', 'First Name': 'Kenneth'}, {'Last Name': 'Monke', 'First Name': 'Bessie'}]
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
--------------
|
||||
Adding Columns
|
||||
--------------
|
||||
@@ -91,15 +89,44 @@ Now that we have a basic :class:`Dataset` in place, let's add a column of **ages
|
||||
|
||||
data.append(col=['Age', 22, 20])
|
||||
|
||||
Let's view the data in CSV this time. ::
|
||||
Let's view the data now. ::
|
||||
|
||||
>>> data.dict
|
||||
[{'Last Name': 'Reitz', 'First Name': 'Kenneth', 'Age': 22}, {'Last Name': 'Monke', 'First Name': 'Bessie', 'Age': 21}]
|
||||
|
||||
It's that easy.
|
||||
|
||||
|
||||
--------------
|
||||
Exporting Data
|
||||
--------------
|
||||
|
||||
Tablib's killer feature is the ability to export your :class:`Dataset` objects into a number of formats.
|
||||
|
||||
**Comma-Seperated Values** ::
|
||||
|
||||
>>> data.csv
|
||||
Last Name,First Name,Age
|
||||
Reitz,Kenneth,22
|
||||
Monke,Bessie,20
|
||||
Monke,Bessie,21
|
||||
|
||||
It's that easy.
|
||||
**JavaScript Object Notation** ::
|
||||
|
||||
>>> data.json
|
||||
[{"Last Name": "Reitz", "First Name": "Kenneth", "Age": 22}, {"Last Name": "Monke", "First Name": "Bessie", "Age": 21}]
|
||||
|
||||
|
||||
**YAML Ain't Markup Language** ::
|
||||
|
||||
>>> data.yaml
|
||||
- {Age: 22, First Name: Kenneth, Last Name: Reitz}
|
||||
- {Age: 21, First Name: Bessie, Last Name: Monke}
|
||||
|
||||
|
||||
**Microsoft Excel** ::
|
||||
|
||||
>>> data.xls
|
||||
<censored binary data>
|
||||
|
||||
|
||||
------------------------
|
||||
@@ -131,9 +158,14 @@ Let's find the average age. ::
|
||||
Removing Rows & Columns
|
||||
-----------------------
|
||||
|
||||
data.insert('MI', )
|
||||
::
|
||||
|
||||
>>> del data['Col Name']
|
||||
|
||||
::
|
||||
|
||||
>>> del data[0:12]
|
||||
|
||||
>>> del data['Row Name']
|
||||
Fucking easy.
|
||||
|
||||
|
||||
@@ -142,8 +174,12 @@ Fucking easy.
|
||||
Advanced Usage
|
||||
==============
|
||||
|
||||
|
||||
This part of the documentation services to give you an idea that are otherwise hard to extract from the :ref:`API Documentation <api>`
|
||||
|
||||
And now for something completely different.
|
||||
|
||||
|
||||
---------------
|
||||
Dynamic Columns
|
||||
---------------
|
||||
@@ -212,12 +248,90 @@ Adding this function to our dataset as a dynamic column would result in: ::
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Excel Workbook With Multiple Sheets
|
||||
------------------------------------
|
||||
|
||||
:class:`Databook`
|
||||
|
||||
::
|
||||
|
||||
book = tablib.Databook([data, data, data])
|
||||
|
||||
::
|
||||
|
||||
with open('students.xls', 'wb') as f:
|
||||
f.write(book.xls)
|
||||
|
||||
The resulting **students.xls** file will contain a seperate spreadsheet for each :class:`Dataset` object in the :class:`Databook`.
|
||||
|
||||
.. admonition:: Binary Warning
|
||||
|
||||
Make sure to open the output file in binary mode.
|
||||
|
||||
|
||||
.. _seperators:
|
||||
|
||||
----------
|
||||
Seperators
|
||||
----------
|
||||
|
||||
.. versionadded:: 0.8.2
|
||||
|
||||
When, it's often useful to create a blank row containing information on the upcomming data. So,
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
daniel_tests = [
|
||||
('11/24/09', 'Math 101 Mid-term Exam', 56.),
|
||||
('05/24/10', 'Math 101 Final Exam', 62.)
|
||||
]
|
||||
|
||||
suzie_tests = [
|
||||
('11/24/09', 'Math 101 Mid-term Exam', 56.),
|
||||
('05/24/10', 'Math 101 Final Exam', 62.)
|
||||
]
|
||||
|
||||
# Create new dataset
|
||||
tests = tablib.Dataset()
|
||||
tests.headers = ['Date', 'Test Name', 'Grade']
|
||||
|
||||
# Daniel's Tests
|
||||
tests.append_seperator('Daniel\'s Scores')
|
||||
|
||||
for test_row in daniel_tests:
|
||||
tests.append(test_row)
|
||||
|
||||
# Susie's Tests
|
||||
tests.append_seperator('Susie\'s Scores')
|
||||
|
||||
for test_row in suzie_tests:
|
||||
tests.append(test_row)
|
||||
|
||||
# Write spreadsheet to disk
|
||||
with open('grades.xls', 'wb') as f:
|
||||
f.write(tests.xls)
|
||||
|
||||
The resulting **tests.xls** will have the following layout:
|
||||
|
||||
|
||||
Daniel's Scores:
|
||||
* '11/24/09', 'Math 101 Mid-term Exam', 56.
|
||||
* '05/24/10', 'Math 101 Final Exam', 62.
|
||||
|
||||
Suzie's Scores:
|
||||
* '11/24/09', 'Math 101 Mid-term Exam', 56.
|
||||
* '05/24/10', 'Math 101 Final Exam', 62.
|
||||
|
||||
|
||||
|
||||
.. admonition:: Format Support
|
||||
|
||||
At this time, only :class:`Excel <Dataset.xls>` output supports seperators.
|
||||
|
||||
----
|
||||
|
||||
Now, go check out the :ref:`API Documentation <api>` or begin :ref:`Tablib Development <development>`.
|
||||
Reference in New Issue
Block a user