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:

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.

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.

Finally the path component defines the unique location of a file or directory on the target machine.

Inheritance diagram¶

Inheritance

Parent Class:

maxon.ObjectInterface

Child Class:

maxon.Url

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

name (maxon.UrlInterface) – The maxon.Url to be compared with.
mode (maxon.URLCOMPARE) – The comparison mode.

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

key (Union[maxon.URLFLAGS, maxon.Url]) – The id of the property to set. The possible values for id depend on the scheme.
value (maxon.Data) – maxon.Data to be set.

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

key (Union[maxon.URLFLAGS, maxon.Url]) – The id of the property to set. The possible values for id depend on the scheme.
value (maxon.Data) – maxon.Data to be set.

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.