Tentaclio

Warnings

• gotcha Many common protocols (e.g., S3, Google Storage, Databricks, various databases) are not included in the base installation. Attempting to use URLs for these schemes without installing the corresponding optional dependencies (e.g., `pip install tentaclio[s3]`) will result in runtime errors.
  Fix: Install `tentaclio` with the specific extras needed for your protocols, e.g., `pip install tentaclio[s3,gs,postgres]`.
• gotcha When using environment variables (prefixed with `TENTACLIO__CONN__`) or a secrets file for authentication, Tentaclio treats the hostname in the URL provided to `tentaclio.open` or `tentaclio.db` as a wildcard. Credentials from the environment variable with a matching scheme and path will be injected. This means `sftp://sftp.example.com/file.txt` will use credentials defined for `sftp://user:pass@sftp.example.com/`, even if the provided URL doesn't contain user/pass.
  Fix: Be aware that the user, password, and hostname from stored credentials (environment variable or secrets file) will override those in the explicit URL if a matching credential entry is found. Scheme and path are taken from the URL, while port is prioritized from credentials if present, otherwise from the URL.
• deprecated Earlier versions (prior to 1.3.2) did not support specifying SFTP private key path and password directly via query parameters in the URL. This functionality was added in version 1.3.2.
  Fix: Upgrade to Tentaclio version 1.3.2 or later to utilize private key path and password query parameters for SFTP connections. For older versions, configure SFTP authentication via environment variables or a secrets file.
• gotcha The `tentaclio.db` function for database connections has specific handling for some URL formats. For instance, for PostgreSQL, a URL like `postgresql://host/database::table` implies writing from a CSV format into a database table, where the table name is specified after `::`.
  Fix: Consult the documentation for specific database URL formats and their implications for read/write operations, especially when dealing with table names embedded in the URL path.

Install

• pip install tentaclio Base installation
• pip install tentaclio[s3,gs,postgres] Install with S3, Google Storage, and PostgreSQL support

Imports

• open

  import tentaclio
  with tentaclio.open('file:///path/to/file.txt') as reader:

  The primary function for opening stream-like resources via URL.
• db

  import tentaclio
  with tentaclio.db('postgresql://hostname/example') as client:

  Used for establishing database connections via URL.
• copy

  import tentaclio
  tentaclio.copy('file:///local/source.txt', 's3://my-bucket/remote/dest.txt')

  Copies data between any supported Tentaclio URLs.

Quickstart

This quickstart demonstrates how to use `tentaclio.open` to write and read from a local file. It also includes commented-out code showing how to interact with cloud storage like S3, highlighting Tentaclio's 'automagic authentication' feature via environment variables (e.g., `TENTACLIO__CONN__PREFIX`). For S3 and other cloud protocols, ensure the corresponding optional dependencies are installed.

import tentaclio
import os

# Example: Write and then read a local file
local_file_url = 'file:///tmp/my_data.txt'
contents_to_write = 'Hello, Tentaclio! 👋🐙'

# Write to a local file
with tentaclio.open(local_file_url, mode='w') as writer:
    writer.write(contents_to_write)
print(f"Written to {local_file_url}")

# Read from the local file
with tentaclio.open(local_file_url, mode='r') as reader:
    read_contents = reader.read()
print(f"Read from {local_file_url}: {read_contents}")

# Clean up the test file
os.remove('/tmp/my_data.txt')
print("Cleaned up /tmp/my_data.txt")

# Example: Reading from an S3 bucket (requires tentaclio[s3] and AWS credentials)
# Set environment variables like:
# os.environ['TENTACLIO__CONN__MY_S3_BUCKET'] = 's3://access_key:secret_key@s3.region.amazonaws.com/my-bucket/'
# s3_url = 's3://my-bucket/hello.txt'
# if os.environ.get('TENTACLIO__CONN__MY_S3_BUCKET'):
#     try:
#         with tentaclio.open(s3_url) as reader:
#             s3_contents = reader.read()
#         print(f"Read from S3: {s3_contents}")
#     except Exception as e:
#         print(f"Could not read from S3: {e}")