Boto3 S3 на Python: базовые примеры

Boto3 позволяет работать с Amazon S3 из Python: загружать файлы, скачивать объекты, получать список ключей, удалять файлы и обрабатывать ошибки доступа. Для запуска нужны учетные данные AWS и права на нужный bucket

Не храните access key и secret key прямо в коде. Используйте переменные окружения, AWS CLI profile, IAM role или другой безопасный способ, который подходит вашему окружению

По этой теме полезно отдельно посмотреть Составьте еженедельное расписание занятий, чтобы расширить контекст и сравнить подходы

По этой теме полезно отдельно посмотреть Аннотации типов для декораторов в Python, чтобы расширить контекст и сравнить подходы

Установка

pip install boto3

Если вы работаете локально, чаще всего сначала настраивают AWS CLI:

aws configure

После этого boto3.client('s3') сможет взять credentials из стандартного окружения AWS

Создать S3 client

import boto3

s3 = boto3.client('s3')

Если нужен конкретный регион:

s3 = boto3.client('s3', region_name='eu-central-1')

В большинстве примеров ниже используются переменные:

bucket = 'my-bucket'

Замените my-bucket на имя своего bucket

Загрузить файл в S3

import boto3

s3 = boto3.client('s3')

s3.upload_file(
    Filename='report.txt',
    Bucket='my-bucket',
    Key='reports/report.txt',
)

print('Файл загружен')

Filename — локальный файл на компьютере. Bucket — имя bucket. Key — путь объекта внутри S3

S3 не является обычной папкой на диске. reports/report.txt — это ключ объекта, который визуально выглядит как путь

Скачать файл из S3

import boto3

s3 = boto3.client('s3')

s3.download_file(
    Bucket='my-bucket',
    Key='reports/report.txt',
    Filename='downloaded-report.txt',
)

print('Файл скачан')

Если ключ не существует или у пользователя нет прав, boto3 выбросит ошибку

Получить список объектов

import boto3

s3 = boto3.client('s3')

response = s3.list_objects_v2(
    Bucket='my-bucket',
    Prefix='reports/',
)

for item in response.get('Contents', []):
    print(item['Key'], item['Size'])

response.get('Contents', []) нужен, потому что если объектов нет, поля Contents может не быть

Для bucket с большим количеством объектов понадобится пагинация. Но для первого примера list_objects_v2() достаточно

Прочитать объект как текст

Иногда файл не нужно сохранять на диск, достаточно прочитать содержимое

import boto3

s3 = boto3.client('s3')

response = s3.get_object(
    Bucket='my-bucket',
    Key='reports/report.txt',
)

text = response['Body'].read().decode('utf-8')

print(text)

Так удобно читать маленькие JSON, CSV или текстовые файлы. Для больших файлов лучше продумать потоковую обработку

Загрузить строку как объект

import boto3

s3 = boto3.client('s3')

s3.put_object(
    Bucket='my-bucket',
    Key='reports/status.txt',
    Body='готово'.encode('utf-8'),
    ContentType='text/plain; charset=utf-8',
)

print('Объект создан')

put_object() удобен, когда данные уже находятся в памяти и не нужно читать локальный файл

Удалить объект

import boto3

s3 = boto3.client('s3')

s3.delete_object(
    Bucket='my-bucket',
    Key='reports/status.txt',
)

print('Объект удален')

Будьте аккуратны с удалением. В учебных примерах используйте отдельный bucket или тестовый prefix

Обработка ошибок ClientError

import boto3
from botocore.exceptions import ClientError

s3 = boto3.client('s3')

try:
    s3.download_file(
        Bucket='my-bucket',
        Key='reports/missing.txt',
        Filename='missing.txt',
    )
except ClientError as error:
    code = error.response['Error']['Code']
    print(f'Ошибка S3: {code}')

Через ClientError можно поймать отсутствие прав, несуществующий объект, неправильный bucket и другие ответы AWS

Пагинация списка объектов

Если объектов много, одного list_objects_v2() может быть недостаточно. Тогда используйте paginator

import boto3

s3 = boto3.client('s3')
paginator = s3.get_paginator('list_objects_v2')

for page in paginator.paginate(Bucket='my-bucket', Prefix='reports/'):
    for item in page.get('Contents', []):
        print(item['Key'])

Paginator сам делает несколько запросов и возвращает страницы результата. Это важнее для production-скриптов, где в bucket могут быть сотни или тысячи объектов

Мини-функции для повторного использования

Даже в маленьком скрипте полезно вынести операции в функции

import boto3

s3 = boto3.client('s3')

def upload_report(local_path, bucket, key):
    s3.upload_file(local_path, bucket, key)
    return key

def list_keys(bucket, prefix=''):
    response = s3.list_objects_v2(Bucket=bucket, Prefix=prefix)
    return [item['Key'] for item in response.get('Contents', [])]

Так код легче тестировать и менять. Например, можно заменить bucket, prefix или добавить логирование в одном месте

Частые ошибки

Хранить ключи доступа в коде

Путать имя bucket и key объекта

Не проверять IAM-права

Ожидать поле Contents в пустом ответе list_objects_v2()

Не учитывать регион bucket

Удалять объекты без тестового prefix

Практические задачи

Загрузите локальный report.txt в prefix reports/

Выведите список объектов с размером

Скачайте объект в новый локальный файл

Прочитайте маленький текстовый объект через get_object()

Добавьте обработку ClientError

Удалите тестовый объект после проверки

Базовая работа с S3 через boto3 строится вокруг boto3.client('s3') и методов upload_file(), download_file(), list_objects_v2(), get_object(), put_object() и delete_object()

Главное — не хранить секреты в коде, правильно различать bucket и key, проверять права IAM и обрабатывать ошибки AWS через ClientError