# Cassandra Connector
This package provides a helpful wrapper around the `cassandra-driver` package with the following features:
1. References environment variables for seamless connections to Apache Cassandra® and DataStax® Astra DB
2. ConnectionManager maintains a dictionary of cluster connections, facilitating connections to multiple
clusters in a single place.
3. Automatically downloads Astra secure connect bundles, based on provided endpoint.
## Installing
Until such time as this is published in PyPI, install from the GitHub repo directly:
```bash
pip install git+https://github.com/mieslep/cassandra-connector.git
```
## Using
### Connecting to Astra
#### Connecting to Astra with Environment Variables
The simplest approach is to set appropriate environment variables:
```bash
ASTRA_DB_APPLICATION_TOKEN=AstraCS:<your token here>
ASTRA_DB_API_ENDPOINT=https://<your endpoint here>
```
and then:
```python
from cassandra_connector import CassandraConnectorManager
cm = CassandraConnectorManager()
astra = cm.get_connector('env_astra')
session = astra.session
```
which will get a driver Session object based on the `ASTRA` environment variables.
#### Connecting to Astra Directly
You can bypass the `CassandraConnectorManager` and use the `CassandraConnector` directly by passing a keyword `dict`
to the `astra` parameter, including both `token` and `endpoint` parameters:
```python
from cassandra_connector import CassandraConnector
astra = CassandraConnector(astra={"token": "AstraCS:<your token here>", "endpoint": "https://<your endpoint here>"})
session = astra.session
```
### Connecting to Cassandra
Connecting to a Cassandra, DataStax Enterprise (DSE), or any other Cassandra-compatible cluster is similar to
the driver connection, but as a single step invocation.
There are two parameters introduced with the `CassandraConnector`; these are used to construct the authentication
provider object that is passed into the Cluster constructor:
* `authProviderClass` is a string representing the Python package of the provider (it must be `import`-able)
* `authProviderArgs` is a `dict` of keyword arguments that are passed to the provider class
All other arguments will be passed directly to the `Cluster` constructor.
**Note**: If you do not need an auth provider to connect, you may omit these parameters. This is generally not
advised for any production enviroment as it means that anybody with access to your cluster can access the data
within the cluster.
#### Connecting to Cassandra with Environment Variables
If you want to use `env_cassandra`, represent them as a single JSON document in the `CASSANDRA_CONNECTION` variable, for example:
```bash
CASSANDRA_CONNECTION={"authProviderClass": "cassandra.auth.PlainTextAuthProvider", "authProviderArgs": {"username": "cassandra", "password": "cassandra"}, "contact_points": ["localhost"], "port": 9042}
```
Once set, you can get a Session:
```python
from cassandra_connector import CassandraConnectorManager
cm = CassandraConnectorManager()
cassandra = cm.get_connector('env_cassandra')
session = cassandra.session
```
#### Connecting to Cassandra Directly
You can provide these same arguments directly to the `CassandraConnector`:
```python
from cassandra_connector import CassandraConnector
cassandra = CassandraConnector(
authProviderClass="cassandra.auth.PlainTextAuthProvider",
authProviderArgs={"username": "cassandra", "password": "cassandra"},
contact_points=["localhost"],
port=9042)
session = cassandra.session
```
### The `CassandraConnectorManager` Object
In addition to being able to create `CassandraConnector` objects from environment variables, you can use the `get_connector` function
along with a `dict` key of your choosing (other than the above `env_*` keys). The first time a key is used, you must
pass connection parameters as you would connecting "directly" as documented above, but subsequently you can simply pass the key
and the `CassandraConnector` will be returned.
### The `CassandraConnector` Object
As seen above, this object has a `.session` property which is the native driver Session object. The object also has a `.cluster`
property which gives access to the native driver Cluster object.
The `session()` function has two boolean parameters:
* `replace` will close the existing session and replace it with a new session; you may wish to do this if you have changed something
in the underlying `Cluster` object for example.
* `new` will create a new (and detached) Session object.
## For More Details
Docstrings are the best reference for more detailed usage for the connection arguments.
## Contributing
Contributions welcome, just fire off a pull request :)
Raw data
{
"_id": null,
"home_page": "https://github.com/mieslep/cassandra-connector",
"name": "cassandra-connector",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cassandra astra db connector",
"author": "Phil Miesle",
"author_email": "phil.miesle@datastax.com",
"download_url": "https://files.pythonhosted.org/packages/e1/cc/9b0c51dc54c036ac3b0c03722ac604070263908fa4099407d40d3de07275/cassandra-connector-0.3.0.tar.gz",
"platform": null,
"description": "# Cassandra Connector\r\n\r\nThis package provides a helpful wrapper around the `cassandra-driver` package with the following features:\r\n\r\n1. References environment variables for seamless connections to Apache Cassandra\u00c2\u00ae and DataStax\u00c2\u00ae Astra DB\r\n2. ConnectionManager maintains a dictionary of cluster connections, facilitating connections to multiple \r\n clusters in a single place.\r\n3. Automatically downloads Astra secure connect bundles, based on provided endpoint.\r\n\r\n## Installing\r\n\r\nUntil such time as this is published in PyPI, install from the GitHub repo directly:\r\n\r\n```bash\r\npip install git+https://github.com/mieslep/cassandra-connector.git\r\n```\r\n\r\n## Using\r\n\r\n### Connecting to Astra\r\n\r\n#### Connecting to Astra with Environment Variables\r\n\r\nThe simplest approach is to set appropriate environment variables:\r\n\r\n```bash\r\nASTRA_DB_APPLICATION_TOKEN=AstraCS:<your token here>\r\nASTRA_DB_API_ENDPOINT=https://<your endpoint here>\r\n```\r\n\r\nand then:\r\n\r\n```python\r\nfrom cassandra_connector import CassandraConnectorManager\r\n\r\ncm = CassandraConnectorManager()\r\nastra = cm.get_connector('env_astra')\r\nsession = astra.session\r\n```\r\n\r\nwhich will get a driver Session object based on the `ASTRA` environment variables. \r\n\r\n#### Connecting to Astra Directly\r\n\r\nYou can bypass the `CassandraConnectorManager` and use the `CassandraConnector` directly by passing a keyword `dict`\r\nto the `astra` parameter, including both `token` and `endpoint` parameters:\r\n\r\n```python\r\nfrom cassandra_connector import CassandraConnector\r\n\r\nastra = CassandraConnector(astra={\"token\": \"AstraCS:<your token here>\", \"endpoint\": \"https://<your endpoint here>\"})\r\nsession = astra.session\r\n```\r\n\r\n### Connecting to Cassandra\r\n\r\nConnecting to a Cassandra, DataStax Enterprise (DSE), or any other Cassandra-compatible cluster is similar to \r\nthe driver connection, but as a single step invocation.\r\n\r\nThere are two parameters introduced with the `CassandraConnector`; these are used to construct the authentication \r\nprovider object that is passed into the Cluster constructor:\r\n\r\n* `authProviderClass` is a string representing the Python package of the provider (it must be `import`-able)\r\n* `authProviderArgs` is a `dict` of keyword arguments that are passed to the provider class\r\n\r\nAll other arguments will be passed directly to the `Cluster` constructor.\r\n\r\n**Note**: If you do not need an auth provider to connect, you may omit these parameters. This is generally not \r\nadvised for any production enviroment as it means that anybody with access to your cluster can access the data \r\nwithin the cluster.\r\n\r\n#### Connecting to Cassandra with Environment Variables\r\n\r\nIf you want to use `env_cassandra`, represent them as a single JSON document in the `CASSANDRA_CONNECTION` variable, for example:\r\n\r\n```bash\r\nCASSANDRA_CONNECTION={\"authProviderClass\": \"cassandra.auth.PlainTextAuthProvider\", \"authProviderArgs\": {\"username\": \"cassandra\", \"password\": \"cassandra\"}, \"contact_points\": [\"localhost\"], \"port\": 9042}\r\n```\r\n\r\nOnce set, you can get a Session:\r\n\r\n```python\r\nfrom cassandra_connector import CassandraConnectorManager\r\n\r\ncm = CassandraConnectorManager()\r\ncassandra = cm.get_connector('env_cassandra')\r\nsession = cassandra.session\r\n```\r\n\r\n#### Connecting to Cassandra Directly\r\n\r\nYou can provide these same arguments directly to the `CassandraConnector`: \r\n\r\n```python\r\nfrom cassandra_connector import CassandraConnector\r\n\r\ncassandra = CassandraConnector(\r\n authProviderClass=\"cassandra.auth.PlainTextAuthProvider\",\r\n authProviderArgs={\"username\": \"cassandra\", \"password\": \"cassandra\"},\r\n contact_points=[\"localhost\"],\r\n port=9042)\r\nsession = cassandra.session\r\n```\r\n\r\n### The `CassandraConnectorManager` Object\r\n\r\nIn addition to being able to create `CassandraConnector` objects from environment variables, you can use the `get_connector` function\r\nalong with a `dict` key of your choosing (other than the above `env_*` keys). The first time a key is used, you must \r\npass connection parameters as you would connecting \"directly\" as documented above, but subsequently you can simply pass the key \r\nand the `CassandraConnector` will be returned.\r\n\r\n### The `CassandraConnector` Object\r\n\r\nAs seen above, this object has a `.session` property which is the native driver Session object. The object also has a `.cluster` \r\nproperty which gives access to the native driver Cluster object. \r\n\r\nThe `session()` function has two boolean parameters:\r\n* `replace` will close the existing session and replace it with a new session; you may wish to do this if you have changed something\r\n in the underlying `Cluster` object for example.\r\n* `new` will create a new (and detached) Session object.\r\n\r\n## For More Details\r\n\r\nDocstrings are the best reference for more detailed usage for the connection arguments.\r\n\r\n## Contributing\r\n\r\nContributions welcome, just fire off a pull request :) \r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Simplifies connecting to Cassandra and AstraDB when using the DataStax driver",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/mieslep/cassandra-connector"
},
"split_keywords": [
"cassandra",
"astra",
"db",
"connector"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "84c464d702e579fb902547487e2ecdcf8e19a63e72ae3058d75dd8e13a6c5608",
"md5": "6f5896f991b936445dcfe1a81c728430",
"sha256": "cb09e8b0f06d963aacf483c7234c40fa5db063487d5b22cf7adc92053250a92b"
},
"downloads": -1,
"filename": "cassandra_connector-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6f5896f991b936445dcfe1a81c728430",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9755,
"upload_time": "2024-03-29T13:09:50",
"upload_time_iso_8601": "2024-03-29T13:09:50.242297Z",
"url": "https://files.pythonhosted.org/packages/84/c4/64d702e579fb902547487e2ecdcf8e19a63e72ae3058d75dd8e13a6c5608/cassandra_connector-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e1cc9b0c51dc54c036ac3b0c03722ac604070263908fa4099407d40d3de07275",
"md5": "a3912c62639fe1d4c53bf4a5b1ca3241",
"sha256": "6390ee33f11ce5274987410b9cf2bc572167f6d080025f61a2dc7b0e688b56d0"
},
"downloads": -1,
"filename": "cassandra-connector-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "a3912c62639fe1d4c53bf4a5b1ca3241",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10166,
"upload_time": "2024-03-29T13:09:52",
"upload_time_iso_8601": "2024-03-29T13:09:52.071821Z",
"url": "https://files.pythonhosted.org/packages/e1/cc/9b0c51dc54c036ac3b0c03722ac604070263908fa4099407d40d3de07275/cassandra-connector-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-29 13:09:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mieslep",
"github_project": "cassandra-connector",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "cassandra-driver",
"specs": [
[
">=",
"3.29.1"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.1"
]
]
}
],
"lcname": "cassandra-connector"
}
JSON
