Metadata-Version: 2.4
Name: light-s3-client
Version: 0.0.27
Summary: A lightweight S3 client.
Author: Douglas Coburn
Author-email: Douglas Coburn <douglas@dactbc.com>
Maintainer-email: Douglas Coburn <douglas@dactbc.com>
License: MIT License
        
        Copyright (c) 2023 Douglas Coburn
        
        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.
        
Keywords: s3,aws,client,lightweight
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: requests~=2.31.0
Requires-Dist: xmltodict~=0.13.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file


light-s3-client
###############

Purpose
-------
The AWS Boto3 Client is quite heavy, and usually specific functionality is needed. This module only implements needed functionality uses the requests library and the S3 Resp API.

Reference doc used for this creation: https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html#signing-request-intro

*Note: The parameter names and function names were copied from the Boto3 S3 Client. It does necessarily have all the options for the function*

Supported Functions
-------------------

Client.download_file(Bucket, Key, Filename)
""""""""""""""""""""""""""""""""""""""""""""""

Download an S3 object to a file

**Usage:**

.. code-block:: python

    from light_s3_client import Client

    s3 = Client(
        region="us-west-1",
        access_key="REPLACE_ME",
        secret_key="REPLACE_ME"
    )
    s3.download_file("mybucket", "hello.txt", "/tmp/hello.txt")



**PARAMETERS:**

- **Bucket (str)** – The name of the bucket to download from.
- **Key (str)** – The name of the key to download from. 
- **Filename (str)** – The path to the file to download to.

Client.upload_fileobj(Fileobj, Bucket, Key)
"""""""""""""""""""""""""""""""""""""""""""

Upload a File Object to S3

**Usage:**

.. code-block:: python

    from light_s3_client import Client
    import json


    def get_file_contents(file_name) -> bytes:
        file_handle = open(file_name, "r")
        content = json.load(file_handle)
        str_content = json.dumps(content)
        file_handle.close()
        data = str_content.encode("utf-8")
        return data


    s3 = Client(
        region="us-west-1",
        access_key="REPLACE_ME",
        secret_key="REPLACE_ME"
    )
    upload_data = get_file_contents("example.json")
    s3.upload_fileobj(upload_data, "example-bucket", "path/example.json")

**PARAMETERS:**

- **Fileobj (a file-like object)** – A file-like object to upload. At a minimum, it must implement the read method, and must return bytes.
- **Bucket (str)** – The name of the bucket to upload to. 
- **Key (str)** – The name of the key to upload to.

Client.delete_object(Bucket, Key)
"""""""""""""""""""""""""""""""""

Delete a S3 object

**Usage:**

.. code-block:: python

    from light_s3_client import Client

    s3 = Client(
        region="us-west-1",
        access_key="REPLACE_ME",
        secret_key="REPLACE_ME"
    )
    s3.delete_file("example-bucket", "path/example.json")

**PARAMETERS:**

- **Bucket (str)** – The name of the bucket to upload to. 
- **Key (str)** – The name of the key to upload to.(Fileobj, Bucket, Key)

Client.list_objects(Bucket, Prefix)
"""""""""""""""""""""""""""""""""""

Lists all keys in an object

**Usage:**

.. code-block:: python

    from light_s3_client import Client

    s3 = Client(
        region="us-west-1",
        access_key="REPLACE_ME",
        secret_key="REPLACE_ME"
    )
    keys = s3.list_objects("example-bucket", "prefix")

**PARAMETERS:**

- **Bucket (str)** – The name of the bucket to upload to.
- **Prefix (str)** – The prefix to use as the search for getting keys from the bucket

Client.get_object(Bucket, Key)
""""""""""""""""""""""""""""""

Returns if an object exists or not

**Usage:**

.. code-block:: python

    from light_s3_client import Client

    s3 = Client(
        region="us-west-1",
        access_key="REPLACE_ME",
        secret_key="REPLACE_ME"
    )
    keys = s3.get_object("example-bucket", "path/file.txt")

**PARAMETERS:**

- **Bucket (str)** – The name of the bucket to upload to.
- **Key (str)** – The key to check if it exists in the bucket


Client Parameters
"""""""""""""""""

========== ======== ====== =========================================================================
property   Required type   description
========== ======== ====== =========================================================================
region     True     string The S3 region being used. This ends up as part of the Server URL
access_key True     string The AWS Access Key for API Access
secret_key True     string The AWS Secret Key for API Access
server     False    string An override of the HTTPS URL to use. When used then `region` is not used
========== ======== ====== =========================================================================


