{"id":3828,"library":"tentaclio","title":"Tentaclio","description":"Tentaclio is a Python library designed to unify data connectors for distributed data tasks, offering a consistent API for interacting with various data sources like local files, FTP, SFTP, S3, GCS, and databases. It provides a simple URL-based interface for streams and database connections. The library is actively maintained with frequent minor releases to address security updates and improve functionality.","status":"active","version":"1.4.1","language":"en","source_language":"en","source_url":"https://github.com/octoenergy/tentaclio","tags":["data-connectors","etl","streams","filesystem","sftp","s3","gcs","databases","url-parsing"],"install":[{"cmd":"pip install tentaclio","lang":"bash","label":"Base installation"},{"cmd":"pip install tentaclio[s3,gs,postgres]","lang":"bash","label":"Install with S3, Google Storage, and PostgreSQL support"}],"dependencies":[{"reason":"Runtime environment","package":"Python","minimum_version":"3.9"},{"reason":"Optional: For Amazon S3 protocol support","package":"s3","optional":true},{"reason":"Optional: For Google Storage protocol support","package":"gs","optional":true},{"reason":"Optional: For Google Drive protocol support","package":"gdrive","optional":true},{"reason":"Optional: For PostgreSQL database connections","package":"postgres","optional":true},{"reason":"Optional: For AWS Athena database connections","package":"athena","optional":true},{"reason":"Optional: For Databricks connections","package":"databricks","optional":true},{"reason":"Optional: For Snowflake database connections","package":"snowflake","optional":true}],"imports":[{"note":"The primary function for opening stream-like resources via URL.","symbol":"open","correct":"import tentaclio\nwith tentaclio.open('file:///path/to/file.txt') as reader:"},{"note":"Used for establishing database connections via URL.","symbol":"db","correct":"import tentaclio\nwith tentaclio.db('postgresql://hostname/example') as client:"},{"note":"Copies data between any supported Tentaclio URLs.","symbol":"copy","correct":"import tentaclio\ntentaclio.copy('file:///local/source.txt', 's3://my-bucket/remote/dest.txt')"}],"quickstart":{"code":"import tentaclio\nimport os\n\n# Example: Write and then read a local file\nlocal_file_url = 'file:///tmp/my_data.txt'\ncontents_to_write = 'Hello, Tentaclio! 👋🐙'\n\n# Write to a local file\nwith tentaclio.open(local_file_url, mode='w') as writer:\n    writer.write(contents_to_write)\nprint(f\"Written to {local_file_url}\")\n\n# Read from the local file\nwith tentaclio.open(local_file_url, mode='r') as reader:\n    read_contents = reader.read()\nprint(f\"Read from {local_file_url}: {read_contents}\")\n\n# Clean up the test file\nos.remove('/tmp/my_data.txt')\nprint(\"Cleaned up /tmp/my_data.txt\")\n\n# Example: Reading from an S3 bucket (requires tentaclio[s3] and AWS credentials)\n# Set environment variables like:\n# os.environ['TENTACLIO__CONN__MY_S3_BUCKET'] = 's3://access_key:secret_key@s3.region.amazonaws.com/my-bucket/'\n# s3_url = 's3://my-bucket/hello.txt'\n# if os.environ.get('TENTACLIO__CONN__MY_S3_BUCKET'):\n#     try:\n#         with tentaclio.open(s3_url) as reader:\n#             s3_contents = reader.read()\n#         print(f\"Read from S3: {s3_contents}\")\n#     except Exception as e:\n#         print(f\"Could not read from S3: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Install `tentaclio` with the specific extras needed for your protocols, e.g., `pip install tentaclio[s3,gs,postgres]`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<1.3.2"},{"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.","message":"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 `::`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}