Metadata-Version: 2.2
Name: livecsv
Version: 0.3
Summary: A custom SQLAlchemy dialect to load CSV from the web (using DuckDB for caching)
Author-email: Eyal Rahmani <eyal.rahmani@med.uni-heidelberg.de>
Maintainer-email: Eyal Rahmani <eyal.rahmani@med.uni-heidelberg.de>
License: MIT License
        
        Copyright (c) 2025 eyal-erknet
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/eyal-erknet/livecsv
Project-URL: Repository, https://github.com/eyal-erknet/livecsv.git
Keywords: sqlalchemy,sql,csv,duckdb
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: SQLAlchemy
Requires-Dist: duckdb
Requires-Dist: duckdb_engine

# livecsv

**livecsv** is a custom SQLAlchemy dialect that loads CSV data from a remote source into an in‑memory DuckDB instance with caching support. It is designed for read‑only use and allows you to query CSV data as if it were a relational table.

## Installation

Install livecsv using pip:

```bash
pip install livecsv
```

Dependencies

livecsv depends on the following packages:
•	SQLAlchemy
•	duckdb
•	duckdb_engine

These dependencies will be automatically installed when you install livecsv.

## Usage

The livecsv dialect lets you create a SQLAlchemy engine with a custom connection string that loads CSV data from a remote URL. The CSV is loaded into an in‑memory DuckDB instance, and the data is cached for a configurable number of minutes.

Connection String Format

The connection string format for livecsv is:

livecsv://<ssl_mode>/<cache_minutes>/<table_name>/<csv_url>

•	ssl_mode: Either secure (for HTTPS) or insecure (for HTTP).
•	cache_minutes: The number of minutes to cache the CSV data before refreshing. If 0, it is unlimited (not refreshed).
•	table_name: The name of the table that will be created in the in‑memory database.
•	csv_url: The URL to the CSV file (if the URL does not start with http, a scheme will be automatically prepended based on the ssl_mode).

## Example

Below is a sample code snippet that demonstrates how to use livecsv:

from sqlalchemy import create_engine, text

# Create an engine using the livecsv dialect.
engine = create_engine(
    "livecsv://secure/10/usernames/support.staffbase.com/hc/en-us/article_attachments/360009197031/username.csv"
)

# Query the table created from the CSV.
with engine.connect() as conn:
    result = conn.execute(text("SELECT * FROM usernames LIMIT 1")).fetchall()
    for row in result:
        print(row)

In this example, livecsv:
•	Loads the CSV from the specified URL.
•	Creates a table named usernames.
•	Caches the data for 10 minutes.
•	Allows you to query the data using SQLAlchemy.

## Testing with pytest

livecsv includes tests that can be run using pytest.

Steps to Run Tests
1.	Install pytest (if you haven’t already):

```bash
pip install pytest
```

2.	Run pytest
From the root of your project, run:

```bash
pytest
```

## License

This project is licensed under the MIT License. See the LICENSE file for details.

## Author
Eyal Rahmani
