diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3fd4f0a3..1d156674 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,8 +48,8 @@ be able to work on TabPy changes: ## Setting Up Environment -Before making any code changes run environment setup script. For -Windows run the next command from the repository root folder: +Before making any code changes run environment setup script. +For Windows run this command from the repository root folder: ```sh utils\set_env.cmd @@ -64,7 +64,7 @@ source utils/set_env.sh ## Unit Tests TabPy has test suites for `tabpy-server` and `tabpy-tools` components. -To run the unit test use `pytest` which you may need to install first +To run the unit tests use `pytest` which you may need to install first (see [https://docs.pytest.org](https://docs.pytest.org) for details): ```sh @@ -92,7 +92,7 @@ pytest tests --cov=tabpy-server/tabpy_server --cov=tabpy-tools/tabpy_tools --cov ## TabPy in Python Virtual Environment -It is possible (and recommended) to run TabPy in a virtual environment, more +It is possible (and recommended) to run TabPy in a virtual environment. More details are on [TabPy in Python virtual environment](docs/tabpy-virtualenv.md) page. @@ -108,9 +108,11 @@ TOC for markdown file is built with [markdown-toc](https://www.npmjs.com/package markdown-toc -i docs/server-startup.md ``` +These checks will run as part of the build if you submit a pull request. + ## TabPy with Swagger -You can invoke TabPy Server API against running TabPy instance with Swagger: +You can invoke the TabPy Server API against a running TabPy instance with Swagger. - Make CORS related changes in TabPy configuration file: update `tabpy-server\state.ini` file in your local repository to have the next settings: @@ -122,24 +124,23 @@ Access-Control-Allow-Headers = Origin, X-Requested-with, Content-Type 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 +- Start a local instance of TabPy server following [TabPy Server Startup Guide](docs/server-startup.md). +- Run a 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 +- In case your TabPy server does not run on `localhost:9004` update `host` value in `TabPy.yml` accordingly. ## 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: +`pycodestyle` is used to check Python code against our style conventions. +You can run install it and run locally for files where modifications were made: ```sh pip install pycodestyle ``` -And then run it for file where modifications were made, e.g.: +And then run it for files where modifications were made, e.g.: ```sh pycodestyle tabpy-server/server_tests/test_pwd_file.py @@ -154,9 +155,9 @@ To install `autopep8` run the next command: pip install autopep8 ``` -And then you can run the tool for a file. In the example below `-i` +Then you can run the tool for a file. In the example below `-i` option tells `autopep8` to update the file. Without the option it -outputs formated code to console. +outputs formatted code to the console. ```sh autopep8 -i tabpy-server/server_tests/test_pwd_file.py diff --git a/docs/api-v1.md b/docs/api-v1.md index 2ba1f6e1..6841b2b0 100755 --- a/docs/api-v1.md +++ b/docs/api-v1.md @@ -1,24 +1,24 @@ # TabPy API v1 - - - - -- [Authentication](#authentication) -- [http:get:: /status](#httpget-status) -- [http:get:: /endpoints](#httpget-endpoints) -- [http:get:: /endpoints/:endpoint](#httpget-endpointsendpoint) -- [http:post:: /evaluate](#httppost-evaluate) -- [http:post:: /query/:endpoint](#httppost-queryendpoint) - - - + + + + +- [Authentication](#authentication) +- [http:get:: /status](#httpget-status) +- [http:get:: /endpoints](#httpget-endpoints) +- [http:get:: /endpoints/:endpoint](#httpget-endpointsendpoint) +- [http:post:: /evaluate](#httppost-evaluate) +- [http:post:: /query/:endpoint](#httppost-queryendpoint) + + + ## Authentication -When authentication feature is enabled for v1 API [`/info` call](server-rest.md#get-info) -response contains authentication feature parameters, e.g.: +When authentication is enabled for v1 API [`/info` call](server-rest.md#get-info), +the response contains authentication feature parameters, e.g.: ```json { @@ -48,9 +48,9 @@ v1 authentication specific features (see the example above): Property | Description --- | --- -`required` | Authentication is never optional for client to use if it is mentioned in features list. +`required` | Authentication is never optional for a client to use if it is in the features list. `methods` | List of supported authentication methods with their properties. -`methods.basic-auth` | TabPy requires to use basic access authentication, see [TabPy Server Configuration Instructions](server-config.md#authentication) for how to configure authentication. +`methods.basic-auth` | TabPy requires basic access authentication. See [TabPy Server Configuration Instructions](server-config.md#authentication) for how to configure authentication. @@ -208,7 +208,7 @@ 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 +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 @@ -229,7 +229,7 @@ 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 +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): @@ -277,4 +277,4 @@ Using curl: curl -X GET http://localhost:9004/query/clustering -d \ '{"data": {"x": [6.35, 6.40, 6.65, 8.60, 8.90, 9.00, 9.10], "y": [1.95, 1.95, 2.05, 3.05, 3.05, 3.10, 3.15]}}' -``` +``` diff --git a/docs/server-config.md b/docs/server-config.md index 66397b62..88a806d0 100755 --- a/docs/server-config.md +++ b/docs/server-config.md @@ -8,7 +8,7 @@ - [Authentication](#authentication) * [Enabling Authentication](#enabling-authentication) * [Password File](#password-file) - * [Setting Up Environmnet](#setting-up-environmnet) + * [Setting Up Environment](#setting-up-environment) * [Adding an Account](#adding-an-account) * [Updating an Account](#updating-an-account) * [Deleting an Account](#deleting-an-account) @@ -85,7 +85,7 @@ Password file is a text file containing usernames and hashed passwords per line separated by single space. For username only ASCII characters are supported. Usernames are case-insensitive. -Passwords in the password file are hashed with PBKDF2, [see source code +Passwords in the password file are hashed with PBKDF2. [See source code for implementation details](../tabpy-server/tabpy_server/handlers/util.py). **It is highly recommended to restrict access to the password file @@ -98,16 +98,16 @@ see how to use it. After making any changes to the password file, TabPy needs to be restarted. -### Setting Up Environmnet +### Setting Up Environment -Before making any code changes run environment setup script. For -Windows run the next command from the repository root folder: +Before making any code changes run the environment setup script. For +Windows run this command from the repository root folder: ```sh utils\set_env.cmd ``` -and for Linux or Mac the next command from the repository root folder: +and for Linux or Mac run this command from the repository root folder: ```sh source utils/set_env.sh @@ -144,15 +144,15 @@ line with the user name. ## Logging -Logging for TabPy is implemented with standard Python logger and can be configured +Logging for TabPy is implemented with Python's standard logger and can be configured as explained in Python documentation at [Logging Configuration page](https://docs.python.org/3.6/library/logging.config.html). -Default config provided with TabPy is +A default config provided with TabPy is at [`tabpy-server/tabpy_server/common/default.conf`](tabpy-server/tabpy_server/common/default.conf) -and has configuration for console and file loggers. With changing the config -user can modify log level, format of the logges messages and add or remove -loggers. +and has a configuration for console and file loggers. Changing the config file +allows the user to modify the log level, format of the logged messages and +add or remove loggers. ### Request Context Logging @@ -179,3 +179,5 @@ function to evaluate=def _user_script(tabpy, _arg1, _arg2): ``` + +No passwords are logged. diff --git a/docs/server-rest.md b/docs/server-rest.md index 902455d8..3bae2952 100755 --- a/docs/server-rest.md +++ b/docs/server-rest.md @@ -22,8 +22,8 @@ Python code and query deployed methods. ## GET /info Get static information about the server. The method doesn't require any -authentication and returns supported API versions client can use together -with optional and required features. +authentication and returns supported API versions which the client can use +together with optional and required features. ### URL @@ -47,7 +47,7 @@ None. ### Response -For successful call: +For a successful call: - Status: 200 - Content: @@ -81,21 +81,18 @@ Response fields: Property | Description --- | --- `description` | String that is hardcoded in the `state.ini` file and can be edited there. -`creation_time` | creation time in seconds since 1970-01-01, hardcoded in the `state.ini` file, where it can be edited. -`state_path` | state file path of the server (the value of the TABPY_STATE_PATH at the time the server was started). +`creation_time` | Creation time in seconds since 1970-01-01, hardcoded in the `state.ini` file, where it can be edited. +`state_path` | State file path of the server (the value of the TABPY_STATE_PATH at the time the server was started). `server_version` | TabPy Server version tag. Clients can use this information for compatibility checks. `name` | TabPy server instance name. Can be edited in `state.ini` file. -`version` | Collection of API versions supported by the server. Each entry in the collection is an API version which has corresponding list of properties. +`version` | Collection of API versions supported by the server. Each entry in the collection is an API version which has a corresponding list of properties. `version.`*``* | Set of properties for an API version. -`version.`*`.features`* | Set of an API available features. -`version.`*`.features.`* | Set of a features properties. For specific details for property meaning of a feature check documentation for specific API version. +`version.`*`.features`* | Set of an API's available features. +`version.`*`.features.`* | Set of a feature's properties. For specific details for a particular property meaning of a feature, check the documentation for the specific API version. `version.`*`.features..required`* | If true the feature is required to be used by client. -For each API version there is set of properties, e.g. for v1 in the example -above features are: - See [TabPy Configuration](#tabpy-configuration) section for more information on modifying the settings.