README.rst 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169
  1. Tablib: format-agnostic tabular dataset library
  2. ===============================================
  3. .. image:: https://travis-ci.org/kennethreitz/tablib.svg?branch=master
  4. :target: https://travis-ci.org/kennethreitz/tablib
  5. ::
  6. _____ ______ ___________ ______
  7. __ /_______ ____ /_ ___ /___(_)___ /_
  8. _ __/_ __ `/__ __ \__ / __ / __ __ \
  9. / /_ / /_/ / _ /_/ /_ / _ / _ /_/ /
  10. \__/ \__,_/ /_.___/ /_/ /_/ /_.___/
  11. Tablib is a format-agnostic tabular dataset library, written in Python.
  12. Output formats supported:
  13. - Excel (Sets + Books)
  14. - JSON (Sets + Books)
  15. - YAML (Sets + Books)
  16. - Pandas DataFrames (Sets)
  17. - HTML (Sets)
  18. - TSV (Sets)
  19. - OSD (Sets)
  20. - CSV (Sets)
  21. - DBF (Sets)
  22. Note that tablib *purposefully* excludes XML support. It always will. (Note: This is a joke. Pull requests are welcome.)
  23. Overview
  24. --------
  25. `tablib.Dataset()`
  26. A Dataset is a table of tabular data. It may or may not have a header row. They can be build and manipulated as raw Python datatypes (Lists of tuples|dictionaries). Datasets can be imported from JSON, YAML, DBF, and CSV; they can be exported to XLSX, XLS, ODS, JSON, YAML, DBF, CSV, TSV, and HTML.
  27. `tablib.Databook()`
  28. A Databook is a set of Datasets. The most common form of a Databook is an Excel file with multiple spreadsheets. Databooks can be imported from JSON and YAML; they can be exported to XLSX, XLS, ODS, JSON, and YAML.
  29. Usage
  30. -----
  31. Populate fresh data files: ::
  32. headers = ('first_name', 'last_name')
  33. data = [
  34. ('John', 'Adams'),
  35. ('George', 'Washington')
  36. ]
  37. data = tablib.Dataset(*data, headers=headers)
  38. Intelligently add new rows: ::
  39. >>> data.append(('Henry', 'Ford'))
  40. Intelligently add new columns: ::
  41. >>> data.append_col((90, 67, 83), header='age')
  42. Slice rows: ::
  43. >>> print(data[:2])
  44. [('John', 'Adams', 90), ('George', 'Washington', 67)]
  45. Slice columns by header: ::
  46. >>> print(data['first_name'])
  47. ['John', 'George', 'Henry']
  48. Easily delete rows: ::
  49. >>> del data[1]
  50. Exports
  51. -------
  52. Drumroll please...........
  53. JSON!
  54. +++++
  55. ::
  56. >>> print(data.export('json'))
  57. [
  58. {
  59. "last_name": "Adams",
  60. "age": 90,
  61. "first_name": "John"
  62. },
  63. {
  64. "last_name": "Ford",
  65. "age": 83,
  66. "first_name": "Henry"
  67. }
  68. ]
  69. YAML!
  70. +++++
  71. ::
  72. >>> print(data.export('yaml'))
  73. - {age: 90, first_name: John, last_name: Adams}
  74. - {age: 83, first_name: Henry, last_name: Ford}
  75. CSV...
  76. ++++++
  77. ::
  78. >>> print(data.export('csv'))
  79. first_name,last_name,age
  80. John,Adams,90
  81. Henry,Ford,83
  82. EXCEL!
  83. ++++++
  84. ::
  85. >>> with open('people.xls', 'wb') as f:
  86. ... f.write(data.export('xls'))
  87. DBF!
  88. ++++
  89. ::
  90. >>> with open('people.dbf', 'wb') as f:
  91. ... f.write(data.export('dbf'))
  92. Pandas DataFrame!
  93. +++++++++++++++++
  94. ::
  95. >>> print(data.export('df')):
  96. first_name last_name age
  97. 0 John Adams 90
  98. 1 Henry Ford 83
  99. It's that easy.
  100. Installation
  101. ------------
  102. To install tablib, simply: ::
  103. $ pip install tablib
  104. Make sure to check out `Tablib on PyPi <https://pypi.python.org/pypi/tablib/>`_!
  105. Contribute
  106. ----------
  107. If you'd like to contribute, simply fork `the repository`_, commit your
  108. changes to the **develop** branch (or branch off of it), and send a pull
  109. request. Make sure you add yourself to AUTHORS_.
  110. .. _`the repository`: http://github.com/kennethreitz/tablib
  111. .. _AUTHORS: http://github.com/kennethreitz/tablib/blob/master/AUTHORS