mirror of
https://github.com/kennethreitz/tablib.git
synced 2026-06-05 23:10:17 +00:00
Big Documentation Upgrade.
This commit is contained in:
Kenneth Reitz
+13
-3
@@ -16,15 +16,25 @@ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
|
||||
Design Considerations
|
||||
---------------------
|
||||
|
||||
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.
|
||||
Tablib was developed with a few `The Zen of Python`_ idioms in mind.
|
||||
|
||||
#. Beautiful is better than ugly.
|
||||
#. Explicit is better than implicit.
|
||||
#. Simple is better than complex.
|
||||
#. Complex is better than complicated.
|
||||
#. Readability counts.
|
||||
|
||||
.. _scm:
|
||||
It strives to be as simple to use as possible.
|
||||
|
||||
.. _git:
|
||||
Source Control
|
||||
--------------
|
||||
|
||||
Git.
|
||||
Git.
|
||||
GitHub.
|
||||
git.kennethreitz.com
|
||||
|
||||
Git Flow
|
||||
|
||||
.. _newformats:
|
||||
Adding New Formats
|
||||
|
||||
+22
-14
@@ -2,7 +2,7 @@
|
||||
Installation
|
||||
============
|
||||
|
||||
This part of the documentation covers the installation of Tablib. The first step to using any software package is getting it properly installed. Please read this section carefully, or you may miss out on some nice :ref:`speed enhancments <speed>`.
|
||||
This part of the documentation covers the installation of Tablib. The first step to using any software package is getting it properly installed. Please read this section carefully, or you may miss out on some nice :ref:`speed enhancments <peed-extentions>`.
|
||||
|
||||
|
||||
.. _installing:
|
||||
@@ -20,7 +20,27 @@ Or, if you must: ::
|
||||
But, you really shouldn't do that.
|
||||
|
||||
|
||||
.. _speed:
|
||||
Download the Source
|
||||
-------------------
|
||||
|
||||
You can also install tablib from source. The latest release (|version|) is available from GitHub.
|
||||
|
||||
* tarball_
|
||||
* zipball_
|
||||
|
||||
.. _
|
||||
Once you have a copy of the source, you can embed it in your Python package, or install it into your site-packages easily. ::
|
||||
|
||||
$ python setup.py install
|
||||
|
||||
|
||||
To download the full source history from Git, see :ref:`Source Control <git>`.
|
||||
|
||||
.. _tarball: http://github.com/kennethreitz/tablib/tarball/master
|
||||
.. _zipball: http://github.com/kennethreitz/tablib/zipball/master
|
||||
|
||||
|
||||
.. _speed-extentions:
|
||||
Speed Extentions
|
||||
----------------
|
||||
|
||||
@@ -38,18 +58,6 @@ If you're using Python 2.5 (currently unsupported), you should also install the
|
||||
|
||||
|
||||
|
||||
.. _pythonsupport:
|
||||
Pythons Supported
|
||||
-----------------
|
||||
|
||||
At this time, the following Python platforms are officially supported:
|
||||
|
||||
* Python 2.6
|
||||
* Python 2.7
|
||||
|
||||
Support for other Pythons will be rolled out soon.
|
||||
|
||||
|
||||
.. _updates:
|
||||
Staying Updated
|
||||
---------------
|
||||
|
||||
+44
-9
@@ -3,25 +3,43 @@
|
||||
Introduction
|
||||
============
|
||||
|
||||
This part of the documentation covers all the interfaces of Tablib. For
|
||||
parts where Tablib depends on external libraries, we document the most
|
||||
important right here and provide links to the canonical documentation.
|
||||
This part of the documentation covers all the interfaces of Tablib.
|
||||
Tablib is a format-agnostic tabular dataset library, written in Python. It allows you to Pythonically import, export, and manipulate tabular data sets.
|
||||
|
||||
|
||||
Why Tablib?
|
||||
-----------
|
||||
Inception
|
||||
---------
|
||||
|
||||
Why not?
|
||||
Tablib was build by `Kenneth Reitz`_ to fufill a specfic need.
|
||||
|
||||
It Should Be Easy
|
||||
-----------------
|
||||
Tablib was born.
|
||||
|
||||
.. _`Kenneth Reitz`: http://kennethreitz.com
|
||||
|
||||
|
||||
Philosphy
|
||||
---------
|
||||
|
||||
Tablib was developed with a few :pep:`20` idioms in mind.
|
||||
|
||||
|
||||
#. Beautiful is better than ugly.
|
||||
#. Explicit is better than implicit.
|
||||
#. Simple is better than complex.
|
||||
#. Complex is better than complicated.
|
||||
#. Readability counts.
|
||||
|
||||
Besides, Why not?
|
||||
|
||||
:ref:`seperators`
|
||||
|
||||
|
||||
.. _mit:
|
||||
|
||||
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 you next open source project.
|
||||
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.
|
||||
|
||||
@@ -30,4 +48,21 @@ Tablib is released under terms of `The MIT License`_.
|
||||
.. _`GPL Licensed`: http://www.opensource.org/licenses/gpl-license.php
|
||||
.. _`The MIT License`: http://www.opensource.org/licenses/mit-license.php
|
||||
|
||||
|
||||
|
||||
.. _pythonsupport:
|
||||
|
||||
Pythons Supported
|
||||
-----------------
|
||||
|
||||
At this time, the following Python platforms are officially supported:
|
||||
|
||||
* Python 2.6
|
||||
* Python 2.7
|
||||
|
||||
Support for other Pythons will be rolled out soon.
|
||||
|
||||
|
||||
|
||||
|
||||
Now, go :ref:`Install Tablib <install>`.
|
||||
+133
-8
@@ -1,22 +1,147 @@
|
||||
.. _quickstart:
|
||||
|
||||
Quickstart
|
||||
==========
|
||||
|
||||
This part of the documentation covers all the interfaces of Tablib. For
|
||||
parts where Tablib depends on external libraries, we document the most
|
||||
important right here and provide links to the canonical documentation.
|
||||
.. module:: tablib
|
||||
|
||||
|
||||
Basic Usage
|
||||
Eager to get started? This page gives a good introduction in how to get started with Tablib. This assumes you already have Tablib installed. If you do not, head over to the :ref:`Installation <install>` section.
|
||||
|
||||
First, make sure that:
|
||||
|
||||
* Tablib is :ref:`installed <install>`
|
||||
* Tablib is :ref:`up-to-date <updates>`
|
||||
|
||||
|
||||
Lets gets started with some simple use cases and examples.
|
||||
|
||||
Creating a Dataset
|
||||
------------------
|
||||
|
||||
A :class:`Dataset <tablib.Dataset>` is nothing more than what its name implies—a set of data.
|
||||
|
||||
Creating your own instance of the :class:`tablib.Dataset` object is simple. ::
|
||||
|
||||
data = tablib.Dataset()
|
||||
|
||||
You can now start filling this :class:`Dataset <tablib.Dataset>` object with data.
|
||||
|
||||
.. admonition:: Example Context
|
||||
|
||||
From here on out, if you see ``data``, assume that it's a fresh :class:`Dataset <tablib.Dataset>` object.
|
||||
|
||||
|
||||
Adding Rows
|
||||
-----------
|
||||
|
||||
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.
|
||||
Let's say you want to collect a simple list of names. ::
|
||||
|
||||
# collection of names
|
||||
names = ['Kenneth Reitz', 'Bessie Monke']
|
||||
|
||||
for name in names:
|
||||
# split name appropriately
|
||||
fname, lname = name.split()
|
||||
|
||||
# add names to Dataset
|
||||
data.append([fname, lname])
|
||||
|
||||
You can get a nice, Pythonic view of the dataset at any time with :class:`Dataset.dict`.
|
||||
|
||||
>>> data.dict
|
||||
[('Kenneth', 'Reitz'), ('Bessie', 'Monke')]
|
||||
|
||||
|
||||
Advanced Usage
|
||||
Adding Headers
|
||||
--------------
|
||||
|
||||
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.
|
||||
It's time enhance our :class:`Dataset` by giving our columns some titles. To do so, set :class:`Dataset.headers`. ::
|
||||
|
||||
data.headers = ['First Name', 'Last Name']
|
||||
|
||||
Let's view the data in YAML this time. ::
|
||||
|
||||
>>> data.yaml
|
||||
- {First Name: Kenneth, Last Name: Reitz}
|
||||
- {First Name: Bessie, Last Name: Monke}
|
||||
|
||||
|
||||
Adding Columns
|
||||
--------------
|
||||
|
||||
Now that we have a basic :class:`Dataset` in place, let's add a column of **ages** to it. ::
|
||||
|
||||
data.append(col=['Age', 22, 20])
|
||||
|
||||
Let's view the data in CSV this time. ::
|
||||
|
||||
>>> data.csv
|
||||
Last Name,First Name,Age
|
||||
Reitz,Kenneth,22
|
||||
Monke,Bessie,20
|
||||
|
||||
It's that easy.
|
||||
|
||||
Selecting Rows & Columns
|
||||
------------------------
|
||||
|
||||
You can slice and dice your data, just like a standard Python list. ::
|
||||
|
||||
>>> data[0]
|
||||
('Kenneth', 'Reitz', 22)
|
||||
|
||||
|
||||
If we had a set of data consisting of thousands of rows, it could be useful to get a list of values in a column.
|
||||
To do so, we access the :class:`Dataset` as if it were a standard Python dictionary. ::
|
||||
|
||||
>>> data['First Name']
|
||||
['Kenneth', 'Bessie']
|
||||
|
||||
Let's find the average age. ::
|
||||
|
||||
>>> ages = data['Age']
|
||||
>>> float(sum(ages)) / len(ages)
|
||||
21.0
|
||||
|
||||
|
||||
|
||||
Dynamic Columns
|
||||
---------------
|
||||
|
||||
.. newversion: 0.8.0
|
||||
|
||||
Thanks to Josh Ourisman, Tablib now supports adding dynamic columns.
|
||||
|
||||
|
||||
|
||||
::
|
||||
|
||||
import random
|
||||
|
||||
data.append(col=random.randint)
|
||||
|
||||
Let's delete that column.
|
||||
|
||||
.. _seperators:
|
||||
|
||||
Seperators
|
||||
----------
|
||||
|
||||
|
||||
|
||||
Transposition
|
||||
-------------
|
||||
|
||||
Thanks to Luca Beltrame, :class:`Dataset` objects
|
||||
::
|
||||
|
||||
data.transpose()
|
||||
|
||||
|
||||
Shortcuts
|
||||
---------
|
||||
|
||||
Population upon instantiation.
|
||||
|
||||
|
||||
Now, go check out the :ref:`API Documentation <api>` or begin :ref:`Tablib Development <development>`.
|
||||
Reference in New Issue
Block a user