maxon.UrlInterface

Description

Interface class for maxon.Url. | A maxon::Url defines the location of a file or a similar resource. | The class allows to construct a file path and to handle files. | | Urls consist of three parts:

  1. A scheme, an authority and a path. The readable text-representation is “scheme://authority/path”.
    The scheme defines which handler is used, e.g. “http” for web-based connections or “file” for the regular file system.
  2. The authority defines the machine, which can be empty for “localhost”, a network drive or a webserver.
    It can also refer to an embedded file, e.g. a ZIP. To distinguish that case the readable text representation contains brackets: “scheme://[authority]/path”.
    Nesting is possible repeatedly.
  3. Finally the path component defines the unique location of a file or directory on the target machine.

Inheritance diagram

Inheritance

Parent Class:

Child Class:

Methods Signature

Append(relativeUrl) Appends a relative string or a maxon.Url to the current one.
CheckSuffix(suffix) Checks whether the maxon.Url has the a given suffix.
ClearSuffix() Deletes the suffix of the maxon.Url.
Compare(name[, mode]) Compares the object against ‘name’.
Get(key[, defaultValue]) Returns maxon.Url attributes.
GetAuthority() Returns the authority of a maxon.Url.
GetComponents(authority) Returns all parts of the maxon.Url system path as separated strings.
GetData(key) Returns maxon.Url attributes.
GetDirectory() Returns the maxon.Url of the directory.
GetEmbeddedUrl() Returns an embedded maxon.Url.
GetName() Returns the name of the last component.
GetPath() Returns the path component of the maxon.Url.
GetScheme()
Gets the UrlScheme of the Url. Is guaranteed to be lowercase (canonical form for urls)
GetSuffix() Returns the suffix of the maxon.Url.
GetSystemPath()
Returns a path from the maxon.Url that the current operating system (or scheme handler) can understand.
GetUrl(urlType) Returns the maxon.Url as a string.
IsEmpty()
Returns if the maxon.Url has no content.
IsPopulated()
Returns if the maxon.Url has any content.
RemoveName() Removes the last part of a Url.
Set(key, value) Modifies or sets a maxon.Url attribute.
SetAuthority(authority) Sets the authority of a maxon.Url.
SetData(key, value) Modifies or sets a maxon.Url attribute.
SetEmbeddedUrl(url) Replaces and sets an embedded maxon.Url.
SetName(name) Replaces the last component of a maxon.Url.
SetPath(path) Replaces the path component of the maxon.Url.
SetScheme(scheme) Sets the scheme of the Url.
SetSuffix(suffix)
Replaces the suffix of the maxon.Url.
SetSystemPath(path)
Stores a system path in a maxon.Url.
SetUrl(urlString, enableDefaultFallbackScheme)
Sets the maxon.Url.

Methods Definition

UrlInterface.Append(relativeUrl)

Appends a relative string or a maxon.Url to the current one.

Note

If the Url is file:///c:/directory a call of

url.Append(maxon.Url("test/file.txt"))

will result in file:///c:/directory/test/file.txt.

Parameters:srelativeUrl – The relative maxon.Url to append.
UrlInterface.CheckSuffix(suffix)

Checks whether the maxon.Url has the a given suffix.

Note

If the maxon.Url is “file:///c:/directory/file.txt” a call of CheckSuffix(“txt”_s) will return true.

Parameters:suffix (str) – The suffix without dot to check against.
Returns:True if the suffix matches.
Return type:bool
UrlInterface.ClearSuffix()

Deletes the suffix of the maxon.Url.

Note

If the maxon.Url was “file:///c:/directory/file.txt” a call will result in “file:///c:/directory/file”.

UrlInterface.Compare(name, mode=maxon.URLCOMPARE.DEFAULT)

Compares the object against ‘name’.

Note

By default the comparison is case-sensitive, so ‘./Test.tif’ and ‘./test.tif’ are not the same.
To check if Urls point to the identical item use maxon.Url.IoNormalizeAndResolve() instead.
Parameters:
Returns:

