GitHub

Downloads

Downloads.download — Function
download(url, [ output = tempname() ];
    [ method = "GET", ]
    [ headers = <none>, ]
    [ timeout = <none>, ]
    [ progress = <none>, ]
    [ verbose = false, ]
    [ debug = <none>, ]
    [ downloader = <default>, ]
) -> output

    url        :: AbstractString
    output     :: Union{AbstractString, AbstractCmd, IO}
    method     :: AbstractString
    headers    :: Union{AbstractVector, AbstractDict}
    timeout    :: Real
    progress   :: (total::Integer, now::Integer) --> Any
    verbose    :: Bool
    debug      :: (type, message) --> Any
    downloader :: Downloader

Скачайте файл по указанному url, сохраняя его в output или, если не указано, во временном пути. output также может быть дескриптором IO, в этом случае тело ответа передается в этот дескриптор, и дескриптор возвращается. Если output является командой, команда выполняется, и вывод отправляется в нее через stdin.

Если аргумент ключевого слова downloader предоставлен, он должен быть объектом Downloader. Ресурсы и соединения будут разделяться между загрузками, выполняемыми одним и тем же Downloader, и автоматически очищаться, когда объект будет собран сборщиком мусора или если с ним не было выполнено загрузок в течение периода ожидания. См. Downloader для получения дополнительной информации о конфигурации и использовании.

Если аргумент ключевого слова headers предоставлен, он должен быть вектором или словарем, элементы которого представляют собой пары строк. Эти пары передаются в качестве заголовков при загрузке URL-адресов с протоколами, которые их поддерживают, такими как HTTP/S.

Аргумент ключевого слова timeout указывает время ожидания для завершения загрузки в секундах с разрешением в миллисекундах. По умолчанию тайм-аут не установлен, но это также можно явно запросить, передав значение тайм-аута Inf. Отдельно, если 20 секунд проходят без получения каких-либо данных, загрузка завершится по тайм-ауту. См. расширенную помощь о том, как отключить этот тайм-аут.

Если аргумент ключевого слова progress предоставлен, он должен быть функцией обратного вызова, которая будет вызываться всякий раз, когда есть обновления о размере и статусе текущей загрузки. Функция обратного вызова должна принимать два целых аргумента: total и now, которые представляют собой общий размер загрузки в байтах и количество байтов, которые были загружены до сих пор. Обратите внимание, что total начинается с нуля и остается нулем, пока сервер не даст указание на общий размер загрузки (например, с заголовком Content-Length), что может никогда не произойти. Поэтому хорошо работающая функция обратного вызова прогресса должна корректно обрабатывать общий размер ноль.

Если опция verbose установлена в true, libcurl, который используется для реализации функциональности загрузки, будет выводить отладочную информацию в stderr. Если опция debug установлена в функцию, принимающую два аргумента String, то опция подробного вывода игнорируется, и вместо этого данные, которые были бы напечатаны в stderr, передаются в функцию обратного вызова debug с аргументами type и message. Аргумент type указывает, какое событие произошло, и является одним из: TEXT, HEADER IN, HEADER OUT, DATA IN, DATA OUT, SSL DATA IN или SSL DATA OUT. Аргумент message — это описание события отладки.

Расширенная помощь

Для дальнейшей настройки используйте Downloader и easy_hooks. Например, чтобы отключить 20-секундный тайм-аут при отсутствии полученных данных, вы можете использовать следующее:

downloader = Downloads.Downloader()
downloader.easy_hook = (easy, info) -> Downloads.Curl.setopt(easy, Downloads.Curl.CURLOPT_LOW_SPEED_TIME, 0)

Downloads.download("https://httpbingo.julialang.org/delay/30"; downloader)
source
Downloads.request — Function
request(url;
    [ input = <none>, ]
    [ output = <none>, ]
    [ method = input ? "PUT" : output ? "GET" : "HEAD", ]
    [ headers = <none>, ]
    [ timeout = <none>, ]
    [ progress = <none>, ]
    [ verbose = false, ]
    [ debug = <none>, ]
    [ throw = true, ]
    [ downloader = <default>, ]
    [ interrupt = <none>, ]
) -> Union{Response, RequestError}

    url        :: AbstractString
    input      :: Union{AbstractString, AbstractCmd, IO}
    output     :: Union{AbstractString, AbstractCmd, IO}
    method     :: AbstractString
    headers    :: Union{AbstractVector, AbstractDict}
    timeout    :: Real
    progress   :: (dl_total, dl_now, ul_total, ul_now) --> Any
    verbose    :: Bool
    debug      :: (type, message) --> Any
    throw      :: Bool
    downloader :: Downloader
    interrupt  :: Base.Event

