Metadata-Version: 2.1
Name: superfile
Version: 0.0.5
Summary: File-like interface for cloud block storage
Author: Fresho Dev
License: MIT License
        
        Copyright (c) 2023 Fresho Dev
        
        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.
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: boto3
Requires-Dist: boto3-stubs[essential]
Requires-Dist: google-cloud-storage

# Superfile

Simple Python file-like interface for cloud block storage. This is unlikely to be the most
performant way do I/O with data from block storage, but it provides a uniform, simple API that can
be used across multiple cloud block storage providers such as Google Cloud Storage, Amazon S3 and
Azure Blob Storage.

## Simple Usage

Importing the main module:

```python
import superfile
```

Reading a local file:

```python
with superfile.open('my/local/path', 'r') as f:
  contents = f.read()
```

Reading a text file:

```python
with superfile.open('gs://my_bucket_name/file.txt', 'r') as f:
  text = f.read()
```

Reading a binary file:

```python
with superfile.open('gs://my_bucket_name/file.ext', 'rb') as f:
  data = f.read()
```

Writing a text file:

```python
text = 'hello world'
with superfile.open('gs://my_bucket_name/file.txt', 'w') as f:
  f.write(text)
```

Writing a binary file:

```python
data = b'hello world'
with superfile.open('gs://my_bucket_name/file.txt', 'wb') as f:
  f.write(data)
```

Listing all files in a bucket:

```python
fnames = list(superfile.list('gs://my_bucket_name'))
```

Listing files with a prefix from a bucket:

```python
prefix = 'abc'
fnames = list(superfile.list(f'gs://my_bucket_name/{prefix}'))
```

## Advanced Usage

Reading a file from GCS and providing auth credentials:

```python
import superfile
from google.oauth2 import service_account

fpath = 'gs://my_bucket_name/file.txt'
creds = service_account.Credentials.from_service_account_file('/path/to/key.json')
with superfile.open(
  path=fpath,
  mode='r',
  # All init_kwargs are passed to google.cloud.storage.Client.__init__().
  init_kwargs=dict(credentials=creds),
  # All open_kwargs are passed to google.cloud.storage.Blob.open().
  open_kwargs=dict(errors='strict'),
) as f:
  ...
```

Reading a file from S3 and providing endpoint URL:

```python
import superfile

fpath = 's3://my_bucket_name/file.txt'
endpoint_url = 'https://example.com'
with superfile.open(
  path=fpath,
  mode='r',
  # All init_kwargs are passed to boto3.client().
  init_kwargs=dict(endpoint_url=endpoint_url),
  # All open_kwargs are passed to boto3.client.get_object() or boto3.client.put_object().
  open_kwargs=dict(VersionId='...'),
) as f:
  ...

```
