Metadata-Version: 2.4
Name: squirl
Version: 0.0.1
Summary: SQL ORM and query builder for the SB stack
Author: Maintainers
Author-email: solubrew@solutionsbrewer.com
License: MIT
Platform: Linux
Requires-Python: >=3.7
Requires-Dist: defusedxml; platform_system == "Windows"
Requires-Dist: futures; python_version < "3"
Requires-Dist: six; platform_system == "Linux" and python_version > "3.3"
Requires-Dist: pypiwin32; platform_system == "Windows"
Requires-Dist: annotated-doc==0.0.4
Requires-Dist: astor==0.8.1
Requires-Dist: asyncpg==0.31.0
Requires-Dist: attrs==26.1.0
Requires-Dist: backoff==2.2.1
Requires-Dist: beautifulsoup4==4.14.2
Requires-Dist: black==26.3.1
Requires-Dist: bs4==0.0.2
Requires-Dist: certifi==2026.2.25
Requires-Dist: cffi==2.0.0
Requires-Dist: charset-normalizer==3.4.7
Requires-Dist: click==8.3.3
Requires-Dist: decorator==5.2.1
Requires-Dist: dill==0.4.1
Requires-Dist: diskcache==5.6.3
Requires-Dist: dnspython==2.8.0
Requires-Dist: html5lib==1.1
Requires-Dist: toml==0.10.2
Requires-Dist: idna==3.11
Requires-Dist: imageio==2.37.3
Requires-Dist: imageio-ffmpeg==0.6.0
Requires-Dist: iniconfig==2.3.0
Requires-Dist: joblib==1.5.3
Requires-Dist: jsonschema==4.23.0
Requires-Dist: jsonschema-specifications==2025.9.1
Requires-Dist: lxml==6.1.0
Requires-Dist: markdown-it-py==4.0.0
Requires-Dist: mdurl==0.1.2
Requires-Dist: moviepy==2.2.1
Requires-Dist: mypy-extensions==1.1.0
Requires-Dist: mysql-connector-python==9.7.0
Requires-Dist: networkx==3.6.1
Requires-Dist: numpy==2.2.6
Requires-Dist: opencv-python==4.13.0.90
Requires-Dist: packaging==26.0
Requires-Dist: pandas==2.3.3
Requires-Dist: pathspec==1.1.1
Requires-Dist: pdfkit==1.0.0
Requires-Dist: pillow==11.3.0
Requires-Dist: platformdirs==4.9.6
Requires-Dist: pluggy==1.6.0
Requires-Dist: proglog==0.1.12
Requires-Dist: psycopg2-binary==2.9.12
Requires-Dist: pyarrow==24.0.0
Requires-Dist: pycparser==3.0
Requires-Dist: pygments==2.20.0
Requires-Dist: pyodbc==5.3.0
Requires-Dist: pytest==9.0.3
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: pytokens==0.4.1
Requires-Dist: pyyaml==6.0.3
Requires-Dist: referencing==0.37.0
Requires-Dist: requests==2.33.1
Requires-Dist: rich==14.3.4
Requires-Dist: rpds-py==0.30.0
Requires-Dist: ruamel-yaml==0.19.1
Requires-Dist: scikit-learn==1.8.0
Requires-Dist: scipy==1.17.1
Requires-Dist: send2trash==2.1.0
Requires-Dist: shellingham==1.5.4
Requires-Dist: six==1.17.0
Requires-Dist: soupsieve==2.8.3
Requires-Dist: threadpoolctl==3.6.0
Requires-Dist: tqdm==4.67.3
Requires-Dist: typer==0.24.1
Requires-Dist: typing-extensions==4.15.0
Requires-Dist: urllib3==2.6.3
Requires-Dist: uuid7==0.1.0
Requires-Dist: webencodings==0.5.1
Requires-Dist: webp==0.4.0
Requires-Dist: websockets==16.0
Requires-Dist: tzdata==2026.1
Requires-Dist: pytz==2026.1.post1
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: pylint ; extra == "dev"
Requires-Dist: ruff ; extra == "dev"
Requires-Dist: black ; extra == "dev"
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: bandit ; extra == "dev"
Provides-Extra: dev
Description: # SQuiRL
        
        SQuiRL is a Python library for interacting with any type of data storage structure, including filesystems, databases, caches, and various text file types. It provides a unified API to read, write, query, and manage data across diverse storage systems, abstracting away the complexities of different backends for seamless integration in applications.
        
        ## Features
        
        - **Unified Interface**: Interact with filesystems (local, remote), databases (SQL, NoSQL), caches (in-memory, distributed), and text files (CSV, JSON, XML, etc.) through a consistent Pythonic API.
        - **Extensible Backends**: Support for multiple storage types with pluggable adapters; easily add custom backends.
        - **Data Operations**: Perform CRUD (Create, Read, Update, Delete) operations, queries, and transformations across storage structures.
        - **Configuration-Driven**: Use YAML or Python configs to define storage connections and behaviors.
        - **Cross-Platform Compatibility**: Works on Windows, macOS, and Linux.
        - **Error Handling and Logging**: Built-in mechanisms for robust error management and detailed logging.
        - **Performance Optimizations**: Efficient handling for large datasets, batch operations, and caching layers.
        
        ## Installation
        
        You can install SQuiRL via pip:
        
        ```bash
        pip install squirrl
        ```
        
        Alternatively, clone the repository and install from source:
        
        ```bash
        git clone https://github.com/<USER_OR_ORG>/squirrl.git
        cd squirrl
        pip install -e .
        ```
        
        ### Requirements
        
        - Python 3.<MIN_VERSION> or higher
        - Dependencies: pyyaml, <DB_LIB>, <CACHE_LIB>, <FILE_LIB> (automatically installed via pip where applicable)
        
        ## Quick Start
        
        Import the module, configure a storage backend, and perform operations:
        
        ```python
        import squirrl
        
        # Load configuration for a storage type
        config = squirrl.load_config('path/to/filesystem.yaml')
        
        # Initialize the storage interface
        storage = squirrl.Storage(config)
        
        # Write data
        storage.write('key/path', 'Hello, World!')
        
        # Read data
        data = storage.read('key/path')
        print(data)  # Output: Hello, World!
        ```
        
        ## Usage
        
        ### Loading Configurations
        
        SQuiRL relies on YAML files to define storage backends. A sample YAML for a database might look like:
        
        ```yaml
        storage_type: database
        backend: <DB_LIB>
        connection:
          host: localhost
          port: 5432
          user: <USER>
          password: <PASS>
          db_name: mydb
        operations:
          query: sql_query_method
          insert: insert_method
        ```
        
        Use `squirrl.load_config(yaml_path)` to parse and validate the config.
        
        ### Interacting with Storage
        
        ```python
        # Initialize with config
        config = squirrl.load_config('cache.yaml')
        cache = squirrl.Storage(config)
        
        # Set and get cache values
        cache.set('user_data', {'id': 1, 'name': 'Alice'})
        value = cache.get('user_data')
        
        # Delete
        cache.delete('user_data')
        ```
        
        ### Handling Different Storage Types
        
        - **Filesystems**: Local directories, S3 buckets, etc.
        - **Databases**: SQLite, PostgreSQL, MongoDB, etc.
        - **Caches**: Redis, Memcached, in-memory dicts.
        - **Text Files**: Read/write CSV, JSON, YAML, XML with parsing support.
        
        ```python
        # Example with text file
        config = squirrl.load_config('json_file.yaml')
        file_storage = squirrl.Storage(config)
        data = file_storage.read('data.json')  # Returns parsed dict
        file_storage.write('data.json', {'key': 'value'})
        ```
        
        ## Examples
        
        ### Example 1: Database Querying
        
        ```python
        import squirrl
        
        config = squirrl.load_config('database.yaml')
        db = squirrl.Storage(config)
        db.connect()
        
        # Execute query
        results = db.query('SELECT * FROM users WHERE active = ?', (True,))
        
        # Insert data
        db.insert('INSERT INTO users (name, active) VALUES (?, ?)', ('Bob', True))
        
        db.close()
        ```
        
        ### Example 2: Multi-Storage Workflow
        
        ```python
        import squirrl
        
        configs = ['filesystem.yaml', 'cache.yaml']
        storages = [squirrl.Storage(squirrl.load_config(cfg)) for cfg in configs]
        
        # Read from filesystem, cache it
        data = storages[0].read('file.txt')
        storages[1].set('cached_file', data)
        
        # Retrieve from cache
        cached_data = storages[1].get('cached_file')
        ```
        
        ## Configuration Guide
        
        Each YAML config must include:
        
        - `storage_type`: String identifier (e.g., 'filesystem', 'database', 'cache', 'textfile')
        - `backend`: The underlying library or driver (e.g., '<FS_LIB>', '<DB_LIB>')
        - `connection`: Dictionary of connection parameters
        - `operations`: Mapping of SQuiRL methods to backend-specific calls
        
        For advanced customization, refer to the [docs/config-reference.md](docs/config-reference.md).
        
        ## Contributing
        
        Contributions are welcome! Please follow these steps:
        
        1. Fork the repository.
        2. Create a feature branch (`git checkout -b feature/<FEATURE_NAME>`).
        3. Commit your changes (`git commit -am 'Add some feature'`).
        4. Push to the branch (`git push origin feature/<FEATURE_NAME>`).
        5. Open a Pull Request.
        
        See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
        
        ## License
        
        This project is licensed under the <LICENSE_TYPE> License - see the [LICENSE](LICENSE) file for details.
        
        ## Acknowledgments
        
        - Built with inspiration from open-source data handling communities.
        - Thanks to contributors of underlying libraries like <DB_LIB>, <CACHE_LIB>, <FILE_LIB>.
Description-Content-Type: text/markdown