The compared result.

Return type:

maxon.COMPARERESULT

UrlInterface.Get(key, defaultValue=None)

Returns maxon.Url attributes.

See also

maxon.URLFLAGS for details.

Parameters:
  • key (Union[maxon.URLFLAGS, maxon.Url]) – The id of the property to get. The possible values for id depend on the scheme.
  • defaultValue (Any) – The default value returned if the key was not found.
Returns:

The attribute value or an error if there was none.

Return type:

Any

UrlInterface.GetAuthority()

Returns the authority of a maxon.Url. The authority can be a machine, server or embedded file.

Returns:The authority of the maxon.Url.
If the machine is localhost the returned maxon.Url is empty.
If it is a machine or server the scheme will be maxon.URLSCHEME_AUTHORITY.
Otherwise it defines an embedded file.
Return type:maxon.Url
UrlInterface.GetComponents(authority)

Returns all parts of the maxon.Url system path as separated strings.

Note

If the maxon.Url was “file:///c:/directory/file.txt” a call of GetComponents will return: { “C:”, “directory”, “file.txt” }.

Parameters:authority
Returns:
UrlInterface.GetData(key)

Returns maxon.Url attributes. See maxon.URLFLAGS for details.

Parameters:key (Union[maxon.URLFLAGS, maxon.Url]) – The id of the property to get. The possible values for id depend on the scheme.
Returns:The attribute value or an error if there was none.
Return type:maxon.Data
UrlInterface.GetDirectory()

Returns the maxon.Url of the directory.

Note

If the Url was “file:///c:/directory/file.txt” a call of GetDirectory() will return “file:///c:/directory”.

Returns:The directory.
Return type:maxon.Url
UrlInterface.GetEmbeddedUrl()

Returns an embedded maxon.Url.

Note

If the Url is “zip://[file:///c:/images.zip]/image01.jpg” a call to GetEmbeddedUrl() will return “file:///c:/images.zip”.

Returns:The embedded maxon.Url or if there was none, an empty maxon.Url.
Return type:maxon.Url
UrlInterface.GetName()

Returns the name of the last component.

Note

if the Url is “file:///c:/directory/file.txt” a call to GetName() will return “file.txt”.

Returns:The name of the last path component.
Return type:str
UrlInterface.GetPath()

Returns the path component of the maxon.Url.

Note

This doesn’t contain scheme and authority. E.g. if the maxon.Url is “file:///c:/directory/file.txt” a call will return “c:/directory/file.txt”.

Returns:The path component of the maxon.Url (with no authority and scheme).
Return type:str
UrlInterface.GetScheme()
Gets the UrlScheme of the Url. Is guaranteed to be lowercase (canonical form for urls)
if scheme was automatically determined through maxon.UrlInterface.SetUrl(), otherwise as set.

In most schemes paths are a combination of the directory path and file path, but the path could also be a network query or database entry. Path components are always separated by a forward slash and the forward slash is a reserved character that cannot be used for names.
Returns:The scheme name.
Return type:str
UrlInterface.GetSuffix()

Returns the suffix of the maxon.Url.

Note

If the maxon.Url was “file:///c:/directory/file.txt” a call of GetSuffix() will return “txt”.

Returns:The suffix without dot.
Return type:str
UrlInterface.GetSystemPath()
Returns a path from the maxon.Url that the current operating system (or scheme handler) can understand.
If the maxon.Url contains no valid scheme an error will be returned.

An error will also be returned if the maxon.Url contains illegal characters for the scheme, e.g. backslashes on Windows in a file scheme.
Returns:The system path.
Return type:str
UrlInterface.GetUrl(urlType)

Returns the maxon.Url as a string.

Note

A maxon.Url has the format scheme://authority/path.

Returns:The maxon.Url as a string.
Return type:str
UrlInterface.IsEmpty()
Returns if the maxon.Url has no content.

