Skip to content

README updates #226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Aug 19, 2022
Merged

README updates #226

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
edb7f5c
Remove SQLAlchemy pre-requisite as setup.py will already install it
hashhar Aug 18, 2022
eece414
Use consistent header style in README
hashhar Aug 18, 2022
446faf2
Language improvements in README
hashhar Aug 18, 2022
8282d67
Reformat example code in README
hashhar Aug 18, 2022
18e6561
Move all SSL related information under dedicated header
hashhar Aug 18, 2022
36a3462
Fix header level in README
hashhar Aug 18, 2022
2ef66ee
Simplify and reorder development instructions in README
hashhar Aug 18, 2022
61c867e
Update releasing instructions in README
hashhar Aug 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 58 additions & 63 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -48,7 +48,6 @@ rows for example `Cursor.fetchone()` or `Cursor.fetchmany()`. By default

**Prerequisite**

- SQLAlchemy >= 1.3
- Trino server >= 351

**Installation**
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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://<username>:<password>@<host>:<port>/<catalog>")
# or

# or as connect_args
from trino.auth import BasicAuthentication
engine = create_engine(
"trino://<username>@<host>:<port>/<catalog>",
Expand All @@ -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):
Expand All @@ -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="<username>",
auth=JWTAuthentication("<jwt_token>"),
Expand All @@ -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://<username>@<host>:<port>/<catalog>/<schema>?access_token=<jwt_token>")
# or

# or as connect_args
from trino.auth import JWTAuthentication
engine = create_engine(
"trino://<username>@<host>:<port>/<catalog>",
Expand All @@ -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).
Expand Down Expand Up @@ -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.

Expand All @@ -253,7 +252,7 @@ The OAuth2 token will be cached either per `trino.auth.OAuth2Authentication` ins

engine = create_engine("trino://<username>@<host>:<port>/<catalog>/<schema>?cert=<cert>&key=<key>")

# or
# or as connect_args
engine = create_engine(
"trino://<username>@<host>:<port>/<catalog>",
connect_args={
Expand All @@ -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):
Expand All @@ -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="<username>",
auth=KerberosAuthentication(...),
Expand All @@ -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
Expand All @@ -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`.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about creating DEVELOPMENT.md or CONTRIBUTING.md exclusively for trino-python-client? It can be done as a follow-up and move there all necessary information about testing, contributing?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

README is still the place where build instructions should live.

Things like code style, release process etc. can go to DEVELOPMENT.md.

I'll send a follow-up PR - thanks for the idea.

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:
Expand All @@ -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:

```
Expand All @@ -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
Expand All @@ -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