FTPC Storage (Read-Only)
Use the ftpc library to read files from various storage backends.
Supported Backends
| Protocol | URL Format | Example |
|---|---|---|
| Local | file:///path or /path | /home/user/data |
| FTP | ftp://[user:pass@]host[:port]/path | ftp://ftp.example.com/pub |
| FTPS | ftps://[user:pass@]host[:port]/path | ftps://secure.example.com |
| SFTP | sftp://[user:pass@]host[:port]/path | sftp://user:pass@host/data |
| S3 | s3://bucket/path | s3://my-bucket/folder |
| Azure Data Lake | azure://account.dfs.core.windows.net/fs/path | azure://myacct.dfs.core.windows.net/data |
| Azure Blob | blob://account.blob.core.windows.net/container/path | blob://myacct.blob.core.windows.net/files |
Quick Start
python
from ftpc import connect_sync
# Connect using URL and list files
with connect_sync("s3://my-bucket") as store:
files = store.list("/")
for f in files:
print(f"{f.name} {'DIR' if f.is_directory else f.size}")
Available Operations
List Directory
python
from ftpc import connect_sync
with connect_sync("ftp://ftp.example.com") as store:
# List root (base path from URL)
files = store.list()
# List specific path
files = store.list("/documents")
# Each file is a FileDescriptor with:
# - name: str (filename only)
# - path: PurePath (full path)
# - is_file: bool
# - is_directory: bool
# - size: Optional[int] (bytes, None for directories)
# - modified_time: Optional[datetime]
Download File
python
from ftpc import connect_sync
with connect_sync("sftp://user:pass@host") as store:
# Download to local path
store.download("/remote/file.csv", "local_file.csv")
# With progress tracking
def progress(bytes_done: int) -> bool:
print(f"Downloaded {bytes_done} bytes")
return True # Return False to cancel
store.download("/large_file.zip", "output.zip", progress)
Using Named Remotes from Config
If ~/.ftpcconf.toml exists with configured remotes:
toml
# ~/.ftpcconf.toml [my-s3] type = "s3" bucket = "my-bucket" region = "us-east-1" [work-ftp] type = "ftp" url = "ftp.company.com" username = "user" password = "secret"
Load config and create client:
python
from ftpc.config import Config
from ftpc.clients.s3client import S3Client
config = Config.from_file() # Loads ~/.ftpcconf.toml
remote = config.remotes["my-s3"]
# Create client from config (varies by type)
with S3Client(bucket_name=remote.bucket, region_name=remote.region) as client:
files = client.ls("/")
Async Usage
python
import asyncio
from ftpc import Storage
async def main():
async with Storage.connect("s3://bucket") as store:
files = await store.list("/")
await store.download("/data.csv", "local.csv")
asyncio.run(main())
Named Constructors (Explicit Configuration)
python
from ftpc import Storage
# S3 with explicit credentials
with Storage.s3(
bucket="my-bucket",
region="us-east-1",
access_key_id="AKIAIOSFODNN7EXAMPLE",
secret_access_key="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
).sync() as store:
files = store.list("/")
# FTP with explicit config
with Storage.ftp(
host="ftp.example.com",
username="user",
password="pass",
tls=True # Use FTPS
).sync() as store:
store.download("/file.txt", "local.txt")
# SFTP with key file
with Storage.sftp(
host="server.example.com",
username="deploy",
key_filename="/home/user/.ssh/id_rsa"
).sync() as store:
files = store.list("/var/data")
Dependencies
Install required backends:
bash
pip install ftpc # Core (local + FTP) pip install ftpc[sftp] # + SFTP (paramiko) pip install ftpc[s3] # + S3 (boto3) pip install ftpc[azure] # + Azure (azure-storage-*) pip install ftpc[all] # All backends