From 7fda829d275c1375d7399f2c9234e0bf0093dbc3 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 10 Oct 2010 04:37:09 -0400 Subject: Documentation update. --- docs/api.rst | 37 +++++++++ docs/index.rst | 2 +- docs/quickstart.rst | 168 --------------------------------------- docs/tutorial.rst | 223 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 261 insertions(+), 169 deletions(-) delete mode 100644 docs/quickstart.rst create mode 100644 docs/tutorial.rst (limited to 'docs') diff --git a/docs/api.rst b/docs/api.rst index ce169b7..4a0ff52 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,8 +1,10 @@ .. _api: +=== API === + .. module:: tablib This part of the documentation covers all the interfaces of Tablib. For @@ -10,18 +12,53 @@ parts where Tablib depends on external libraries, we document the most important right here and provide links to the canonical documentation. +-------------- Dataset Object -------------- + + .. autoclass:: Dataset :inherited-members: +--------------- Databook Object --------------- + .. autoclass:: Databook :inherited-members: +--------- +Functions +--------- + + +.. autofunction:: detect + +.. autofunction:: import_set + + +---------- +Exceptions +---------- + + +.. class:: InvalidDatasetType + + Raised when shit goes down. + + +.. class:: InvalidDimensions + + Raised when shit goes down. + + +.. class:: UnsupportedFormat + + Raised when shit goes down. + + Now, go start some :ref:`Tablib Development `. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index ff757a6..5dcc564 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,7 +44,7 @@ This part of the documentation, which is mostly prose, begins with some backgrou .. toctree:: :maxdepth: 2 - quickstart + tutorial .. toctree:: :maxdepth: 2 diff --git a/docs/quickstart.rst b/docs/quickstart.rst deleted file mode 100644 index ae113a4..0000000 --- a/docs/quickstart.rst +++ /dev/null @@ -1,168 +0,0 @@ -.. _quickstart: -Quickstart -========== - -.. module:: tablib - - -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 ` section. - -First, make sure that: - -* Tablib is :ref:`installed ` -* Tablib is :ref:`up-to-date ` - - -Lets gets started with some simple use cases and examples. - -Creating a Dataset ------------------- - -A :class:`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 ` object with data. - -.. admonition:: Example Context - - From here on out, if you see ``data``, assume that it's a fresh :class:`Dataset ` object. - - -Adding Rows ------------ - -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')] - - -Adding Headers --------------- - -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 ---------------- - -.. versionadded:: 0.8.3 - -Thanks to Josh Ourisman, Tablib now supports adding dynamic columns. For now, this is only supported on :class:`Dataset` objects that have no defined :class:`headers `. - -Let's save our headers for later. :: - - _headers = list(data.headers) - data.headers = None - -test :: - - import random - - def random_grade(*args): - """Returns a random integer for entry.""" - return (random.randint(60,100)/100.0) - - data.append(col=[random_grade]) - - -:: - >>> data.yaml - - [Reitz, Kenneth, 22, 0.83] - - [Monke, Bessie, 21, 0.73] - -Now we can add our headers back. -:: - >>> data.headers = _headers + ['Random'] - -Let's delete that column. - -:: - >>> del data['Grade'] - - -.. _seperators: - -Seperators ----------- - - - -Transposition -------------- - -Thanks to Luca Beltrame, :class:`Dataset` objects -:: - - data.transpose() - - -Shortcuts ---------- - -Population upon instantiation. - - -Now, go check out the :ref:`API Documentation ` or begin :ref:`Tablib Development `. \ No newline at end of file diff --git a/docs/tutorial.rst b/docs/tutorial.rst new file mode 100644 index 0000000..cfede22 --- /dev/null +++ b/docs/tutorial.rst @@ -0,0 +1,223 @@ +.. _quickstart: + +========== +Quickstart +========== + + +.. module:: tablib + + +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 ` section. + +First, make sure that: + +* Tablib is :ref:`installed ` +* Tablib is :ref:`up-to-date ` + + +Lets gets started with some simple use cases and examples. + + + +------------------ +Creating a Dataset +------------------ + + +A :class:`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 ` object with data. + +.. admonition:: Example Context + + From here on out, if you see ``data``, assume that it's a fresh :class:`Dataset ` object. + + + +----------- +Adding Rows +----------- + + +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')] + + + +-------------- +Adding Headers +-------------- + + +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 + + + +----------------------- +Removing Rows & Columns +----------------------- + +data.insert('MI', ) + +>>> del data['Row Name'] +Fucking easy. + + + +============== +Advanced Usage +============== + +And now for something completely different. + +--------------- +Dynamic Columns +--------------- + +.. versionadded:: 0.8.3 + +Thanks to Josh Ourisman, Tablib now supports adding dynamic columns. A dynamic column is a single callable object (*ie.* a function). +For now, this is only supported on :class:`Dataset` objects that have no defined :class:`headers `. + +So, let's save our headers for later, then remove them. :: + + _headers = list(data.headers) + data.headers = None + + +We can now add a dynamic column to our :class:`Dataset` object. In this example, we have a function that generates a random grade for our students. :: + + import random + + def random_grade(row): + """Returns a random integer for entry.""" + return (random.randint(60,100)/100.0) + + data.append(col=[random_grade]) + + +Now add the headers back, with our new column. :: + + >>> data.headers = _headers + ['Random'] + +Let's have a look at our data. :: + + >>> data.yaml + - {Age: 22, First Name: Kenneth, Grade: 0.6, Last Name: Reitz} + - {Age: 21, First Name: Bessie, Grade: 0.75, Last Name: Monke} + + +Let's remove that column. :: + + >>> del data['Grade'] + + +When you add a dynamic column, the first argument that is passed in to the given callable is the current data row. You can use this to perform calculations against your data row. + +For example, we can use the data available in the row to guess the gender of a student. :: + + def guess_gender(row): + """Calculates gender of given student data row.""" + m_names = ('Kenneth', 'Mike', 'Yuri') + f_names = ('Bessie', 'Samantha', 'Heather') + + name = row[0] + + if name in m_names: + return 'Male' + elif name in f_names: + return 'Female' + else: + return 'Unknown' + +Adding this function to our dataset as a dynamic column would result in: :: + + >>> data.yaml + - {Age: 22, First Name: Kenneth, Gender: Male, Last Name: Reitz} + - {Age: 21, First Name: Bessie, Gender: Female, Last Name: Monke} + + + +.. _seperators: + +---------- +Seperators +---------- +.. versionadded:: 0.8.2 + + +Now, go check out the :ref:`API Documentation ` or begin :ref:`Tablib Development `. \ No newline at end of file -- cgit v1.2.1