Metadata-Version: 2.4
Name: pyaws_s3
Version: 1.0.11
Summary: A Python package for AWS S3 utilities
Author-email: Giuseppe Zileni <giuseppe.zileni@gmail.com>
Keywords: aws,s3,utilities
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: aioboto3==14.3.0
Requires-Dist: aiobotocore==2.22.0
Requires-Dist: aiofiles==24.1.0
Requires-Dist: aiohappyeyeballs==2.6.1
Requires-Dist: aiohttp==3.11.18
Requires-Dist: aioitertools==0.12.0
Requires-Dist: aiosignal==1.3.2
Requires-Dist: attrs==25.3.0
Requires-Dist: boto3==1.37.3
Requires-Dist: botocore==1.37.3
Requires-Dist: build==1.2.2.post1
Requires-Dist: chardet==5.2.0
Requires-Dist: contourpy==1.3.2
Requires-Dist: cycler==0.12.1
Requires-Dist: fonttools==4.58.0
Requires-Dist: fpdf==1.7.2
Requires-Dist: frozenlist==1.6.0
Requires-Dist: idna==3.10
Requires-Dist: iniconfig==2.1.0
Requires-Dist: jmespath==1.0.1
Requires-Dist: kiwisolver==1.4.8
Requires-Dist: matplotlib==3.10.3
Requires-Dist: multidict==6.4.3
Requires-Dist: narwhals==1.39.1
Requires-Dist: numpy==2.2.5
Requires-Dist: packaging==25.0
Requires-Dist: pandas==2.2.3
Requires-Dist: pillow==11.2.1
Requires-Dist: plotly==6.1.0
Requires-Dist: pluggy==1.6.0
Requires-Dist: propcache==0.3.1
Requires-Dist: pyparsing==3.2.3
Requires-Dist: pyproject_hooks==1.2.0
Requires-Dist: pytest==8.3.5
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: pytz==2025.2
Requires-Dist: reportlab==4.4.1
Requires-Dist: s3transfer==0.11.3
Requires-Dist: setuptools==80.7.1
Requires-Dist: six==1.17.0
Requires-Dist: tzdata==2025.2
Requires-Dist: urllib3==2.4.0
Requires-Dist: wrapt==1.17.2
Requires-Dist: yarl==1.20.0
Dynamic: license-file

# PYAWS_S3

## Description

`S3Client` is a Python class that simplifies interaction with AWS S3 for uploading, downloading, managing, and deleting files. It supports uploading images, DataFrames, PDFs, generating pre-signed URLs, downloading files, listing files, and deleting individual files.

## Installation

Make sure you have installed:

```bash
pip install pyaws_s3
```

### Env Variables

Make sure to add these environment variables:

```bash
AWS_ACCESS_KEY_ID=<Your Access Key Id>
AWS_SECRET_ACCESS_KEY=<Your Secret Access Key>
AWS_REGION=<Your Region>
AWS_BUCKET_NAME=<Your Bucket Name>
```

## Usage

### Initialization

You can initialize the class by passing AWS credentials as parameters or via environment variables:

```python
from s3_client import S3Client

s3 = S3Client(
    aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"),
    aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
    region_name=os.getenv("AWS_REGION"),
    bucket_name=os.getenv("AWS_BUCKET_NAME")
)
```

### Main Methods

#### 1. `upload_image(fig, object_name, format_file=Literal["png", "jpeg", "svg", "html"])`

Uploads a figure (e.g., Matplotlib or Plotly) to S3 as an image (svg, png, jpeg, html).

```python
url = s3.upload_image(fig, "folder/image.svg", format_file="svg")
```

#### 2. `upload_from_dataframe(df, object_name, format_file=Literal["xlsx", "csv", "pdf"])`

Uploads a DataFrame to S3 as an Excel, CSV, or PDF file.

```python
url = s3.upload_from_dataframe(df, "folder/data", format_file="csv")
```

#### 3. `upload_to_pdf(text, object_name)`

Exports text to PDF and uploads it to S3.

```python
url = s3.upload_to_pdf("Text to export", "folder/file.pdf")
```

#### 4. `await delete_all(filter=None)`

Deletes all files from the bucket, optionally filtering by name.

```python
import asyncio
await s3.delete_all(filter="your_filter")
```

#### 5. `download(object_name, local_path=None, stream=False)`

Downloads a file from the S3 bucket.

- `object_name` (str): The name of the S3 object to download.
- `local_path` (str, optional): Local path to save the downloaded file. Required if `stream` is False.
- `stream` (bool, optional): If True, returns the file content as bytes instead of saving locally.

**Examples:**

Download and save locally:

```python
local_path = s3.download("folder/image.svg", local_path="downloads/")
```

Download as bytes (stream):

```python
file_bytes = s3.download("folder/image.svg", stream=True)
```

#### 6. `list_files(filter=None) -> list[str]`

Lists all files in the S3 bucket, optionally filtered by a substring.

- `filter` (str, optional): Only files containing this substring will be listed.

**Example:**

```python
files = s3.list_files(filter="folder/")
```

#### 7. `delete_file(object_name)`

Deletes a single file from the S3 bucket.

- `object_name` (str): The name of the S3 object to delete.

**Example:**

```python
s3.delete_file("folder/image.svg")
```

## Notes

- All upload methods return a pre-signed URL for downloading the file.
- Integrated error handling with logging.
- For uploading images and DataFrames, utility functions are required (`bytes_from_figure`, `html_from_figure`).

## Complete Example

```python
import matplotlib.pyplot as plt
import pandas as pd

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [4, 5, 6])

df = pd.DataFrame({"a": [1, 2], "b": [3, 4]})

s3 = S3Client(bucket_name="my-bucket")
img_url = s3.upload_image(fig, "test.svg")
df_url = s3.upload_from_dataframe(df, "mydata")
pdf_url = s3.upload_to_pdf("Hello PDF", "hello.pdf")

# Download a file
local_path = s3.download("test.svg", local_path="downloads/test.svg")

# List files
files = s3.list_files()

# Delete a file
s3.delete_file("test.svg")
```
