Este guia de referência explica a classe Client do pacote replit-object-storage-python e fornece exemplos de código para seus métodos de classe.
Client
A classe Client gerencia as interações com o Replit App Storage. Esta classe possui métodos para realizar operações em objetos em um bucket.
Para importar a classe do pacote replit.object_storage, adicione a seguinte linha ao seu código Python:
from replit.object_storage import Client
Client que interage com o Replit App Storage:
Se seu app usa múltiplos buckets, crie uma instância de Client por bucket.
__init__
O método init inicializa uma instância da classe Client.
def __init__(bucket_id: Optional[str] = None)
bucket_id (Optional[str]): O ID do bucket que o cliente gerencia. Quando omitido, o Client usa o bucket padrão associado ao Replit App ou Deployment.
copy
O método copy copia um objeto dentro do mesmo bucket. Se um objeto existir no mesmo local, ele sobrescreve o original.
def copy(object_name: str, dest_object_name: str) -> None
object_name (str) - O caminho completo do objeto de origem.dest_object_name (str) - O caminho completo do destino do objeto.
Exceções:
ObjectNotFoundError - Indica que o objeto de origem não existe no caminho especificado.
delete
O método delete remove permanentemente um arquivo do App Storage.
def delete(object_name: str, ignore_not_found: bool = False) -> None
object_name (str) - O nome do objeto a ser excluído.ignore_not_found (bool) - Quando True, suprime o erro se o objeto não existir.
Exceções:
ObjectNotFoundError - Indica que o objeto não existe.
download_as_bytes
O método download_as_bytes recupera o conteúdo de um arquivo como bytes.
def download_as_bytes(object_name: str) -> bytes
object_name (str) - O nome do objeto a ser baixado.
Retorna:
bytes - A representação bruta em bytes do conteúdo do objeto.
Exceções:
ObjectNotFoundError - Indica que o objeto não existe.
download_as_text
O método download_as_text faz o download do conteúdo de um arquivo como tipo str.
def download_as_text(object_name: str) -> str
object_name (str) - O nome do objeto de origem a ser recuperado.
Retorna:
- str: O conteúdo do objeto como uma string codificada em UTF-8.
Exceções:
ObjectNotFoundError - Indica que o objeto não existe.
download_to_filename
Faz o download do conteúdo de um objeto para um arquivo no disco local.
def download_to_filename(object_name: str, dest_filename: str) -> None
object_name (str) - O nome do objeto de origem no App Storage a ser recuperado.dest_filename (str) - O nome do arquivo de destino no disco local.
Exceções:
ObjectNotFoundError - Indica que o objeto não existe.
exists
O método exists verifica se um objeto existe.
def exists(object_name: str) -> bool
object_name (str) - O nome do objeto a ser verificado.
Retorna:
bool: True se o objeto existir, False caso contrário.
list
O método list lista os objetos no Bucket.
def list(end_offset: Optional[str] = None,
match_glob: Optional[str] = None,
max_results: Optional[int] = None,
prefix: Optional[str] = None,
start_offset: Optional[str] = None) -> List[Object]
end_offset (Optional[str]) - Filtra os resultados para objetos nomeados lexicograficamente antes de end_offset. Se start_offset estiver definido, os objetos listados
têm nomes entre start_offset (inclusivo) e end_offset (exclusivo).match_glob (Optional[str]) - Use um padrão glob para filtrar os resultados. Por exemplo: “foo*bar” corresponde a “footbar”, “foo baz bar” e “foobar”.max_results (Optional[int]) - O número máximo de resultados a retornar na resposta.prefix (Optional[str]) - Filtra os resultados para objetos cujos nomes possuem o prefixo especificado.start_offset (Optional[str]) - Filtra os resultados para objetos cujos nomes são lexicograficamente iguais ou posteriores a start_offset.
Quando end_offset está definido, os objetos listados têm nomes entre start_offset (inclusivo) e end_offset (exclusivo).
Retorna:
List(Object): Uma lista de objetos que correspondem aos parâmetros de consulta fornecidos.
upload_from_filename
Use upload_from_filename() para fazer o upload de um objeto a partir de um arquivo de origem no disco local para o App Storage.
def upload_from_filename(dest_object_name: str, src_filename: str) -> None
dest_object_name (str) - O nome do arquivo enviado.src_filename (str) - O arquivo de origem a ser enviado.
upload_from_bytes
O método upload_from_bytes faz o upload de um objeto a partir de dados bytes.
def upload_from_bytes(dest_object_name: str, src_data: bytes) -> None
dest_object_name (str) - O nome do objeto a ser enviado.src_data (str) - Os dados em bytes a serem enviados.
upload_from_text
O método upload_from_text faz o upload de um objeto a partir de uma string.
def upload_from_text(dest_object_name: str, src_data: Union[bytes, str]) -> None
dest_object_name (str) - O nome do objeto a ser enviado.src_data (str) - Os dados de texto a serem enviados.
Tipos de exceção
-
Ao interagir com o Replit App Storage usando o
Client, qualquer método pode retornar um dos seguintes erros:
-
BucketNotFoundError: Indica que o nome do bucket configurado não corresponde a nenhum bucket no App Storage.
-
DefaultBucketError: Indica ausência de configuração de bucket padrão.
-
ForbiddenError: Indica permissões insuficientes para acessar o bucket.
-
TooManyRequestsError: Indica que a operação está sendo limitada por excesso de requisições.
-
UnauthorizedError: Indica que a autorização restringiu o acesso à operação.
Exemplos de métodos de classe
As seções a seguir fornecem exemplos de código para gerenciar seus objetos usando o SDK do Replit App Storage.
Recuperar um arquivo como texto
client.download_as_text("file.json")
Recuperar os bytes brutos de um arquivo
client.download_as_bytes("file.png")
Baixar um arquivo para o sistema de arquivos local
client.download_to_filename("file.json", dest_filename)
Listar objetos no bucket
Fazer upload de um arquivo a partir de texto
client.upload_from_text("file.json", data)
Fazer upload de um arquivo como bytes
client.upload_from_bytes("file.png", data)
Fazer upload de objetos a partir do sistema de arquivos
client.upload_from_filename("file.json", src_filename)
Excluir um objeto do bucket
client.delete("file.json")
