Merge pull request #66 from tableau/development

Releasing 0.2 to master

Author: Russell Hay

.gitignore

@@ -63,3 +63,4 @@ target/
 
 #Other things
 .DS_Store
+.idea

.travis.yml

@@ -12,10 +12,11 @@ install:
 # command to run tests
 script:
   # Tests
-  - python test.py
+  - python setup.py test
   # pep8
-  - pep8 --ignore=E501 .
+  - pep8 .
   # Examples
   - (cd "Examples/Replicate Workbook" && python replicateWorkbook.py)
   - (cd "Examples/List TDS Info" && python listTDSInfo.py)
+  - (cd "Examples/GetFields" && python show_fields.py)
 

CHANGELOG.md

@@ -0,0 +1,11 @@
+## 0.2 (22 July 2016)
+
+* Added support for loading twbx and tdsx files (#43, #44)
+* Added Fields property to datasource (#45)
+* Added Example for using the Fields Property (#51)
+* Added Ability to get fields used by a specific sheet (#54)
+* Code clean up and test reorganization
+
+## 0.1 (29 June 2016)
+
+* Initial Release to the world

Examples/GetFields/World.tds

@@ -0,0 +1 @@
+../List TDS Info/World.tds

Examples/GetFields/show_fields.py

@@ -0,0 +1,29 @@
+############################################################
+# Step 1)  Use Datasource object from the Document API
+############################################################
+from tableaudocumentapi import Datasource
+
+############################################################
+# Step 2)  Open the .tds we want to inspect
+############################################################
+sourceTDS = Datasource.from_file('World.tds')
+
+############################################################
+# Step 3)  Print out all of the fields and what type they are
+############################################################
+print('----------------------------------------------------------')
+print('--- {} total fields in this datasource'.format(len(sourceTDS.fields)))
+print('----------------------------------------------------------')
+for count, field in enumerate(sourceTDS.fields.values()):
+    print('{:>4}: {} is a {}'.format(count+1, field.name, field.datatype))
+    blank_line = False
+    if field.calculation:
+        print('      the formula is {}'.format(field.calculation))
+        blank_line = True
+    if field.default_aggregation:
+        print('      the default aggregation is {}'.format(field.default_aggregation))
+        blank_line = True
+
+    if blank_line:
+        print('')
+print('----------------------------------------------------------')

README.md

@@ -6,15 +6,26 @@ This repo contains Python source and example files for the Tableau Document API.
 
 Document API
 ---------------
-The Document API provides a supported way to programmatically make updates to Tableau workbook (`.twb`) and datasource (`.tds`) files. If you've been making changes to these file types by directly updating the XML--that is, by XML hacking--this SDK is for you :)
-
-Currently only the following operations are supported:
-
-- Modify database server
-- Modify database name
-- Modify database user
-
-We don't yet support creating files from scratch. In addition, support for `.twbx` and `.tdsx` files is coming.
+The Document API provides a supported way to programmatically make updates to Tableau workbook and data source files. If you've been making changes to these file types by directly updating the XML--that is, by XML hacking--this SDK is for you :)
+
+Features include:
+- Support for 9.X, and 10.X workbook and data source files
+  - Including TDSX and TWBX files
+- Getting connection information from data sources and workbooks
+  - Server Name
+  - Username
+  - Database Name
+  - Authentication Type
+  - Connection Type
+- Updating connection information in workbooks and data sources
+  - Server Name
+  - Username
+  - Database Name
+- Getting Field information from data sources and workbooks
+  - Get all fields in a data source
+  - Get all feilds in use by certain sheets in a workbook
+
+We don't yet support creating files from scratch, adding extracts into workbooks or data sources, or updating field information
 
 
 ###Getting Started
@@ -34,8 +45,19 @@ Download the `.zip` file that contains the SDK. Unzip the file and then run the
 pip install -e <directory containing setup.py>
 ```
 
-We plan on putting the package in PyPi to make installation easier.
+#### Installing the Development Version From Git
+
+*Only do this if you know you want the development version, no guarantee that we won't break APIs during development*
+
+```text
+pip install git+https://github.com/tableau/document-api-python.git@development
+```
+
+If you go this route, but want to switch back to the non-development version, you need to run the following command before installing the stable version:
 
+```text
+pip uninstall tableaudocumentapi
+```
 
 ###Basics
 The following example shows the basic syntax for using the Document API to update a workbook:
@@ -52,7 +74,7 @@ sourceWB.datasources[0].connections[0].username = "benl"
 sourceWB.save()
 ```
 
-With Data Integration in Tableau 10, a datasource can have multiple connections. To access the connections simply index them like you would datasources
+With Data Integration in Tableau 10, a data source can have multiple connections. To access the connections simply index them like you would datasources
 
 ```python
 from tableaudocumentapi import Workbook
@@ -75,13 +97,13 @@ sourceWB.save()
 **Notes**
 
 - Import the `Workbook` object from the `tableaudocumentapi` module.
-- To open a workbook, instantiate a `Workbook` object and pass the `.twb` file name in the constructor.
-- The `Workbook` object exposes a `datasources` collection.
-- Each datasource object has a `connection` object that supports a `server`, `dbname`, and `username` property.
+- To open a workbook, instantiate a `Workbook` object and pass the file name as the first argument.
+- The `Workbook` object exposes a list of `datasources` in the workbook
+- Each data source object has a `connection` object that supports a `server`, `dbname`, and `username` property.
 - Save changes to the workbook by calling the `save` or `save_as` method.
 
 
 
 ###Examples
 
-The downloadable package contains an example named `replicateWorkbook.py` (in the folder `\Examples\Replicate Workbook`). This example reads an existing workbook and reads a .csv file that contains a list of servers, database names, and users. For each new user in the .csv file, the code copies the original workbook, updates the `server`, `dbname`, and `username` properties, and saves the workbook under a new name.
+The downloadable package contains several example scripts that show more detailed usage of the Document API

contributing.md

@@ -0,0 +1,33 @@
+# Contributing
+
+We welcome contributions to this project!
+
+Contribution can include, but are not limited to, any of the following:
+
+* File an Issue
+* Request a Feature
+* Implement a Requested Feature
+* Fix an Issue/Bug
+* Add/Fix documentation
+
+Contributions must follow the guidelines outlined on the [Tableau Organization](http://tableau.github.io/) page, though filing an issue or requesting
+a feature do not require the CLA.
+
+## Issues and Feature Requests
+
+To submit an issue/bug report, or to request a feature, please submit a [github issue](https://github.com/tableau/document-api-python/issues) to the repo.
+
+If you are submiting a bug report, please provide as much information as you can, including clear and concise repro steps, attaching any necessary
+files to assist in the repro.  **Be sure to scrub the files of any potentially sensitive information.  Issues are public.**
+
+For a feature request, please try to describe the scenario you are trying to accomplish that requires the feature.  This will help us understand
+the limitations that you are running into, and provide us with a use case to know if we've satisfied your request.
+
+## Fixes, Implementations, and Documentation
+
+For all other things, please submit a PR that includes the fix, documentation, or new code that you are trying to contribute.  More information on
+creating a PR can be found in the [github documentation](https://help.github.com/articles/creating-a-pull-request/)
+
+If the feature is complex or has multiple solutions that could be equally appropriate approaches, it would be helpful to file an issue to discuss the
+design trade-offs of each solution before implementing, to allow us to collectively arrive at the best solution, which most likely exists in the middle
+somewhere.

publish.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -e
+
+rm -rf dist
+python setup.py sdist
+python setup.py bdist_wheel
+python3 setup.py bdist_wheel
+twine upload dist/*

setup.cfg

@@ -0,0 +1,10 @@
+[wheel]
+universal = 1
+
+[pycodestyle]
+select = 
+max_line_length = 120
+
+[pep8]
+max_line_length = 120
+

setup.py

@@ -5,11 +5,12 @@
 
 setup(
     name='tableaudocumentapi',
-    version='0.0.1',
+    version='0.2',
     author='Tableau Software',
     author_email='[email protected]',
     url='https://github.com/tableau/document-api-python',
     packages=['tableaudocumentapi'],
     license='MIT',
-    description='A Python module for working with Tableau files.'
+    description='A Python module for working with Tableau files.',
+    test_suite='test'
 )