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([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()

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[, convertWindowsBackslashes])

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(mode=<URLCOMPARE.DEFAULT: 1>)

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 (maxon.Data) – The default value returned if the key was not found.

Returns

The attribute value or an error if there was none.

Return type

maxon.Data

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()

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, convertWindowsBackslashes=True)

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 unless convertWindowsBackslashes is set to False.

Parameters
  • path (str) – The new path.

  • convertWindowsBackslashes (bool) – True to convert backslashes under windows (the default).

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.