diff --git a/README.md b/README.md index 9efb475e..d45c6554 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -Trino Python client -=================== +# Trino Python client + A [Trino](https://trino.io/) client for the [Python](https://www.python.org/) programming language. It supports Python>=3.7 and pypy. @@ -48,7 +48,6 @@ rows for example `Cursor.fetchone()` or `Cursor.fetchmany()`. By default **Prerequisite** -- SQLAlchemy >= 1.3 - Trino server >= 351 **Installation** @@ -90,7 +89,7 @@ rows = connection.execute(select(nodes)).fetchall() ``` In order to pass additional connection attributes use [connect_args](https://docs.sqlalchemy.org/en/14/core/engines.html#sqlalchemy.create_engine.params.connect_args) method. -Attributes can be also passed in connection string. +Attributes can also be passed in the connection string. ```python from sqlalchemy import create_engine @@ -113,12 +112,12 @@ engine = create_engine( ) ``` -## Authentications +## Authentication mechanisms -### Basic Authentication +### Basic authentication The `BasicAuthentication` class can be used to connect to a Trino cluster configured with -the [Password file authentication type, LDAP authentication type or Salesforce authentication type](https://trino.io/docs/current/security/authentication-types.html): +the [Password file, LDAP or Salesforce authentication type](https://trino.io/docs/current/security/authentication-types.html): - DBAPI @@ -138,10 +137,10 @@ the [Password file authentication type, LDAP authentication type or Salesforce a ```python from sqlalchemy import create_engine - + engine = create_engine("trino://:@:/") - - # or + + # or as connect_args from trino.auth import BasicAuthentication engine = create_engine( "trino://@:/", @@ -152,7 +151,7 @@ the [Password file authentication type, LDAP authentication type or Salesforce a ) ``` -### JWT Authentication +### JWT authentication The `JWTAuthentication` class can be used to connect to a Trino cluster configured with the [`JWT` authentication type](https://trino.io/docs/current/security/jwt.html): @@ -162,7 +161,7 @@ the [`JWT` authentication type](https://trino.io/docs/current/security/jwt.html) ```python from trino.dbapi import connect from trino.auth import JWTAuthentication - + conn = connect( user="", auth=JWTAuthentication(""), @@ -175,10 +174,10 @@ the [`JWT` authentication type](https://trino.io/docs/current/security/jwt.html) ```python from sqlalchemy import create_engine - + engine = create_engine("trino://@://?access_token=") - - # or + + # or as connect_args from trino.auth import JWTAuthentication engine = create_engine( "trino://@:/", @@ -189,7 +188,7 @@ the [`JWT` authentication type](https://trino.io/docs/current/security/jwt.html) ) ``` -### OAuth2 Authentication +### OAuth2 authentication The `OAuth2Authentication` class can be used to connect to a Trino cluster configured with the [OAuth2 authentication type](https://trino.io/docs/current/security/oauth2.html). @@ -227,7 +226,7 @@ The OAuth2 token will be cached either per `trino.auth.OAuth2Authentication` ins ) ``` -### Certificate Authentication +### Certificate authentication `CertificateAuthentication` class can be used to connect to Trino cluster configured with [certificate based authentication](https://trino.io/docs/current/security/certificate.html). `CertificateAuthentication` requires paths to a valid client certificate and private key. @@ -253,7 +252,7 @@ The OAuth2 token will be cached either per `trino.auth.OAuth2Authentication` ins engine = create_engine("trino://@://?cert=&key=") - # or + # or as connect_args engine = create_engine( "trino://@:/", connect_args={ @@ -263,7 +262,7 @@ The OAuth2 token will be cached either per `trino.auth.OAuth2Authentication` ins ) ``` -### Kerberos Authentication +### Kerberos authentication The `KerberosAuthentication` class can be used to connect to a Trino cluster configured with the [`Kerberos` authentication type](https://trino.io/docs/current/security/kerberos.html): @@ -273,7 +272,7 @@ the [`Kerberos` authentication type](https://trino.io/docs/current/security/kerb ```python from trino.dbapi import connect from trino.auth import KerberosAuthentication - + conn = connect( user="", auth=KerberosAuthentication(...), @@ -297,16 +296,16 @@ the [`Kerberos` authentication type](https://trino.io/docs/current/security/kerb ) ``` -### User impersonation +## User impersonation -In the case of user who submit the query is not the same as user who authenticate to Trino server (e.g in Superset), -you can set `username` to different from `principal_id`. Note that `principal_id` is extracted from `auth`, -for example `username` in BasicAuthentication, `sub` in JWT token or `service-name` in KerberosAuthentication and -please make sure that [`principal_id` has permission to impersonate `username`](https://trino.io/docs/current/security/file-system-access-control.html#impersonation-rules). +In the case where user who submits the query is not the same as user who authenticates to Trino server (e.g in Superset), +you can set `username` to be different from `principal_id`. Note that `principal_id` is extracted from `auth`, +for example `username` in BasicAuthentication, `sub` in JWT token or `service-name` in KerberosAuthentication. +You need to make sure that [`principal_id` has permission to impersonate `username`](https://trino.io/docs/current/security/file-system-access-control.html#impersonation-rules). -### Extra Credential +### Extra credentials -Send [`extra credentials`](https://trino.io/docs/current/develop/client-protocol.html#client-request-headers): +[`Extra credentials`](https://trino.io/docs/current/develop/client-protocol.html#client-request-headers) can be sent as: ```python import trino @@ -322,6 +321,8 @@ cur.execute('SELECT * FROM system.runtime.nodes') rows = cur.fetchall() ``` +## SSL + ### SSL verification In order to disable SSL verification, set the `verify` parameter to `False`. @@ -380,7 +381,7 @@ The transaction is created when the first SQL statement is executed. exits the *with* context and the queries succeed, otherwise `trino.dbapi.Connection.rollback()` will be called. -# Improved Python types +## Improved Python types If you enable the flag `experimental_python_types`, the client will convert the results of the query to the corresponding Python types. For example, if the query returns a `DECIMAL` column, the result will be a `Decimal` object. @@ -413,42 +414,34 @@ assert cur.description[0][1] == "timestamp with time zone" # Development -## Getting Started With Development +## Getting started with development Start by forking the repository and then modify the code in your fork. -Clone the repository and go inside the code directory. Then you can get the -version with `./setup.py --version`. - We recommend that you use Python3's `venv` for development: ``` $ python3 -m venv .venv $ . .venv/bin/activate -$ pip install . -``` - -For development purpose, pip can reference the code you are modifying in a -*virtual env*: - -``` -$ pip install -e . -# To additionally install all dependencies for development run below command $ pip install -e '.[tests]' ``` -That way, you do not need to run `pip install` again to make your changes -applied to the *virtual env*. +With `-e` passed to `pip install` above pip can reference the code you are +modifying in the *virtual env*. That way, you do not need to run `pip install` +again to make your changes applied to the *virtual env*. When the code is ready, submit a Pull Request. -### Code Style +### Code style - For Python code, adhere to PEP 8. - Prefer code that is readable over one that is "clever". - When writing a Git commit message, follow these [guidelines](https://chris.beams.io/posts/git-commit/). -### Running Tests +See also Trino's [guidelines](https://github.com/trinodb/trino/blob/master/.github/DEVELOPMENT.md). +Most of them also apply to code in trino-python-client. + +### Running tests `trino-python-client` uses [pytest](https://pytest.org/) for its tests. To run only unit tests, type: @@ -459,13 +452,6 @@ $ pytest tests/unit Then you can pass options like `--pdb` or anything supported by `pytest --help`. -To run the tests with different versions of Python in managed *virtual envs*, -use `tox` (see the configuration in `tox.ini`): - -``` -$ tox -``` - To run integration tests: ``` @@ -476,7 +462,14 @@ They pull a Docker image and then run a container with a Trino server: - the image is named `trinodb/trino:${TRINO_VERSION}` - the container is named `trino-python-client-tests-{uuid4()[:7]}` -### Releasing +To run the tests with different versions of Python in managed *virtual envs*, +use `tox` (see the configuration in `tox.ini`): + +``` +$ tox +``` + +## Releasing - [Set up your development environment](#Getting-Started-With-Development). - Check the local workspace is up to date and has no uncommitted changes @@ -494,24 +487,26 @@ They pull a Docker image and then run a container with a Trino server: ``` - Create release package and upload it to PyPI ```bash - . .venv/bin/activate && - pip install twine && - rm -rf dist/ && - ./setup.py sdist bdist_wheel && - twine upload dist/* && - open https://pypi.org/project/trino/ && + . .venv/bin/activate && \ + pip install twine && \ + rm -rf dist/ && \ + ./setup.py sdist bdist_wheel && \ + twine upload dist/* && \ + open https://pypi.org/project/trino/ && \ echo "Released!" ``` - Push the branch and the tag ```bash git push upstream master 0.123.0 ``` -- Send release announcement. +- Send release announcement on the *#python-client* channel on [Trino Slack][trino-slack]. -## Need Help? +# Need help? -Feel free to create an issue as it make your request visible to other users and contributors. +Feel free to create an issue as it makes your request visible to other users and contributors. If an interactive discussion would be better or if you just want to hangout and chat about the Trino Python client, you can join us on the *#python-client* channel on -[Trino Slack](https://trino.io/slack.html). +[Trino Slack][trino-slack]. + +[trino-slack]: https://trino.io/slack.html