README.rst 3.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151
  1. Tablib: format-agnostic tabular dataset library
  2. ===============================================
  3. .. image:: https://travis-ci.org/kennethreitz/tablib.svg?branch=develop
  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. - HTML (Sets)
  17. - TSV (Sets)
  18. - CSV (Sets)
  19. Note that tablib *purposefully* excludes XML support. It always will. (Note: This is a joke. Pull requests are welcome.)
  20. Overview
  21. --------
  22. `tablib.Dataset()`
  23. 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, and CSV; they can be exported to XLSX, XLS, ODS, JSON, YAML, CSV, TSV, and HTML.
  24. `tablib.Databook()`
  25. 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.
  26. Usage
  27. -----
  28. Populate fresh data files: ::
  29. headers = ('first_name', 'last_name')
  30. data = [
  31. ('John', 'Adams'),
  32. ('George', 'Washington')
  33. ]
  34. data = tablib.Dataset(*data, headers=headers)
  35. Intelligently add new rows: ::
  36. >>> data.append(('Henry', 'Ford'))
  37. Intelligently add new columns: ::
  38. >>> data.append_col((90, 67, 83), header='age')
  39. Slice rows: ::
  40. >>> print data[:2]
  41. [('John', 'Adams', 90), ('George', 'Washington', 67)]
  42. Slice columns by header: ::
  43. >>> print data['first_name']
  44. ['John', 'George', 'Henry']
  45. Easily delete rows: ::
  46. >>> del data[1]
  47. Exports
  48. -------
  49. Drumroll please...........
  50. JSON!
  51. +++++
  52. ::
  53. >>> print data.json
  54. [
  55. {
  56. "last_name": "Adams",
  57. "age": 90,
  58. "first_name": "John"
  59. },
  60. {
  61. "last_name": "Ford",
  62. "age": 83,
  63. "first_name": "Henry"
  64. }
  65. ]
  66. YAML!
  67. +++++
  68. ::
  69. >>> print data.yaml
  70. - {age: 90, first_name: John, last_name: Adams}
  71. - {age: 83, first_name: Henry, last_name: Ford}
  72. CSV...
  73. ++++++
  74. ::
  75. >>> print data.csv
  76. first_name,last_name,age
  77. John,Adams,90
  78. Henry,Ford,83
  79. EXCEL!
  80. ++++++
  81. ::
  82. >>> with open('people.xls', 'wb') as f:
  83. ... f.write(data.xls)
  84. It's that easy.
  85. Installation
  86. ------------
  87. To install tablib, simply: ::
  88. $ pip install tablib
  89. Or, if you absolutely must: ::
  90. $ easy_install tablib
  91. Contribute
  92. ----------
  93. If you'd like to contribute, simply fork `the repository`_, commit your
  94. changes to the **develop** branch (or branch off of it), and send a pull
  95. request. Make sure you add yourself to AUTHORS_.
  96. .. _`the repository`: http://github.com/kennethreitz/tablib
  97. .. _AUTHORS: http://github.com/kennethreitz/tablib/blob/master/AUTHORS