A maxon.Url is considered empty if it has no path component and no authority (even if a scheme is set).
Returns:True if the maxon.Url is empty.
Return type:bool
UrlInterface.IsPopulated()
Returns if the maxon.Url has any content.
A maxon.Url is considered populated if it has a path component or authority set.
Returns:True if the maxon.Url has content.
Return type:bool
UrlInterface.RemoveName()

Removes the last part of a Url.

Note

If the maxon.Url is “file:///c:/directory/file.txt” a call of RemoveName() will result in “file:///c:/directory”.

UrlInterface.Set(key, value)

Modifies or sets a maxon.Url attribute.

See also

maxon.URLFLAGS for details.

Parameters:
UrlInterface.SetAuthority(authority)

Sets the authority of a maxon.Url. This can be a machine or server.

Note

Empty string can be passed for no authority / localhost. The authority scheme will be URLSCHEME_AUTHORITY.

Parameters:authority (Union[str, maxon.Url]) – The new authority.
Returns:
UrlInterface.SetData(key, value)

Modifies or sets a maxon.Url attribute. See maxon.URLFLAGS for details.

Parameters:
UrlInterface.SetEmbeddedUrl(url)

Replaces and sets an embedded maxon.Url.

Note

If the Url is “zip://[file:///c:/images.zip]/image01.jpg” a call to SetEmbeddedUrl(“file:///c:/otherimages.zip”_s) will result in “zip://[file:///c:/otherimages.zip]/image01.jpg”.

Parameters:url – The new embedded maxon.Url.
UrlInterface.SetName(name)

Replaces the last component of a maxon.Url. The name must not contain a forward slashes and under Windows additionally no backslashes.

Note

If the Url is “file:///c:/directory/file.txt” a call of SetName(“change.tif”_s) will result in “file:///c:/directory/change.tif”.

Parameters:name (str) – The new name.
UrlInterface.SetPath(path)

Replaces the path component of the maxon.Url. The path is stored unchanged with the exception that under Windows all backslashes will be changed into forward slashes.

Parameters:path (str) – The new path.
UrlInterface.SetScheme(scheme)

Sets the scheme of the Url. Path and authority will stay unchanged.

Parameters:scheme (str) – The new scheme
UrlInterface.SetSuffix(suffix)
Replaces the suffix of the maxon.Url.
If the maxon.Url had no suffix before a dot will be added together with the suffix string.

Note

If the maxon.Url is “file:///c:/directory/file.txt” a call of SetSuffix(“jpg”_s) will result in “file:///c:/directory/file.jpg”.

Parameters:suffix (str) – The new suffix of the maxon.Url without dot.
UrlInterface.SetSystemPath(path)
Stores a system path in a maxon.Url.

This call needs to be done after the appropriate scheme has been set.
If no scheme is set maxon.URLSCHEME_FILESYSTEM will be automatically set.

The system path may be converted to a different internal representation,
e.g. split into authority and path components.

Note

Under Windows all backslashes will be changed into forward slashes.

Parameters:path (str) – The system path
UrlInterface.SetUrl(urlString, enableDefaultFallbackScheme)
Sets the maxon.Url.
The scheme is detected automatically and converted to the canonical lowercase version (as described in rfc3986#3.1).

If a scheme isn’t found and enableDefaultFallbackScheme is False the function returns an IllegalArgumentError,
otherwise maxon.URLSCHEME_FILESYSTEM will be assumed (or maxon.URLSCHEME_RELATIVE if ‘urlString’ starts with no drive letter).

Please note that Urls only use forward slashes as delimiter,
backslashes are considered to be a part of names and not a delimiter.

‘?’ will be considered as the start of maxon.URLFLAGS.QUERY parameters.

Everything behind the ‘?’ will be placed in that property.
Use url.Get(maxon.URLFLAGS.QUERY) to get the query parameters.
Parameters:
  • urlString (str) – The new maxon.Url to be set.
  • enableDefaultFallbackScheme (bool) – If False and no scheme is set an error will be returned.