Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Separate method headers in docstrings #265

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Separate method headers in docstrings #265

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9d01b7b
Remove square brackets around arguments in docstrings
abhro Dec 25, 2024
3344fb9
Make method signature more compact
abhro Dec 25, 2024
ee655d8
Move the argument types in docstring to own section
abhro Dec 25, 2024
59be7ea
Separate argument type list in docstring from method header
abhro Dec 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 96 additions & 82 deletions src/Downloads.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ export download, request, Downloader, Response, RequestError, default_downloader
## public API types ##

"""
Downloader(; [ grace::Real = 30 ])
Downloader(; grace::Real = 30)

`Downloader` objects are used to perform individual `download` operations.
Connections, name lookups and other resources are shared within a `Downloader`.
Expand Down Expand Up @@ -171,64 +171,80 @@ end
## download API ##

"""
download(url, [ output = tempname() ];
[ method = "GET", ]
[ headers = <none>, ]
[ timeout = <none>, ]
[ progress = <none>, ]
[ verbose = false, ]
[ debug = <none>, ]
[ downloader = <default>, ]
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

Download a file from the given url, saving it to `output` or if not specified, a
temporary path. The `output` can also be an `IO` handle, in which case the body
of the response is streamed to that handle and the handle is returned. If
`output` is a command, the command is run and output is sent to it on stdin.

If the `downloader` keyword argument is provided, it must be a `Downloader`
object. Resources and connections will be shared between downloads performed by
the same `Downloader` and cleaned up automatically when the object is garbage
collected or there have been no downloads performed with it for a grace period.
See `Downloader` for more info about configuration and usage.

If the `headers` keyword argument is provided, it must be a vector or dictionary
whose elements are all pairs of strings. These pairs are passed as headers when
downloading URLs with protocols that supports them, such as HTTP/S.

The `timeout` keyword argument specifies a timeout for the download to complete in
seconds, with a resolution of milliseconds. By default no timeout is set, but this
can also be explicitly requested by passing a timeout value of `Inf`. Separately,
if 20 seconds elapse without receiving any data, the download will timeout. See
extended help for how to disable this timeout.

If the `progress` keyword argument is provided, it must be a callback function
which will be called whenever there are updates about the size and status of the
ongoing download. The callback must take two integer arguments: `total` and
`now` which are the total size of the download in bytes, and the number of bytes
which have been downloaded so far. Note that `total` starts out as zero and
remains zero until the server gives an indication of the total size of the
download (e.g. with a `Content-Length` header), which may never happen. So a
well-behaved progress callback should handle a total size of zero gracefully.

If the `verbose` option is set to true, `libcurl`, which is used to implement
the download functionality will print debugging information to `stderr`. If the
`debug` option is set to a function accepting two `String` arguments, then the
verbose option is ignored and instead the data that would have been printed to
`stderr` is passed to the `debug` callback with `type` and `message` arguments.
The `type` argument indicates what kind of event has occurred, and is one of:
`TEXT`, `HEADER IN`, `HEADER OUT`, `DATA IN`, `DATA OUT`, `SSL DATA IN` or `SSL
DATA OUT`. The `message` argument is the description of the debug event.
## Arguments

### Positonal arguments

- `url :: AbstractString`

- `output :: Union{AbstractString, AbstractCmd, IO}`

### Keyword Arguments

All keyword arguments are optional.

- `method :: AbstractString`

- `downloader :: Downloader`

If the `downloader` keyword argument is provided, it must be a `Downloader`
object. Resources and connections will be shared between downloads performed by
the same `Downloader` and cleaned up automatically when the object is garbage
collected or there have been no downloads performed with it for a grace period.
See `Downloader` for more info about configuration and usage.

- `headers :: Union{AbstractVector, AbstractDict}`

If the `headers` keyword argument is provided, it must be a vector or dictionary
whose elements are all pairs of strings. These pairs are passed as headers when
downloading URLs with protocols that supports them, such as HTTP/S.

- `timeout :: Real`

The `timeout` keyword argument specifies a timeout for the download to complete in
seconds, with a resolution of milliseconds. By default no timeout is set, but this
can also be explicitly requested by passing a timeout value of `Inf`. Separately,
if 20 seconds elapse without receiving any data, the download will timeout. See
extended help for how to disable this timeout.

- `progress :: (total::Integer, now::Integer) -> Any`

If the `progress` keyword argument is provided, it must be a callback function
which will be called whenever there are updates about the size and status of the
ongoing download. The callback must take two integer arguments: `total` and
`now` which are the total size of the download in bytes, and the number of bytes
which have been downloaded so far. Note that `total` starts out as zero and
remains zero until the server gives an indication of the total size of the
download (e.g. with a `Content-Length` header), which may never happen. So a
well-behaved progress callback should handle a total size of zero gracefully.

- `verbose :: Bool`

If the `verbose` option is set to true, `libcurl`, which is used to implement
the download functionality will print debugging information to `stderr`. If the
`debug` option is set to a function accepting two `String` arguments, then the
verbose option is ignored and instead the data that would have been printed to
`stderr` is passed to the `debug` callback with `type` and `message` arguments.
The `type` argument indicates what kind of event has occurred, and is one of:
`TEXT`, `HEADER IN`, `HEADER OUT`, `DATA IN`, `DATA OUT`, `SSL DATA IN` or `SSL
DATA OUT`. The `message` argument is the description of the debug event.

- `debug :: (type, message) -> Any`

## Extended Help

Expand All @@ -237,7 +253,7 @@ For further customization, use a [`Downloader`](@ref) and
For example, to disable the 20 second timeout when no data is received, you may
use the following:

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

Expand Down Expand Up @@ -276,32 +292,19 @@ end

"""
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>, ]
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

Make a request to the given url, returning a `Response` object capturing the
status, headers and other information about the response. The body of the
response is written to `output` if specified and discarded otherwise. For HTTP/S
Expand All @@ -315,6 +318,21 @@ options differ from the `download` function:
- `progress` is a callback taking four integers for upload and download progress
- `throw` controls whether to throw or return a `RequestError` on request error

The given `url` must be an `AbstractString`.
All keyword arguments to this method are optional:

- `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`

Note that unlike `download` which throws an error if the requested URL could not
be downloaded (indicated by non-2xx status code), `request` returns a `Response`
object no matter what the status code of the response is. If there is an error
Expand Down Expand Up @@ -488,11 +506,7 @@ function content_length(headers::Union{AbstractVector, AbstractDict})
end

"""
default_downloader!(
downloader = <none>
)

downloader :: Downloader
default_downloader!(downloader::Downloader = <none>)

Set the default `Downloader`. If no argument is provided, resets the default downloader so that a fresh one is created the next time the default downloader is needed.
"""
Expand Down
Loading