Skip to content

Commit a283faf

Browse files
author
Jesse
authored
README updates (#9)
* Add license and contributing sections to README. * Add environment setup docs to CONTRIBUTING * Clarify example of connection details in example * Add badges from pypi * Explicitly call out Python 3.7 or above is needed
1 parent 07c709e commit a283faf

File tree

2 files changed

+74
-9
lines changed

2 files changed

+74
-9
lines changed

CONTRIBUTING.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Contributing
2+
3+
To contribute to this repository, fork it and send pull requests.
4+
5+
## Set up your environment
6+
7+
This project uses [Poetry](https://python-poetry.org/) for dependency management, tests, and linting.
8+
9+
1. Clone this respository
10+
2. Run `poetry install`
11+
12+
### Unit Tests
13+
14+
We use [Pytest](https://docs.pytest.org/en/7.1.x/) as our test runner. Invoke it with `poetry run pytest`, all other arguments are passed directly to `pytest`.
15+
16+
#### All tests
17+
```bash
18+
poetry run pytest tests
19+
```
20+
21+
#### Only a specific test file
22+
23+
```bash
24+
poetry run pytest tests/tests.py
25+
```
26+
27+
#### Only a specific method
28+
29+
```bash
30+
poetry run pytest tests/tests.py::ClientTestSuite::test_closing_connection_closes_commands
31+
```
32+
33+
### Code formatting
34+
35+
This project uses [Black](https://pypi.org/project/black/).
36+
37+
```
38+
poetry run black src
39+
```
40+
## Pull Request Process
41+
42+
1. Update the [CHANGELOG.md](README.md) or similar documentation with details of changes you wish to make, if applicable.
43+
2. Add any appropriate tests.
44+
3. Make your code or other changes.
45+
4. Review guidelines such as
46+
[How to write the perfect pull request][github-perfect-pr], thanks!
47+
48+
[github-perfect-pr]: https://blog.github.com/2015-01-21-how-to-write-the-perfect-pull-request/

README.md

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,19 @@
11
# Databricks SQL Connector for Python
22

3+
[![PyPI](https://img.shields.io/pypi/v/databricks-sql-connector?style=flat-square)](https://pypi.org/project/databricks-sql-connector/)
4+
[![Downloads](https://pepy.tech/badge/databricks-sql-connector)](https://pepy.tech/project/databricks-sql-connector)
5+
36
The Databricks SQL Connector for Python allows you to develop Python applications that connect to Databricks clusters and SQL warehouses. It is a Thrift-based client with no dependencies on ODBC or JDBC. It conforms to the [Python DB API 2.0 specification](https://www.python.org/dev/peps/pep-0249/).
47

58
This connector uses Arrow as the data-exchange format, and supports APIs to directly fetch Arrow tables. Arrow tables are wrapped in the `ArrowQueue` class to provide a natural API to get several rows at a time.
69

710
You are welcome to file an issue here for general use cases. You can also contact Databricks Support [here](help.databricks.com).
811

9-
# Documentation
12+
## Requirements
13+
14+
Python 3.7 or above is required.
15+
16+
## Documentation
1017

1118
For the latest documentation, see
1219

@@ -23,9 +30,10 @@ Example usage:
2330
from databricks import sql
2431

2532
connection = sql.connect(
26-
server_hostname='<server-hostname>',
27-
http_path='<http-path>',
28-
access_token='<personal-access-token>')
33+
server_hostname='********.databricks.com',
34+
http_path='/sql/1.0/endpoints/****************',
35+
access_token='dapi********************************')
36+
2937

3038
cursor = connection.cursor()
3139

@@ -38,8 +46,17 @@ cursor.close()
3846
connection.close()
3947
```
4048

41-
Where:
42-
- `<server-hostname>` is the Databricks instance host name.
43-
- `<http-path>` is the HTTP Path either to a Databricks SQL endpoint (e.g. /sql/1.0/endpoints/1234567890abcdef),
44-
or to a Databricks Runtime interactive cluster (e.g. /sql/protocolv1/o/1234567890123456/1234-123456-slid123)
45-
- `<personal-access-token>` is a HTTP Bearer access token, e.g. a Databricks Personal Access Token.
49+
In the above example:
50+
- `server-hostname` is the Databricks instance host name.
51+
- `http-path` is the HTTP Path either to a Databricks SQL endpoint (e.g. /sql/1.0/endpoints/1234567890abcdef),
52+
or to a Databricks Runtime interactive cluster (e.g. /sql/protocolv1/o/1234567890123456/1234-123456-slid123)
53+
- `personal-access-token` is the Databricks Personal Access Token for the account that will execute commands and queries
54+
55+
56+
## Contributing
57+
58+
See [CONTRIBUTING.md](CONTRIBUTING.md)
59+
60+
## License
61+
62+
[Apache License 2.0](LICENSE)

0 commit comments

Comments
 (0)