From 169984c1c3ee6fdabeae00a4c6fef0325057818e Mon Sep 17 00:00:00 2001 From: ogolovatyi Date: Thu, 21 Feb 2019 17:44:09 -0800 Subject: [PATCH 1/3] Add markdownlint step --- .travis.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.travis.yml b/.travis.yml index c5dc9e6d..6fcca821 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,8 +7,10 @@ install: - pip install pytest - pip install pytest-cov - pip install coveralls + - npm install -g markdownlint-cli script: - pytest tabpy-server/server_tests/ --cov=tabpy-server/tabpy_server - pytest tabpy-tools/client_tests/ --cov=tabpy-tools/tabpy_tools --cov-append + - markdownlint . after_success: - coveralls From 6b943e535eab463be9f6c966bb149aa6451cd44c Mon Sep 17 00:00:00 2001 From: ogolovatyi Date: Thu, 21 Feb 2019 17:48:30 -0800 Subject: [PATCH 2/3] Fix .travis.yml --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 6fcca821..9b1fd4f6 100644 --- a/.travis.yml +++ b/.travis.yml @@ -10,7 +10,7 @@ install: - npm install -g markdownlint-cli script: - pytest tabpy-server/server_tests/ --cov=tabpy-server/tabpy_server - - pytest tabpy-tools/client_tests/ --cov=tabpy-tools/tabpy_tools --cov-append + - pytest tabpy-tools/tools_tests/ --cov=tabpy-tools/tabpy_tools --cov-append - markdownlint . after_success: - coveralls From c2acbf39916adfeace25a8610c5927a4421e7b15 Mon Sep 17 00:00:00 2001 From: ogolovatyi Date: Thu, 21 Feb 2019 18:38:59 -0800 Subject: [PATCH 3/3] Fix markdownlint warnings --- CONTRIBUTING.md | 15 +++-- README.md | 12 +++- docs/TableauConfiguration.md | 112 +++++++++++++++++++++++----------- docs/about.md | 6 +- docs/security.md | 3 +- docs/server-config.md | 25 +++++--- docs/server-configurations.md | 22 ++++--- docs/server-download.md | 17 +++--- docs/server-rest.md | 65 +++++++++++++------- docs/server-startup.md | 84 ++++++++++++++----------- docs/tabpy-tools.md | 22 ++++--- 11 files changed, 248 insertions(+), 135 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11ffc7c7..bcb34fb7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,14 +59,17 @@ python tests\runtests.py If you have downloaded Tabpy and would like to manually install Tabpy Server not using pip then follow the steps below [to run TabPy in Python virtual environment](docs/tabpy-virtualenv.md). - ## Documentation Updates For any process, scripts or API changes documentation needs to be updated accordingly. Please use markdown validation tools like web-based[markdownlint](https://dlaa.me/markdownlint/) or npm [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli). -TOC for markdown file is built with [markdonw-toc](https://www.npmjs.com/package/markdown-toc). +TOC for markdown file is built with [markdonw-toc](https://www.npmjs.com/package/markdown-toc): + +```sh +markdownlint -i docs/server-startup.md +``` ## TabPy with Swagger @@ -83,7 +86,7 @@ Access-Control-Allow-Methods = GET, OPTIONS, POST ``` - Start local instance of TabPy server following [TabPy Server Startup Guide](docs/server-startup.md). -- Run local copy of Swagger editor with steps provided at +- Run local copy of Swagger editor with steps provided at [https://github.com/swagger-api/swagger-editor](https://github.com/swagger-api/swagger-editor). - Open `misc/TabPy.yml` in Swagger editor. - In case your TabPy server runs not on `localhost:9004` update @@ -91,9 +94,9 @@ Access-Control-Allow-Methods = GET, OPTIONS, POST ## Code styling -On github repo for merge request `pycodestyle` is used to check Python code against our -style conventions. You can run install it and run locally for file where modifications -were made: +On github repo for merge request `pycodestyle` is used to check Python code +against our style conventions. You can run install it and run locally for +file where modifications were made: ```sh pip install pycodestyle diff --git a/README.md b/README.md index 56b9445f..a134533c 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,16 @@ # TabPy + [![Community Supported](https://img.shields.io/badge/Support%20Level-Community%20Supported-457387.svg)](https://www.tableau.com/support-levels-it-and-developer-tools) [![Build Status](https://travis-ci.com/tableau/TabPy.svg?branch=master)](https://travis-ci.com/tableau/TabPy) [![Coverage Status](https://coveralls.io/repos/github/tableau/TabPy/badge.svg)](https://coveralls.io/github/tableau/TabPy) [![Python 3.6](https://img.shields.io/badge/python-3.6-blue.svg)](https://www.python.org/downloads/release/python-360/) -TabPy (Tableau Python Server) is external server implementation which allows expanding Tableau with executing Python scripts on table calculation. +TabPy (Tableau Python Server) is external server implementation which allows +expanding Tableau with executing Python scripts on table calculation. -All documentation is in the [docs](docs) folder. Consider reading it the next order: +All documentation is in the [docs](docs) folder. Consider reading it the next +order: * [About TabPy](docs/about.md) * [TabPy Server Download Instructions](docs/server-download.md) @@ -26,7 +29,10 @@ More technical topics: Other useful resources: -* For all questions not related to the TabPy code (installation, deployment, connections, Python issues, etc.) and requests use the [External Services Forum](https://community.tableau.com/community/forums/externalservices) on [Tableau Community](https://community.tableau.com). +* For all questions not related to the TabPy code (installation, deployment, + connections, Python issues, etc.) and requests use the + [External Services Forum](https://community.tableau.com/community/forums/externalservices) + on [Tableau Community](https://community.tableau.com). * [Building advanced analytics applications with TabPy](https://www.tableau.com/about/blog/2017/1/building-advanced-analytics-applications-tabpy-64916) * [Building Data Science Applications with TabPy Video Tutorial](https://youtu.be/nRtOMTnBz_Y) * [TabPy Tutorial on TabWiki](https://community.tableau.com/docs/DOC-10856) diff --git a/docs/TableauConfiguration.md b/docs/TableauConfiguration.md index 11643d9f..b3daade4 100755 --- a/docs/TableauConfiguration.md +++ b/docs/TableauConfiguration.md @@ -1,5 +1,6 @@ # Using Python in Tableau Calculations + - [Configuration](#configuration) @@ -10,101 +11,141 @@ - [Using Deployed Functions](#using-deployed-functions) + ## Configuration -Once you have a [TabPy instance](server-startup.md) set up you can easily configure Tableau to use this service for evaluating Python code. +Once you have a [TabPy instance](server-startup.md) set up you can easily +configure Tableau to use this service for evaluating Python code. ### Tableau Desktop In Tableau Desktop version 10.1 or later: 1. Go to Help->Settings and Performance->Manage External Service Connection... -2. Enter the Server (localhost if running TabPy on the same computer) and the Port (default is 9004). +2. Enter the Server (localhost if running TabPy on the same computer) and the + Port (default is 9004). ![Screenshot of Configuration on Tableau Desktop](img/external-service-configuration.png) ### Tableau Server 2018.2 and Newer Versions -To configure Tableau Server 2018.2 and newer versions to connect to TabPy server +To configure Tableau Server 2018.2 and newer versions to connect to TabPy server use [TSM command line tool](https://onlinehelp.tableau.com/current/server/en-us/tsm.htm). -To configure a non secure connection to TabPy server set `vizqlserver.extsvc.host` and `vizqlserver.extsvc.port` -parameters: +To configure a non secure connection to TabPy server set `vizqlserver.extsvc.host` +and `vizqlserver.extsvc.port` parameters: ```sh tsm set vizqlserver.extsvc.host tsm set vizqlserver.extsvc.port ``` -To configure a secure connection to TabPy server use `tsm security vizql-extsvc enable` command -as described at [TSM Security documentation page](https://onlinehelp.tableau.com/current/server/en-us/cli_security_tsm.htm#tsm_security_vizql-extsvc-ssl-enable). +To configure a secure connection to TabPy server use `tsm security vizql-extsvc enable` +command as described at +[TSM Security documentation page](https://onlinehelp.tableau.com/current/server/en-us/cli_security_tsm.htm#tsm_security_vizql-extsvc-ssl-enable). + + ```sh tsm security vizql-extsvc-ssl enable --connection-type --extsvc-host --extsvc-port [options] [global options] ``` -For how to configure a secure TabPy instance follow instructions at -[TabPy Server Config documentation](server-config.md). + +For how to configure a secure TabPy instance follow instructions at +[TabPy Server Config documentation](server-config.md). ### Tableau Server 2018.1 and Older Versions -For Tableau workbooks with embedded Python code to work on Tableau Server 10.1 or later, you need to go -through a similar setup but using the [tabadmin](https://onlinehelp.tableau.com/current/server/en-us/tabadmin.htm) -command line utility. -The two server settings that need to be configured are `vizqlserver.extsvc.host` and `vizqlserver.extsvc.port`. +For Tableau workbooks with embedded Python code to work on Tableau Server 10.1 +or later, you need to go through a similar setup but using the +[tabadmin](https://onlinehelp.tableau.com/current/server/en-us/tabadmin.htm) +command line utility. The two server settings that need to be configured are +`vizqlserver.extsvc.host` and `vizqlserver.extsvc.port`. ```sh tabadmin stop -tabadmin set vizqlserver.extsvc.host +tabadmin set vizqlserver.extsvc.host tabadmin set vizqlserver.extsvc.port tabadmin configure tabadmin start ``` -Note that you cannot use TabPy secure connection with 2018.1 and older versions of Tableau. +Note that you cannot use TabPy secure connection with 2018.1 and older versions +of Tableau. -Note that it is not necessary to install TabPy on the Tableau Server or Desktop computer-all -that is required is a pointer to a TabPy server instance. +Note that it is not necessary to install TabPy on the Tableau Server or Desktop +computer-all that is required is a pointer to a TabPy server instance. -Once you're done with configuration, you can use Python in calculated fields in Tableau. +Once you're done with configuration, you can use Python in calculated fields in +Tableau. ## Anatomy of a Python Calculation -Tableau can pass code to TabPy through four different functions: SCRIPT_INT, SCRIPT_REAL, SCRIPT_STR and SCRIPT_BOOL to accommodate the different return types. -In the example below you can see a simple function that passes a column of book names (highlighted in blue) to Python for proper casing. Since Python returns an array of string, SCRIPT_STR function is used. +Tableau can pass code to TabPy through four different functions: SCRIPT_INT, +SCRIPT_REAL, SCRIPT_STR and SCRIPT_BOOL to accommodate the different return +types. In the example below you can see a simple function that passes a column +of book names (highlighted in blue) to Python for proper casing. Since Python +returns an array of string, SCRIPT_STR function is used. + ![A simple example of a Python calculated field in Tableau Desktop](img/Example1-SimpleFunctionCall.png) -For a SCRIPT call to Python to be successful, it needs to return a result explicitly specified with the `return` keyword (highlighted in red). -In this simple example, there is only one input but you can pass as many arguments to SCRIPT functions as you like. Tableau takes the arguments in the order provided and replaces the _argN placeholders accordingly. In this case ATTR([Book Name]) maps to _arg1 and both are highlighted to indicate the association. +For a SCRIPT call to Python to be successful, it needs to return a result +explicitly specified with the `return` keyword (highlighted in red). + +In this simple example, there is only one input but you can pass as many +arguments to SCRIPT functions as you like. Tableau takes the arguments in the +order provided and replaces the _argN placeholders accordingly. In this case +ATTR([Book Name]) maps to _arg1 and both are highlighted to indicate the +association. -Tableau expects the SCRIPT to return a single column that has either a single row or the same number of rows as it passed to TabPy. The example above sends 18 rows of data to TabPy and receives 18 rows back. +Tableau expects the SCRIPT to return a single column that has either a single +row or the same number of rows as it passed to TabPy. The example above sends +18 rows of data to TabPy and receives 18 rows back. -In the example below Tableau passes multiple columns to TabPy and gets a single value (correlation coefficient) back. SUM(Sales) and SUM(Profit) are used as argument 1 and 2 respectively and highlighted in matching colors. -In this case the function `corrcoef` returns a matrix from which the correlation coefficient is extracted such that a single column is returned. +In the example below Tableau passes multiple columns to TabPy and gets a single +value (correlation coefficient) back. SUM(Sales) and SUM(Profit) are used as +argument 1 and 2 respectively and highlighted in matching colors. +In this case the function `corrcoef` returns a matrix from which the correlation +coefficient is extracted such that a single column is returned. ![Using Partitioning settings with calculations](img/Example2-MultipleFunctionCalls.png) -Tableau aggregates the data before sending to TabPy using the level of detail of the view. In this particular example each point in the scatter plot is a Customer and TabPy is receiving SUM(Sales) and SUM(Profit) for each Customer. +Tableau aggregates the data before sending to TabPy using the level of detail +of the view. In this particular example each point in the scatter plot is a +Customer and TabPy is receiving SUM(Sales) and SUM(Profit) for each Customer. -If you would like to run your Python code on disaggregate data, you can achieve this simply by unchecking the Aggregate Measures option under the Analysis menu. +If you would like to run your Python code on disaggregate data, you can achieve +this simply by unchecking the Aggregate Measures option under the Analysis menu. -The example above showcases another capability that can come in handy if you like to run the same Python script multiple times in different contexts. In this particular example, unchecking the Category and Segment boxes in the Table Calculation dialog results in Tableau making multiple calls to TabPy, once per each pane in the visualization. +The example above showcases another capability that can come in handy if you +like to run the same Python script multiple times in different contexts. In this +particular example, unchecking the Category and Segment boxes in the Table +Calculation dialog results in Tableau making multiple calls to TabPy, once per +each pane in the visualization. Running regression analysis independently for each Segment-Category combination. -In all of these examples the data structure being returned by the function can be consumed by Tableau. This may not always be the case. If your Python code returns a one dimensional array but TabPy is failing to serialize it to JSON, you may want to convert it to a list as shown in the example below. +In all of these examples the data structure being returned by the function can +be consumed by Tableau. This may not always be the case. If your Python code +returns a one dimensional array but TabPy is failing to serialize it to JSON, +you may want to convert it to a list as shown in the example below. ![Converting to list to make the results JSON serializable](img/python-calculated-field.png) -You can find two detailed working examples with downloadable sample Tableau workbooks on [our blog](https://www.tableau.com/about/blog/2017/1/building-advanced-analytics-applications-tabpy-64916). +You can find two detailed working examples with downloadable sample Tableau +workbooks on [our blog](https://www.tableau.com/about/blog/2017/1/building-advanced-analytics-applications-tabpy-64916). ## Using Deployed Functions -[TabPy Tools documentation](tabpy-tools.md) covers in detail how functions could be deployed as endpoints. -You can invoke such endpoints using `tabpy.query` option by specifying the endpoint name and arguments and retrieving the `response` object. +[TabPy Tools documentation](tabpy-tools.md) covers in detail how functions +could be deployed as endpoints. +You can invoke such endpoints using `tabpy.query` option by specifying the +endpoint name and arguments and retrieving the `response` object. -A SCRIPT calculated field in Tableau using the [add endpoint](tabpy-tools.md#deploying-a-function) defined in [TabPy Tools documentation](tabpy-tools.md) could look like the following: +A SCRIPT calculated field in Tableau using the +[add endpoint](tabpy-tools.md#deploying-a-function) defined in +[TabPy Tools documentation](tabpy-tools.md) could look like the following: ```sh SCRIPT_REAL(" @@ -112,4 +153,7 @@ return tabpy.query('add',_arg1,_arg2)['response']", -SUM([Discount]),SUM([Price])) ``` -You can find a detailed working example with a downloadable sample Tableau workbook showing how to publish models and use the published models in calculated fields on [our blog](https://www.tableau.com/about/blog/2017/1/building-advanced-analytics-applications-tabpy-64916). +You can find a detailed working example with a downloadable sample Tableau +workbook showing how to publish models and use the published models in +calculated fields on +[our blog](https://www.tableau.com/about/blog/2017/1/building-advanced-analytics-applications-tabpy-64916). diff --git a/docs/about.md b/docs/about.md index a41a1a3f..5ac71f1d 100755 --- a/docs/about.md +++ b/docs/about.md @@ -4,8 +4,8 @@ TabPy framework allows Tableau to remotely execute Python code. It has two compo 1. A process built on Tornado, which allows for the remote execution of Python code through a set of [REST APIs](server-rest.md). The code can either be immediately - executed or persisted in the server process and exposed as a REST endpoint, to be - called later. + executed or persisted in the server process and exposed as a REST endpoint, + to be called later. 2. A [tools library](tabpy-tools.md) that enables the deployment of such endpoints, based on Python functions. @@ -14,5 +14,5 @@ Tableau can connect to the TabPy server to execute Python code on the fly and display results in Tableau visualizations. Users can control data and parameters being sent to TabPy by interacting with their Tableau worksheets, dashboard or stories. -For how to configure Tableau to connect to TabPy server follow steps in +For how to configure Tableau to connect to TabPy server follow steps in [Tableau Configuration Document](TableauConfiguration.md). diff --git a/docs/security.md b/docs/security.md index 33206948..31c5bef7 100755 --- a/docs/security.md +++ b/docs/security.md @@ -3,7 +3,8 @@ The following security issues should be kept in mind as you use TabPy with Tableau: - TabPy currently does not use authentication. -- Python scripts can contain code which can harm security on the server where the TabPy is running. For example: +- Python scripts can contain code which can harm security on the server where + the TabPy is running. For example: - Access file system (read/write) - Install new Python packages which can contain binary code - Execute operating system commands diff --git a/docs/server-config.md b/docs/server-config.md index ef64ce96..bf9e6f86 100755 --- a/docs/server-config.md +++ b/docs/server-config.md @@ -1,32 +1,43 @@ # TabPy Server Configuration Instructions -Default settings for TabPy may be viewed in the tabpy_server/common/default.conf file. This file also contains a commented example of how to set up your TabPy server to only serve HTTPS traffic. +Default settings for TabPy may be viewed in the +tabpy_server/common/default.conf file. This file also contains a +commented example of how to set up your TabPy server to only +serve HTTPS traffic. Change settings by: 1. Adding environment variables: - - set the environment variable as required by your Operating System. When creating environment variables, use the same name as is in the config file as an environment variable. The files startup.sh and startup.cmd in the root of the install folder have examples of how to set environment variables in both Linux and Windows respectively. Set any desired environment variables and then start the application. + - set the environment variable as required by your Operating System. When + creating environment variables, use the same name as is in the config file + as an environment variable. The files startup.sh and startup.cmd in the root + of the install folder have examples of how to set environment variables in + both Linux and Windows respectively. Set any desired environment variables + and then start the application. 2. Modifying default.conf. 3. Specifying your own config file as a command line parameter. - i.e. Running the command: ```python tabpy.py --config=path\to\my\config``` -The default config file is provided to show you the default values but does not need to be present to run TabPy. +The default config file is provided to show you the default values but does not +need to be present to run TabPy. ## Configuring HTTP vs HTTPS -By default, TabPy serves only HTTP requests. TabPy can be configured to serve only HTTPS requests by setting the following parameter in the config file: +By default, TabPy serves only HTTP requests. TabPy can be configured to serve +only HTTPS requests by setting the following parameter in the config file: ```sh TABPY_TRANSFER_PROTOCOL = https ``` -If HTTPS is selected, the absolute paths to the cert and key file need to be specified in your config file using the following parameters: +If HTTPS is selected, the absolute paths to the cert and key file need to be +specified in your config file using the following parameters: ```sh TABPY_CERTIFICATE_FILE = C:/path/to/cert/file.crt TABPY_KEY_FILE = C:/path/to/key/file.key ``` -Note that only PEM-encoded x509 certificates are supported for the secure connection scenario. - +Note that only PEM-encoded x509 certificates are supported for the secure +connection scenario. diff --git a/docs/server-configurations.md b/docs/server-configurations.md index 39a70bdc..82d083b6 100644 --- a/docs/server-configurations.md +++ b/docs/server-configurations.md @@ -1,10 +1,18 @@ # Supported TabPy Server Configurations -The following table lists environment configurations that have been validated to support hosting TabPy instances. -To download specific release of TabPy find it on [TabPy releases](https://github.com/tableau/TabPy/releases/) page. +The following table lists environment configurations that have been +validated to support hosting TabPy instances. +To download specific release of TabPy find it on +[TabPy releases](https://github.com/tableau/TabPy/releases/) page. - TabPy Version |Python | Operating System | Owner |When confirmed to work | Comments ---------------- |------- |------------------- |---------- |----------------------- |---------- -0.3.2 | 3.6.5 | Windows 10 | @tableau | 2019-01-29 | Win 10 x64, Python 3.5.6 x64 -0.3.2 | 3.6.5 | centOS 7.6-1810 | @tableau | 2019-01-30 | There are known issues with `pip` on CentOS, carefully read [Starting TabPy Server](server-startup.md) instructions for CentOS specific steps. -0.3.2 | 3.6.5 | macOS Sierra | @tableau | 2019-01-29 | \ No newline at end of file + TabPy release | Python | Operating System | Owner | When confirmed to work | Comments +-------------- |------- |----------------- |------ |----------------------- |---------- +0.3.2 | 3.6.5 | Windows 10 | @tableau | 2019-01-29 | Win 10 x64, Python 3.5.6 x64 +0.3.2 | 3.6.5 | centOS 7.6-1810 | @tableau | 2019-01-30 | There are known + issues with `pip` + on CentOS, carefully + read [Starting TabPy Server](server-startup.md) + instructions for + CentOS specific + steps. +0.3.2 | 3.6.5 | macOS Sierra | @tableau | 2019-01-29 | \ No newline at end of file diff --git a/docs/server-download.md b/docs/server-download.md index cec74c57..69e06478 100755 --- a/docs/server-download.md +++ b/docs/server-download.md @@ -1,10 +1,13 @@ # TabPy Server Download -TabPy server can be downloaded from [TabPy github releases page](https://github.com/tableau/TabPy/releases). -Read description for the releases and download `zip` or `tar.gz` TabPy archive on your machine. -It is recommended to us the latest release of TabPy unless there are some restrictions or breaking -changes you need to consider. +TabPy server can be downloaded from +[TabPy github releases page](https://github.com/tableau/TabPy/releases). +Read description for the releases and download `zip` or `tar.gz` +TabPy archive on your machine. It is recommended to us the latest release +of TabPy unless there are some restrictions or breaking changes you need to +consider. -After downloading archive unpack it to a folder on your machine and you are ready to start -running TabPy from that folder. Read [configuration](server-config.md) and -[starting up instructions](server-startup.md) for more details. +After downloading archive unpack it to a folder on your machine and you are +ready to start running TabPy from that folder. Read +[configuration](server-config.md) and [starting up instructions](server-startup.md) +for more details. diff --git a/docs/server-rest.md b/docs/server-rest.md index e9fa13ea..16b92e31 100755 --- a/docs/server-rest.md +++ b/docs/server-rest.md @@ -1,6 +1,7 @@ # TabPy REST Interface -The server process exposes several REST APIs to get status and to execute Python code and query deployed methods. +The server process exposes several REST APIs to get status and to execute +Python code and query deployed methods. @@ -39,12 +40,17 @@ Content-Type: application/json ``` -- `description` is a string that is hardcoded in the `state.ini` file and can be edited there. -- `creation_time` is the creation time in seconds since 1970-01-01, hardcoded in the `state.ini` file, where it can be edited. -- `state_path` is the state file path of the server (the value of the TABPY_STATE_PATH at the time the server was started). -- `server_version` is the TabPy Server version tag. Clients can use this information for compatibility checks. +- `description` is a string that is hardcoded in the `state.ini` file and + can be edited there. +- `creation_time` is the creation time in seconds since 1970-01-01, hardcoded + in the `state.ini` file, where it can be edited. +- `state_path` is the state file path of the server (the value of the + TABPY_STATE_PATH at the time the server was started). +- `server_version` is the TabPy Server version tag. Clients can use this + information for compatibility checks. -See [TabPy Configuration](#tabpy-configuration) section for more information on modifying the settings. +See [TabPy Configuration](#tabpy-configuration) section for more information +on modifying the settings. Using curl: @@ -54,7 +60,8 @@ curl -X GET http://localhost:9004/info ## http:get:: /status -Gets runtime status of deployed endpoints. If no endpoints are deployed in the server, the returned data is an empty JSON object. +Gets runtime status of deployed endpoints. If no endpoints are deployed in +the server, the returned data is an empty JSON object. Example request: @@ -91,7 +98,8 @@ curl -X GET http://localhost:9004/status ## http:get:: /endpoints -Gets a list of deployed endpoints and their static information. If no endpoints are deployed in the server, the returned data is an empty JSON object. +Gets a list of deployed endpoints and their static information. If no +endpoints are deployed in the server, the returned data is an empty JSON object. Example request: @@ -136,7 +144,8 @@ curl -X GET http://localhost:9004/endpoints ## http:get:: /endpoints/:endpoint -Gets the description of a specific deployed endpoint. The endpoint must first be deployed in the server (see the [TabPy Tools documentation](tabpy-tools.md)). +Gets the description of a specific deployed endpoint. The endpoint must first +be deployed in the server (see the [TabPy Tools documentation](tabpy-tools.md)). Example request: @@ -165,12 +174,17 @@ curl -X GET http://localhost:9004/endpoints/add ## http:post:: /evaluate -Executes a block of Python code, replacing named parameters with their provided values. +Executes a block of Python code, replacing named parameters with their provided +values. The expected POST body is a JSON dictionary with two elements: -- A key `data` with a value that contains the parameter values passed to the code. These values are key-value pairs, following a specific convention for key names (`_arg1`, `_arg2`, etc.). -- A key `script` with a value that contains the Python code (one or more lines). Any references to the parameter names will be replaced by their values according to `data`. +- A key `data` with a value that contains the parameter values passed to the + code. These values are key-value pairs, following a specific convention for + key names (`_arg1`, `_arg2`, etc.). +- A key `script` with a value that contains the Python code (one or more lines). + Any references to the parameter names will be replaced by their values + according to `data`. Example request: @@ -198,13 +212,14 @@ curl -X POST http://localhost:9004/evaluate \ -d '{"data": {"_arg1": 1, "_arg2": 2}, "script": "return _arg1 + _arg2"}' ``` -It is possible to call a deployed function from within the code block, through the predefined -function `tabpy.query`. This function works like the client library's `query` method, and -returns the corresponding data structure. The function must first be deployed as an endpoint -in the server (for more details see the [TabPy Tools documentation](tabpy-tools.md)). +It is possible to call a deployed function from within the code block, through +the predefined function `tabpy.query`. This function works like the client +library's `query` method, and returns the corresponding data structure. The +function must first be deployed as an endpoint in the server (for more details +see the [TabPy Tools documentation](tabpy-tools.md)). -The following example calls the endpoint `clustering` as it was deployed in the section -[deploy-function](tabpy-tools.md#deploying-a-function): +The following example calls the endpoint `clustering` as it was deployed in the +section [deploy-function](tabpy-tools.md#deploying-a-function): ```HTTP POST /evaluate HTTP/1.1 @@ -218,8 +233,9 @@ Accept: application/json "script": "return tabpy.query('clustering', x=_arg1, y=_arg2)"} ``` -The next example shows how to call `evaluate` from a terminal using curl; this code queries the method -`add` that was deployed in the section [deploy-function](tabpy-tools.md#deploying-a-function): +The next example shows how to call `evaluate` from a terminal using curl; this +code queries the method `add` that was deployed in the section +[deploy-function](tabpy-tools.md#deploying-a-function): ```bash curl -X POST http://localhost:9004/evaluate \ @@ -229,10 +245,13 @@ curl -X POST http://localhost:9004/evaluate \ ## http:post:: /query/:endpoint -Executes a function at the specified endpoint. The function must first be deployed -(see the [TabPy Tools documentation](tabpy-tools.md)). +Executes a function at the specified endpoint. The function must first be +deployed (see the [TabPy Tools documentation](tabpy-tools.md)). -This interface expects a JSON body with a `data` key, specifying the values for the function, according to its original definition. In the example below, the function `clustering` was defined with a signature of two parameters `x` and `y`, expecting arrays of numbers. +This interface expects a JSON body with a `data` key, specifying the values +for the function, according to its original definition. In the example below, +the function `clustering` was defined with a signature of two parameters `x` +and `y`, expecting arrays of numbers. Example request: diff --git a/docs/server-startup.md b/docs/server-startup.md index 00ba43cf..3c1f030b 100755 --- a/docs/server-startup.md +++ b/docs/server-startup.md @@ -1,19 +1,21 @@ # Starting TabPy Server -These instructions explain how to start up TabPy Server. - - - -- [Prerequisites](#prerequisites) -- [Windows](#windows) - * [Command Line Arguments](#command-line-arguments) -- [Mac](#mac) - * [Command Line Arguments](#command-line-arguments-1) -- [Linux](#linux) - * [Command Line Arguments](#command-line-arguments-2) - - - +These instructions explain how to start up TabPy Server. + + + + +- [Prerequisites](#prerequisites) +- [Windows](#windows) + * [Command Line Arguments](#command-line-arguments) +- [Mac](#mac) + * [Command Line Arguments](#command-line-arguments-1) +- [Linux](#linux) + * [Command Line Arguments](#command-line-arguments-2) + + + + ## Prerequisites To start up TabPy Server from an environment the following prerequisites are required: @@ -25,9 +27,10 @@ First, select a TabPy version and download its source code from the [releases page](https://github.com/tableau/TabPy/releases). To start up a TabPy server instance, follow the instructions for your OS (found below). -Instructions on how to configure your TabPy server instance can be found in the [TabPy Server Configuration Instructions](server-config.md) +Instructions on how to configure your TabPy server instance can be found in the +[TabPy Server Configuration Instructions](server-config.md) -It is highly recommended to use Python virtual enviroment for running TabPy. +It is highly recommended to use Python virtual enviroment for running TabPy. Check the [Running TabPy in Python Virtual Environment](tabpy-virtualenv.md) page for more details. If you are installing a newer version of TabPy in the same environment as a @@ -44,16 +47,20 @@ previous install, delete the previous TabPy version folder in your Python direct startup.cmd ``` -### Command Line Arguments +### Command Line Arguments for Windows -To specify the *config file* with which to configure your server instance, pass it in as a command line argument as follows: +To specify the *config file* with which to configure your server instance, pass +it in as a command line argument as follows: ```batch startup.cmd myconfig.conf ``` -Replace ```myconfig.conf``` with the path to your config file relative to ```%TABPY_ROOT%\tabpy-server\tabpy_server\```. -For example, in this case your config file would be located at ```%TABPY_ROOT%\tabpy-server\tabpy_server\myconfig.conf``` +Replace `myconfig.conf` with the path to your config file relative to +`%TABPY_ROOT%\tabpy-server\tabpy_server\`. + +For example, in this case your config file would be located at +`%TABPY_ROOT%\tabpy-server\tabpy_server\myconfig.conf`. ## Mac @@ -66,24 +73,28 @@ For example, in this case your config file would be located at ```%TABPY_ROOT%\t ./startup.sh ``` -### Command Line Arguments +### Command Line Arguments for Mac -- To specify the *port* on which your server instance listens, set the ```-p``` command line argument as follows: +- To specify the *port* on which your server instance listens, set the `-p` + command line argument as follows: ```bash ./startup.sh -p 1234 ``` - Replace ```1234``` with the port of your choice. + Replace `1234` with the port of your choice. -- To specify the *config file* with which to configure your server instance, set the ```-c``` command line argument as follows: +- To specify the *config file* with which to configure your server instance, + set the `-c` command line argument as follows: ```bash ./startup.sh -c myconfig.conf ``` - Replace ```myconfig.conf``` with the path to your config file relative to ```$TABPY_ROOT/tabpy-server/tabpy_server/```. + Replace `myconfig.conf` with the path to your config file relative to + `$TABPY_ROOT/tabpy-server/tabpy_server/`. - For example, in this case your config file would be located at ```$TABPY_ROOT/tabpy-server/tabpy_server/myconfig.conf```. + For example, in this case your config file would be located at + `$TABPY_ROOT/tabpy-server/tabpy_server/myconfig.conf`. The following is an example of how you might set both the port and the config: @@ -102,28 +113,33 @@ The following is an example of how you might set both the port and the config: sudo ./startup.sh ``` -### Command Line Arguments +### Command Line Arguments for Linux -- To specify the *port* on which your server instance listens, set the ```-p``` command line argument as follows: +- To specify the *port* on which your server instance listens, set the `-p` + command line argument as follows: ```bash sudo ./startup.sh -p 1234 ``` - Replace ```1234``` with the port of your choice. -- To specify the *config file* with which to configure your server instance, set the ```-c``` command line argument as follows: + Replace `1234` with the port of your choice. + +- To specify the *config file* with which to configure your server instance, + set the `-c` command line argument as follows: ```bash sudo ./startup.sh -c myconfig.conf ``` - - Replace ```myconfig.conf``` with the path to your config file relative to ```$TABPY_ROOT/tabpy-server/tabpy_server/```. - For example, in this case your config file would be located at ```$TABPY_ROOT/tabpy-server/tabpy_server/myconfig.conf```. + Replace `myconfig.conf` with the path to your config file relative to + `$TABPY_ROOT/tabpy-server/tabpy_server/`. + + For example, in this case your config file would be located at + `$TABPY_ROOT/tabpy-server/tabpy_server/myconfig.conf`. The following is an example of how you might set both the port and the config: ```bash sudo ./startup.sh -p 1234 -c myconfig.conf -``` +``` diff --git a/docs/tabpy-tools.md b/docs/tabpy-tools.md index 86712d4a..0fefc316 100755 --- a/docs/tabpy-tools.md +++ b/docs/tabpy-tools.md @@ -27,7 +27,8 @@ client = Client('http://localhost:9004/') ``` The URL and port are where the Tableau-Python-Server process has been started - -more info can be found in the [server section](server-startup.md#Command-Line-Arguments) of the documentation. +more info can be found in the +[server section](server-startup.md#Command-Line-Arguments) of the documentation. ## Deploying a Function @@ -58,17 +59,18 @@ def clustering(x, y): client.deploy('clustering', - clustering, - 'Returns cluster Ids for each data point specified by the pairs in x and y') + clustering, + 'Returns cluster Ids for each data point specified by the ' + 'pairs in x and y') ``` In this example the function `clustering` expects a set of two-dimensional data points, represented by the list of all x-coordinates and the list of all y-coordinates. It will return a set of numerical labels corresponding to the clusters each datapoint -is assigned to. We deploy this function as an endpoint named `clustering`. It is now -reachable as a [REST API](server-rest.md#httppost-queryendpoint), as well as through the -TabPy tools - for details see the next section. +is assigned to. We deploy this function as an endpoint named `clustering`. It is +now reachable as a [REST API](server-rest.md#httppost-queryendpoint), as well as +through the TabPy tools - for details see the next section. You can re-deploy a function (for example, after you modified its code) by setting the `override` parameter to `True`: @@ -104,10 +106,10 @@ deployed (as in `gbm.predict(...)` below), Tableau will automatically save its definition using `cloudpickle` along with the definition of the function. The model will also be kept in memory on the server to achieve fast response times. If you persist your model manually to disk and read as part of your scoring function code -however, you will notice that response times are noticeably longer as every time a -client hits an endpoint, the code (including model loading) will get executed. In -order to get the best performance, we recommended following the methodology outlined -in this example. +however, you will notice that response times are noticeably longer as every time +a client hits an endpoint, the code (including model loading) will get executed. +In order to get the best performance, we recommended following the methodology +outlined in this example. ```python