asyncftpclient

Этот модуль реализует асинхронный FTP-клиент. Он позволяет подключаться к FTP-серверу и выполнять на нём операции, такие как, например:

• Загрузка новых файлов.
• Удаление существующих файлов.
• Загрузка файлов.
• Изменение разрешений файлов.
• Навигация по каталогам FTP-сервера.

Подключение к FTP-серверу

Для начала любого обмена файлами необходимо сначала подключиться к FTP-серверу. Это можно сделать с помощью процедуры connect.

import asyncdispatch, asyncftpclient
proc main() {.async.} =
  var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test")
  await ftp.connect()
  echo("Connected")
waitFor(main())

Необходимо объявить новую асинхронную процедуру, чтобы разрешить использование ключевого слова await. Подключение будет завершено асинхронно, и клиент будет подключен после вызова await ftp.connect().

Загрузка нового файла

После подключения вы можете использовать процедуру store, чтобы загрузить новый файл на FTP-сервер. Убедитесь, что вы находитесь в правильном рабочем каталоге перед этим, используя процедуру pwd, вы также можете указать абсолютный путь.

import asyncdispatch, asyncftpclient
proc main() {.async.} =
  var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test")
  await ftp.connect()
  let currentDir = await ftp.pwd()
  assert currentDir == "/home/user/"
  await ftp.store("file.txt", "file.txt")
  echo("File finished uploading")
waitFor(main())

Проверка прогресса передачи файла

Прогресс загрузки или скачивания файла можно проверить, указав процедуру onProgressChanged для процедур store или retrFile.

Процедуры, принимающие обратный вызов onProgressChanged, будут вызывать его каждые progressInterval миллисекунд.

import asyncdispatch, asyncftpclient

proc onProgressChanged(total, progress: BiggestInt,
                        speed: float) {.async.} =
  echo("Uploaded ", progress, " of ", total, " bytes")
  echo("Current speed: ", speed, " kb/s")

proc main() {.async.} =
  var ftp = newAsyncFtpClient("example.com", user = "test", pass = "test", progressInterval = 500)
  await ftp.connect()
  await ftp.store("file.txt", "/home/user/file.txt", onProgressChanged)
  echo("File finished uploading")
waitFor(main())

Импорты

asyncdispatch, asyncnet, nativesockets, strutils, parseutils, os, times, net

Типы

AsyncFtpClient = ref object
  csock*: AsyncSocket
  dsock*: AsyncSocket
  user*, pass*: string
  address*: string
  port*: Port
  progressInterval: int
  jobInProgress*: bool
  job*: FtpJob
  dsockConnected*: bool

Исходный код Редактировать

FtpJobType = enum
  JRetrText, JRetr, JStore

Исходный код Редактировать

FtpEventType = enum
  EvTransferProgress, EvLines, EvRetr, EvStore

Исходный код Редактировать

FtpEvent = object
  filename*: string
  case typ*: FtpEventType
  of EvLines:
      lines*: string         ## Lines that have been transferred.
    
  of EvRetr, EvStore:       ## Retr/Store operation finished.
      nil

  of EvTransferProgress:
      bytesTotal*: BiggestInt ## Bytes total.
      bytesFinished*: BiggestInt ## Bytes transferred.
      speed*: BiggestInt     ## Speed in bytes/s
      currentJob*: FtpJobType ## The current job being performed.

Событие Исходный код Редактировать

ReplyError = object of IOError

Исходный код Редактировать

ProgressChangedProc = proc (total, progress: BiggestInt; speed: float): Future[
    void] {...}{.closure, gcsafe.}

Исходный код Редактировать

Процедуры

proc send(ftp: AsyncFtpClient; m: string): Future[TaintedString] {...}{.
    raises: [Exception, ValueError], tags: [RootEffect].}

Отправляет сообщение на сервер и ожидает основного ответа. \c\L добавлено для вас.

Вы должны убедиться, что сообщение m не содержит символов новой строки. Невыполнение этого требования приведёт к ошибке AssertionDefect.

Примечание: сервер может возвращать несколько строк кодированных ответов.

Исходный код Редактировать

proc connect(ftp: AsyncFtpClient): owned(Future[void]) {...}{.raises: [Exception],
    tags: [RootEffect].}

Подключается к указанному FTP-серверу с помощью ftp. Исходный код Редактировать

proc pwd(ftp: AsyncFtpClient): Future[TaintedString] {...}{.
    raises: [Exception, ValueError], tags: [RootEffect].}

Возвращает текущий рабочий каталог. Исходный код Редактировать