Сделайте запрос к указанному URL, возвращая объект Response, который захватывает статус, заголовки и другую информацию о ответе. Тело ответа записывается в output, если указано, и игнорируется в противном случае. Для HTTP/S запросов, если задан поток input, выполняется запрос PUT; в противном случае, если задан поток output, выполняется запрос GET; если ни один из них не задан, выполняется запрос HEAD. Для других протоколов используются соответствующие методы по умолчанию в зависимости от того, какие комбинации ввода и вывода запрашиваются. Следующие параметры отличаются от функции download:

  • input позволяет предоставить тело запроса; если предоставлено, по умолчанию используется запрос PUT
  • progress является обратным вызовом, принимающим четыре целых числа для прогресса загрузки и выгрузки
  • throw управляет тем, следует ли выбрасывать ошибку или возвращать RequestError в случае ошибки запроса

Обратите внимание, что в отличие от download, который выбрасывает ошибку, если запрашиваемый URL не может быть загружен (что указывается кодом состояния, отличным от 2xx), request возвращает объект Response независимо от того, каков код состояния ответа. Если возникает ошибка при получении ответа, то выбрасывается или возвращается RequestError.

Если предоставлен аргумент ключевого слова interrupt, он должен быть объектом Base.Event. Если событие срабатывает во время выполнения запроса, запрос будет отменен, и будет выброшена ошибка. Это можно использовать для прерывания длительного запроса, например, если пользователь хочет отменить загрузку.

source
Downloads.Response — Type
struct Response
    proto   :: String
    url     :: String
    status  :: Int
    message :: String
    headers :: Vector{Pair{String,String}}
end

Response — это тип, который захватывает свойства успешного ответа на запрос в виде объекта. Он имеет следующие поля:

  • proto: протокол, который использовался для получения ответа
  • url: URL, который в конечном итоге был запрошен после следования перенаправлениям
  • status: код состояния ответа, указывающий на успех, неудачу и т. д.
  • message: текстовое сообщение, описывающее природу ответа
  • headers: любые заголовки, которые были возвращены с ответом

Значение и доступность некоторых из этих ответов зависят от протокола, использованного для запроса. Для многих протоколов, включая HTTP/S и S/FTP, код состояния 2xx указывает на успешный ответ. Для ответов в протоколах, которые не поддерживают заголовки, вектор заголовков будет пустым. HTTP/2 не включает сообщение состояния, только код состояния, поэтому сообщение будет пустым.

source
Downloads.RequestError — Type
struct RequestError <: ErrorException
    url      :: String
    code     :: Int
    message  :: String
    response :: Response
end

RequestError — это тип, который захватывает свойства неудачного ответа на запрос в качестве объекта исключения:

  • url: оригинальный URL, который был запрошен без каких-либо перенаправлений
  • code: код ошибки libcurl; 0, если произошла ошибка только протокола
  • message: сообщение об ошибке libcurl, указывающее, что пошло не так
  • response: объект ответа, захватывающий доступную информацию о ответе

Тот же тип RequestError выбрасывается функцией download, если запрос был успешным, но произошла ошибка на уровне протокола, что указывает на код состояния, который не находится в диапазоне 2xx, в этом случае code будет равен нулю, а поле message будет пустой строкой. API request выбрасывает RequestError только в том случае, если код ошибки libcurl не равен нулю, в этом случае включенный объект response вероятно будет иметь status равный нулю и пустое сообщение. Однако существуют ситуации, когда ошибка на уровне curl выбрасывается из-за ошибки протокола, в этом случае как внутренний, так и внешний код и сообщение могут быть интересны.

source
Downloads.Downloader — Type
Downloader(; [ grace::Real = 30 ])

Объекты Downloader используются для выполнения отдельных операций download. Соединения, поиск имен и другие ресурсы разделяются внутри Downloader. Эти соединения и ресурсы очищаются после настраиваемого периода грации (по умолчанию: 30 секунд) с момента последней загрузки, или когда он будет собран сборщиком мусора, в зависимости от того, что произойдет первым. Если период грации установлен в ноль, все ресурсы будут очищены немедленно, как только не останется активных загрузок. Если период грации установлен в Inf, ресурсы не будут очищены до тех пор, пока Downloader не будет собран сборщиком мусора.

source