basilisp.url

Namespace providing simple utility functions for creating and modifying URLs, wrapping functionality provided in urllib.parse in a more Clojure-like API.

The primary entrypoint function is url which will parse the input value into an URL record type, which allows for structured manipulation. Because the source type is a record, it can be manipulated using standard Clojure idioms such as basilisp.core/assoc.

After any modifications are made, basilisp.core/str can turn the URL record type into a string that can be used wherever string URLs are expected.

(-> (url/url "https://en.wikipedia.org/wiki/Python_(programming_language)#Libraries")
    (assoc :query {"mobile" ["true"]})
    (str))
;; => "https://en.wikipedia.org/wiki/Python_%28programming_language%29?mobile=true#Libraries"

Note

Per the note in urllib.parse.urlunparse(), it is possible that round-trip return from this function is not identical to the input if no other changes are made to the URL parts, but the resulting URL should be equivalent.

Warning

No validation occurs creating a URL string from the provided URL record type, so users should take care to validate any components carefully before using these results.

To create a new URL record, basilisp.core/assoc keys onto blank-url. This ensures that your URL has the correct defaults.

recordURL
protocolURLSource[source]
fn (to-url* this)[source]

Convert the input type to an URL.

Var blank-url[source]

Blank URL type which can be used as a base for URL manipulation.

fn (url url-str)[source]

Construct an URL record from the input value (such as a string) as by urllib.parse.urlparse().

URL types have the following fields which you can manipulate directly using basilisp.core/assoc. The default values for each field is an empty string unless otherwise noted.

  • :scheme

  • :username (default nil)

  • :password (default nil)

  • :hostname (default nil)

  • :port (default nil)

  • :path

  • :params

  • :query (default {})

  • :fragment

Note

Component fields of what Python calls the netloc (“network location”) must be nil to be excluded from the final URL output. Empty strings are not equivalent to nil. These include :username, :password, :hostname, and :port.

Note

The :query component should be a mapping of string keys to vectors of values:

(:query (url/url "http://localhost/some/path?a=1&a=2&b=3"))
;; => {"b" ["3"] "a" ["1" "2"]}

Note

url always decodes percent-encoded :username, :password, :path, and :query values. Users should not attempt to URL encode values added to the URL object returned by that function. Converting the URL back into a string will URL encode those same fields.

Warning

Because this function relies on urllib.parse.urlparse, it does not perform any validation of the input URLs and all the caveats of that function apply here.