Metadata-Version: 2.4
Name: drb-driver-s3
Version: 1.4.0
Summary: DRB aws3 driver
Author: GAEL Systems
Author-email: drb-python@gael.fr
License: LGPLv3
Project-URL: Documentation, http://drb-python.gitlab.io/impl/aws3
Project-URL: Source, https://gitlab.com/drb-python/impl/aws3
Classifier: Programming Language :: Python :: 3.11
Classifier: Environment :: Plugins
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Requires-Dist: drb<3,>=2.3.9
Requires-Dist: drb-driver-http~=1.3.0
Requires-Dist: boto3<2,>=1.28
Requires-Dist: botocore<2,>=1.31
Dynamic: license-file

# Amazon simple storage service driver

This drb-driver-s3 module implements S3 protocol access with DRB data model.

## S3 Factory and S3 Node
The module implements the factory model defined in DRB in its node resolver. Based on the python entry point mechanism, this module can be dynamically imported into applications.

The entry point group reference is `drb.drivers.aws3`.<br/>
The driver name is `aws3`.<br/>
The factory class is encoded into `drb.drivers.aws3`.<br/>
The S3 signature id is  `4ab73f92-bbff-11ec-8422-0242ac120002`.<br/>


## Using this module
The project is present in https://www.pypi.org service. it can be freely 
loaded into projects with the following command line:

```commandline
pip install drb-driver-s3
```
## Access Data
`DrbS3Node` manages the s3 protocol to access remote data. The construction
parameter is an authentication object.

```python
from drb.drivers.aws3 import DrbS3Service, Auth
from botocore.config import Config

auth = Auth(service_name='s3',
            endpoint_url='http://your_s3_storage/',
            aws_access_key_id='user',
            aws_secret_access_key='password',
            config=Config(signature_version='s3v4'),
            region_name='us-east-1')
node = DrbS3Service(auth)
```
When accessing a DrbS3Service the node gives access to all the bucket of this service by giving a list of DrbS3Bucket,
and then each node gives a list of DrbS3Object for each object in the bucket.

## Resolving an `s3://` URL
An `s3://bucket/key` URL resolves to:

- a `DrbS3Service` for `s3://` (no bucket),
- a `DrbS3Bucket` for `s3://bucket` or any key ending with `/` (a prefix),
- a `DrbS3Object` for a key that is a **real object**.

When the key is *not* a real object, the factory raises `DrbFactoryException`
(it probes existence with a `HeadObject`). This lets the DRB resolver walk the
path segment by segment and descend an intermediate container instead of
building a bogus object node whose first read would `404`. It is what makes a
key that continues *inside* an archive resolvable, e.g.:

```python
from drb.topics.resolver import create
# descend into a zipped product on S3 and force the XML driver on a leaf
# that has no .xml extension:
node = create('s3+xml://bucket/product.zip/product.SAFE/manifest.safe')
```

The existence `HeadObject` is cached in the node context
(`node.context['resolver']['head']`) so opening the object stream does not
issue a second `HeadObject`.

## GDAL locator (`gdal-vsi`)

A `DrbS3Object` exposes a GDAL `/vsis3` locator through
`get_impl(str, 'gdal-vsi')` (`/vsis3/bucket/key`) and, as a side effect,
exposes the endpoint and credentials taken from the node's `Auth` to GDAL's
`/vsis3` handler via the standard `AWS_*` environment variables (no GDAL import
in this driver). This lets a consumer such as drb-driver-image hand an object
to GDAL for native range reads, and composes with the zip locator
(`/vsizip{/vsis3/bucket/key.zip}/inner.jp2`). The GDAL S3 configuration is
process-global, so a single credential set is assumed per process.

## Limitations

This driver doesn't allow to write, modify, delete file on a s3 bucket,
or it doesn't allow to delete or upload a file.
This driver doesn't allow to download directly a bucket.

## Documentation

The documentation of this implementation can be found here https://drb-python.gitlab.io/impl/aws3
