diff --git a/docs/index.rst b/docs/index.rst index 87a8d3b..4a4de40 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,8 +6,6 @@ Tablib: Pythonic Tabular Data ============================= -Welcome to Tablib's documentation. - .. Contents: .. .. .. toctree:: @@ -22,7 +20,7 @@ Welcome to Tablib's documentation. .. * :ref:`search` -Tablib is a format-agnostic tabular dataset library, written in Python. It allows you to import, export, and manipulate tabular data sets. Oh, and it's :ref:`MIT Lisenced `. +Tablib is an :ref:`MIT Lisenced ` format-agnostic tabular dataset library, written in Python. It allows you to import, export, and manipulate tabular data sets. Advanced features include, segregation, dynamic columns, tags & filtering, and seamless format import & exmport. I recommend you start with :ref:`Installation `. diff --git a/docs/intro.rst b/docs/intro.rst index 616b3e1..a327d28 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -4,17 +4,7 @@ Introduction ============ 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. - - -Inception ---------- - -Tablib was build by `Kenneth Reitz`_ to fufill a specfic need. - -Tablib was born. - -.. _`Kenneth Reitz`: http://kennethreitz.com +Tablib is a format-agnostic tabular dataset library, written in Python. It allows you to Pythonically import, export, and manipulate tabular data sets. Advanced features include, segregation, dynamic columns, tags / filtering, and seamless format import/exmport. Philosphy @@ -29,10 +19,7 @@ Tablib was developed with a few :pep:`20` idioms in mind. #. Complex is better than complicated. #. Readability counts. -Besides, Why not? - -:ref:`seperators` - +All contributions to Tablib should keep these important rules in mind. .. _mit: diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 0aa0f80..774158d 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -158,7 +158,7 @@ Let's find the average age. :: Removing Rows & Columns ----------------------- -:: +It's easier than you could imagine. :: >>> del data['Col Name'] @@ -166,9 +166,6 @@ Removing Rows & Columns >>> del data[0:12] -Fucking easy. - - ============== Advanced Usage @@ -180,6 +177,8 @@ This part of the documentation services to give you an idea that are otherwise h And now for something completely different. +.. _dyncols: + --------------- Dynamic Columns --------------- @@ -187,15 +186,8 @@ 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. :: +Let's 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 @@ -203,12 +195,7 @@ We can now add a dynamic column to our :class:`Dataset` object. In this example, """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 + ['Grade'] + data.append(col=[random_grade], header='Grade') Let's have a look at our data. :: @@ -247,19 +234,48 @@ Adding this function to our dataset as a dynamic column would result in: :: - {Age: 20, First Name: Bessie, Gender: Female, Last Name: Monke} +.. _tags: +---------------------------- +Filtering Datasets with Tags +---------------------------- + +.. versionadded:: 0.9.0 + + +When constructing a :class:`Dataset` object, you can add tags to rows by speficying the ``tags`` parameter. +This allows you to filter your :class:`Dataset` later. This can be useful so seperate rows of data based on +arbitrary criteria (*e.g.* origin) that you don't want to include in your :class:`Dataset`. + +Let's tag some students. :: + + students = tablib.Dataset() + + students.headers = ['first', 'last'] + + students.append(['Kenneth', 'Reitz'], tags=['male', 'technical']) + students.append(['Bessie', 'Monke'], tags=['female', 'creative']) + +Now that we have extra meta-data on our rows, we can use easily filter our :class:`Dataset`. Let's just see Male students. :: + + + >>> data.filter(['male']).yaml + - {first: Kenneth, Last: Reitz} + +It's that simple. The original :class:`Dataset` is untouched. Excel Workbook With Multiple Sheets ------------------------------------ -:class:`Databook` +When dealine with a large number of :class:`Datasets ` in spreadsheet format, it's quite common to group mulitple spreadsheets into a single Excel file, known as a Workbook. Tablib makes it extremely easy to build webooks with the handy, :class:`Databook` class. + -:: +Let's say we have 3 different :class:`Datasets `. All we have to do is add then to a :class:`Databook` object... :: - book = tablib.Databook([data, data, data]) + book = tablib.Databook([data1, data2, data3]) -:: +... and export to Excel just like :class:`Datasets `. :: with open('students.xls', 'wb') as f: f.write(book.xls)