ButlerURI

class lsst.daf.butler.ButlerURI(uri: Union[str, urllib.parse.ParseResult], root: Optional[str] = None, forceAbsolute: bool = True, forceDirectory: bool = False)

Bases: object

Convenience wrapper around URI parsers.

Provides access to URI components and can convert file paths into absolute path URIs. Scheme-less URIs are treated as if they are local file system paths and are converted to absolute URIs.

Parameters:

uri : str or urllib.parse.ParseResult

URI in string form. Can be scheme-less if referring to a local filesystem path.

root : str, optional

When fixing up a relative path in a file scheme or if scheme-less, use this as the root. Must be absolute. If None the current working directory will be used.

forceAbsolute : bool, optional

If True, scheme-less relative URI will be converted to an absolute path using a file scheme. If False scheme-less URI will remain scheme-less and will not be updated to file or absolute path.

forceDirectory: `bool`, optional

If True forces the URI to end with a separator, otherwise given URI is interpreted as is.

Attributes Summary

fragment	The fragment component of the URI.
netloc	The URI network location.
ospath	Path component of the URI localized to current OS.
params	Any parameters included in the URI.
path	The path component of the URI.
query	Any query strings included in the URI.
relativeToPathRoot	Returns path relative to network location.
scheme	The URI scheme (:// is not part of the scheme).

Methods Summary

basename()	Returns the base name, last element of path, of the URI.
dirname()	Returns a ButlerURI containing all the directories of the path attribute.
getExtension()	Return the file extension(s) associated with this URI path.
geturl()	Return the URI in string form.
replace(**kwargs)	Replace components in a URI with new values and return a new instance.
split()	Splits URI into head and tail.
updateFile(newfile)	Update in place the final component of the path with the supplied file name.

Attributes Documentation

fragment

The fragment component of the URI.

netloc

The URI network location.

ospath

Path component of the URI localized to current OS.

params

Any parameters included in the URI.

path

The path component of the URI.

query

Any query strings included in the URI.

relativeToPathRoot

Returns path relative to network location.

Effectively, this is the path property with posix separator stripped from the left hand side of the path.

scheme

The URI scheme (:// is not part of the scheme).

Methods Documentation

basename() → str

Returns the base name, last element of path, of the URI. If URI ends on a slash returns an empty string. This is the second element returned by split().

Equivalent of os.path.basename().

Returns:

tail : str

Last part of the path attribute. Trail will be empty if path ends on a separator.

dirname() → lsst.daf.butler.core.location.ButlerURI

Returns a ButlerURI containing all the directories of the path attribute.

Equivalent of os.path.dirname()

Returns:

head : ButlerURI

Everything except the tail of path attribute, expanded and normalized as per ButlerURI rules.

getExtension() → str

Return the file extension(s) associated with this URI path.

Returns:

ext : str

The file extension (including the .). Can be empty string if there is no file extension. Will return all file extensions as a single extension such that file.fits.gz will return a value of .fits.gz.

geturl() → str

Return the URI in string form.

Returns:

url : str

String form of URI.

replace(**kwargs) → lsst.daf.butler.core.location.ButlerURI

Replace components in a URI with new values and return a new instance.

Returns:

new : ButlerURI

New ButlerURI object with updated values.

split() → Tuple[lsst.daf.butler.core.location.ButlerURI, str]

Splits URI into head and tail. Equivalent to os.path.split where head preserves the URI components.

Returns:

head: `ButlerURI`

Everything leading up to tail, expanded and normalized as per ButlerURI rules.

tail : str

Last self.path component. Tail will be empty if path ends on a separator. Tail will never contain separators.

updateFile(newfile: str) → None

Update in place the final component of the path with the supplied file name.

Parameters:

newfile : str

File name with no path component.

Notes

Updates the URI in place. Updates the ButlerURI.dirLike attribute.