proc cd(ftp: AsyncFtpClient; dir: string): owned(Future[void]) {...}{.
    raises: [Exception], tags: [RootEffect].}

Изменяет текущий каталог на удалённом FTP-сервере на dir. Исходный код Редактировать

proc cdup(ftp: AsyncFtpClient): owned(Future[void]) {...}{.raises: [Exception],
    tags: [RootEffect].}

Изменяет текущий каталог на родительский каталог. Исходный код Редактировать

proc listDirs(ftp: AsyncFtpClient; dir = ""): Future[seq[string]] {...}{.
    raises: [Exception, ValueError], tags: [RootEffect].}

Возвращает список имён файлов в заданном каталоге. Если dir равно "", используется текущий каталог. Если async равно true, эта функция вернётся немедленно, и вам придётся использовать poll asyncdispatch для продолжения операции. Исходный код Редактировать

proc fileExists(ftp: AsyncFtpClient; file: string): Future[bool] {...}{.
    raises: [Exception, ValueError], tags: [RootEffect].}

Определяет, существует ли file. Исходный код Редактировать

proc createDir(ftp: AsyncFtpClient; dir: string; recursive = false): owned(
    Future[void]) {...}{.raises: [Exception], tags: [RootEffect].}

Создаёт каталог dir. Если recursive равно true, сначала создаётся самый верхний подкаталог dir, затем второй и т.д. Это позволяет указывать полный путь как dir, не беспокоясь о том, что подкаталоги могут не существовать. Исходный код Редактировать

proc chmod(ftp: AsyncFtpClient; path: string; permissions: set[FilePermission]): owned(
    Future[void]) {...}{.raises: [Exception], tags: [RootEffect].}

Изменяет разрешения path на permissions. Исходный код Редактировать

proc list(ftp: AsyncFtpClient; dir = ""): Future[string] {...}{.
    raises: [Exception, ValueError], tags: [RootEffect].}

Перечисляет все файлы в dir. Если dir равно "", используется текущий рабочий каталог. Исходный код Редактировать

proc retrText(ftp: AsyncFtpClient; file: string): Future[string] {...}{.
    raises: [Exception, ValueError], tags: [RootEffect].}

Получает file. Файл должен быть текстом ASCII. Исходный код Редактировать

proc defaultOnProgressChanged(total, progress: BiggestInt; speed: float): Future[
    void] {...}{.nimcall, gcsafe, raises: [Exception], tags: [RootEffect].}

Обработчик по умолчанию FTP onProgressChanged. Ничего не делает. Исходный код Редактировать

proc retrFile(ftp: AsyncFtpClient; file, dest: string;
              onProgressChanged: ProgressChangedProc = defaultOnProgressChanged): owned(
    Future[void]) {...}{.raises: [Exception],
                    tags: [RootEffect, TimeEffect, WriteIOEffect].}

Загружает file и сохраняет его в dest. Событие EvRetr передаётся в указанную функцию handleEvent при завершении загрузки. Поле filename события будет равно file. Исходный код Редактировать

proc store(ftp: AsyncFtpClient; file, dest: string;
           onProgressChanged: ProgressChangedProc = defaultOnProgressChanged): owned(
    Future[void]) {...}{.raises: [Exception],
                    tags: [RootEffect, ReadIOEffect, TimeEffect].}

Загружает file в dest на удалённом FTP-сервере. Рекомендуется использовать эту функцию асинхронно для просмотра прогресса загрузки. Событие EvStore передаётся в указанную функцию handleEvent при завершении загрузки, и поле filename будет равно file. Исходный код Редактировать

proc rename(ftp: AsyncFtpClient; nameFrom: string; nameTo: string): owned(
    Future[void]) {...}{.raises: [Exception], tags: [RootEffect].}

Переименовывает файл или каталог на удалённом FTP-сервере из текущего имени name_from в новое имя name_to Исходный код Редактировать

proc removeFile(ftp: AsyncFtpClient; filename: string): owned(Future[void]) {...}{.
    raises: [Exception], tags: [RootEffect].}

Удаляет файл filename на удалённом FTP-сервере Исходный код Редактировать

proc removeDir(ftp: AsyncFtpClient; dir: string): owned(Future[void]) {...}{.
    raises: [Exception], tags: [RootEffect].}

Удаляет каталог dir на удалённом FTP-сервере Исходный код Редактировать

proc newAsyncFtpClient(address: string; port = Port(21); user, pass = "";
                       progressInterval: int = 1000): AsyncFtpClient {...}{.
    raises: [OSError, Exception], tags: [RootEffect].}

Создаёт новый объект AsyncFtpClient. Исходный код Редактировать