Metadata-Version: 2.2
Name: hopeit.aws.s3
Version: 0.3.0rc0
Summary: Hopeit Engine S3 Storage Toolkit
Author-email: Leo Smerling & Pablo Canto <contact@hopeit.com.ar>, Leo Smerling <contact@hopeit.com.ar>, Pablo Canto <contact@hopeit.com.ar>
License: Apache 2
Project-URL: Homepage, https://github.com/hopeit-git/hopeit.aws
Project-URL: CI: GitHub Actions, https://github.com/hopeit-git/hopeit.aws/actions?query=workflow
Project-URL: GitHub: issues, https://github.com/hopeit-git/hopeit.aws/issues
Project-URL: GitHub: repo, https://github.com/hopeit-git/hopeit.aws
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: AsyncIO
Description-Content-Type: text/markdown
Requires-Dist: hopeit.engine>=0.25.4
Requires-Dist: aioboto3>=14.0.0

# hopeit.aws.s3 plugin

This library is part of hopeit.engine:

> visit: https://github.com/hopeit-git/hopeit.engine

This library provides a `ObjectStorage` class to store and retrieve `@dataobjects` and files from S3 and compatible services as a plugin for the popular [`hopeit.engine`](https://github.com/hopeit-git/hopeit.engine) reactive microservices framework.

It supports the `prefix` setting, which is a prefix to be used for every element (object or file) stored in the S3 bucket. This prefix can be used to organize and categorize stored data within the bucket. Additionally, it supports the `partition_dateformat` setting, which is a date format string used to prefix file names for partitioning saved files into different subfolders based on the event timestamp (event_ts()). For example, using `%Y/%m/%d` will store each data object in a folder structure like year/month/day/, providing a way to efficiently organize and retrieve data based on date ranges. These settings can be used together to achieve more granular organization of data within the bucket.

### Installation

Python library that provides helpers to store and retrieve `@dataobjects` and files to S3-compatible services

```bash
pip install hopeit.aws.s3
```

### Usage

```python
from hopeit.dataobjects import dataobject, dataclass
from hopeit.aws.s3 import ObjectStorage, ObjectStorageSettings, ConnectionConfig

# Create a connection configuration
conn_config = ConnectionConfig(
    aws_access_key_id="your-access-key-id",
    aws_secret_access_key="your-secret-access-key",
    region_name="your-region-name"
)

# Create settings for ObjectStorage
settings = ObjectStorageSettings(
    bucket="your-bucket-name",
    connection_config=conn_config
)

# Create an ObjectStorage instance
storage = ObjectStorage.with_settings(settings)

# Connect to the ObjectStorage
await storage.connect()

# hopeit.engine data object
@dataobject
@dataclass
class Something:
    key: str
    value: str

something = Something(key="my_key", value="some_value")

# Store a data object
await storage.store(key=something.key, value=something)

# Retrieve a data object
retrieved_object = await storage.get(key=something.key, datatype=Something)
print(retrieved_object)
```

## Example Usage

In the `apps/examples/aws-example/` directory, you can find a full example `hopeit.engine` app that demonstrates the usage of the `hopeit.aws.s3` plugin within the `hopeit.engine` framework. This example showcases how to store and retrieve `@dataobjects` and files from S3 using the `ObjectStorage` class.
