1*bcb5dc79SHONG Yifan<!-- Generated with Stardoc: http://skydoc.bazel.build --> 2*bcb5dc79SHONG Yifan 3*bcb5dc79SHONG YifanSkylib module containing file path manipulation functions. 4*bcb5dc79SHONG Yifan 5*bcb5dc79SHONG YifanNOTE: The functions in this module currently only support paths with Unix-style 6*bcb5dc79SHONG Yifanpath separators (forward slash, "/"); they do not handle Windows-style paths 7*bcb5dc79SHONG Yifanwith backslash separators or drive letters. 8*bcb5dc79SHONG Yifan 9*bcb5dc79SHONG Yifan<a id="paths.basename"></a> 10*bcb5dc79SHONG Yifan 11*bcb5dc79SHONG Yifan## paths.basename 12*bcb5dc79SHONG Yifan 13*bcb5dc79SHONG Yifan<pre> 14*bcb5dc79SHONG Yifanpaths.basename(<a href="#paths.basename-p">p</a>) 15*bcb5dc79SHONG Yifan</pre> 16*bcb5dc79SHONG Yifan 17*bcb5dc79SHONG YifanReturns the basename (i.e., the file portion) of a path. 18*bcb5dc79SHONG Yifan 19*bcb5dc79SHONG YifanNote that if `p` ends with a slash, this function returns an empty string. 20*bcb5dc79SHONG YifanThis matches the behavior of Python's `os.path.basename`, but differs from 21*bcb5dc79SHONG Yifanthe Unix `basename` command (which would return the path segment preceding 22*bcb5dc79SHONG Yifanthe final slash). 23*bcb5dc79SHONG Yifan 24*bcb5dc79SHONG Yifan 25*bcb5dc79SHONG Yifan**PARAMETERS** 26*bcb5dc79SHONG Yifan 27*bcb5dc79SHONG Yifan 28*bcb5dc79SHONG Yifan| Name | Description | Default Value | 29*bcb5dc79SHONG Yifan| :------------- | :------------- | :------------- | 30*bcb5dc79SHONG Yifan| <a id="paths.basename-p"></a>p | The path whose basename should be returned. | none | 31*bcb5dc79SHONG Yifan 32*bcb5dc79SHONG Yifan**RETURNS** 33*bcb5dc79SHONG Yifan 34*bcb5dc79SHONG YifanThe basename of the path, which includes the extension. 35*bcb5dc79SHONG Yifan 36*bcb5dc79SHONG Yifan 37*bcb5dc79SHONG Yifan<a id="paths.dirname"></a> 38*bcb5dc79SHONG Yifan 39*bcb5dc79SHONG Yifan## paths.dirname 40*bcb5dc79SHONG Yifan 41*bcb5dc79SHONG Yifan<pre> 42*bcb5dc79SHONG Yifanpaths.dirname(<a href="#paths.dirname-p">p</a>) 43*bcb5dc79SHONG Yifan</pre> 44*bcb5dc79SHONG Yifan 45*bcb5dc79SHONG YifanReturns the dirname of a path. 46*bcb5dc79SHONG Yifan 47*bcb5dc79SHONG YifanThe dirname is the portion of `p` up to but not including the file portion 48*bcb5dc79SHONG Yifan(i.e., the basename). Any slashes immediately preceding the basename are not 49*bcb5dc79SHONG Yifanincluded, unless omitting them would make the dirname empty. 50*bcb5dc79SHONG Yifan 51*bcb5dc79SHONG Yifan 52*bcb5dc79SHONG Yifan**PARAMETERS** 53*bcb5dc79SHONG Yifan 54*bcb5dc79SHONG Yifan 55*bcb5dc79SHONG Yifan| Name | Description | Default Value | 56*bcb5dc79SHONG Yifan| :------------- | :------------- | :------------- | 57*bcb5dc79SHONG Yifan| <a id="paths.dirname-p"></a>p | The path whose dirname should be returned. | none | 58*bcb5dc79SHONG Yifan 59*bcb5dc79SHONG Yifan**RETURNS** 60*bcb5dc79SHONG Yifan 61*bcb5dc79SHONG YifanThe dirname of the path. 62*bcb5dc79SHONG Yifan 63*bcb5dc79SHONG Yifan 64*bcb5dc79SHONG Yifan<a id="paths.is_absolute"></a> 65*bcb5dc79SHONG Yifan 66*bcb5dc79SHONG Yifan## paths.is_absolute 67*bcb5dc79SHONG Yifan 68*bcb5dc79SHONG Yifan<pre> 69*bcb5dc79SHONG Yifanpaths.is_absolute(<a href="#paths.is_absolute-path">path</a>) 70*bcb5dc79SHONG Yifan</pre> 71*bcb5dc79SHONG Yifan 72*bcb5dc79SHONG YifanReturns `True` if `path` is an absolute path. 73*bcb5dc79SHONG Yifan 74*bcb5dc79SHONG Yifan**PARAMETERS** 75*bcb5dc79SHONG Yifan 76*bcb5dc79SHONG Yifan 77*bcb5dc79SHONG Yifan| Name | Description | Default Value | 78*bcb5dc79SHONG Yifan| :------------- | :------------- | :------------- | 79*bcb5dc79SHONG Yifan| <a id="paths.is_absolute-path"></a>path | A path (which is a string). | none | 80*bcb5dc79SHONG Yifan 81*bcb5dc79SHONG Yifan**RETURNS** 82*bcb5dc79SHONG Yifan 83*bcb5dc79SHONG Yifan`True` if `path` is an absolute path. 84*bcb5dc79SHONG Yifan 85*bcb5dc79SHONG Yifan 86*bcb5dc79SHONG Yifan<a id="paths.is_normalized"></a> 87*bcb5dc79SHONG Yifan 88*bcb5dc79SHONG Yifan## paths.is_normalized 89*bcb5dc79SHONG Yifan 90*bcb5dc79SHONG Yifan<pre> 91*bcb5dc79SHONG Yifanpaths.is_normalized(<a href="#paths.is_normalized-str">str</a>, <a href="#paths.is_normalized-look_for_same_level_references">look_for_same_level_references</a>) 92*bcb5dc79SHONG Yifan</pre> 93*bcb5dc79SHONG Yifan 94*bcb5dc79SHONG YifanReturns true if the passed path doesn't contain uplevel references "..". 95*bcb5dc79SHONG Yifan 96*bcb5dc79SHONG YifanAlso checks for single-dot references "." if look_for_same_level_references 97*bcb5dc79SHONG Yifanis `True.` 98*bcb5dc79SHONG Yifan 99*bcb5dc79SHONG Yifan 100*bcb5dc79SHONG Yifan**PARAMETERS** 101*bcb5dc79SHONG Yifan 102*bcb5dc79SHONG Yifan 103*bcb5dc79SHONG Yifan| Name | Description | Default Value | 104*bcb5dc79SHONG Yifan| :------------- | :------------- | :------------- | 105*bcb5dc79SHONG Yifan| <a id="paths.is_normalized-str"></a>str | The path string to check. | none | 106*bcb5dc79SHONG Yifan| <a id="paths.is_normalized-look_for_same_level_references"></a>look_for_same_level_references | If True checks if path doesn't contain uplevel references ".." or single-dot references ".". | `True` | 107*bcb5dc79SHONG Yifan 108*bcb5dc79SHONG Yifan**RETURNS** 109*bcb5dc79SHONG Yifan 110*bcb5dc79SHONG YifanTrue if the path is normalized, False otherwise. 111*bcb5dc79SHONG Yifan 112*bcb5dc79SHONG Yifan 113*bcb5dc79SHONG Yifan<a id="paths.join"></a> 114*bcb5dc79SHONG Yifan 115*bcb5dc79SHONG Yifan## paths.join 116*bcb5dc79SHONG Yifan 117*bcb5dc79SHONG Yifan<pre> 118*bcb5dc79SHONG Yifanpaths.join(<a href="#paths.join-path">path</a>, <a href="#paths.join-others">others</a>) 119*bcb5dc79SHONG Yifan</pre> 120*bcb5dc79SHONG Yifan 121*bcb5dc79SHONG YifanJoins one or more path components intelligently. 122*bcb5dc79SHONG Yifan 123*bcb5dc79SHONG YifanThis function mimics the behavior of Python's `os.path.join` function on POSIX 124*bcb5dc79SHONG Yifanplatform. It returns the concatenation of `path` and any members of `others`, 125*bcb5dc79SHONG Yifaninserting directory separators before each component except the first. The 126*bcb5dc79SHONG Yifanseparator is not inserted if the path up until that point is either empty or 127*bcb5dc79SHONG Yifanalready ends in a separator. 128*bcb5dc79SHONG Yifan 129*bcb5dc79SHONG YifanIf any component is an absolute path, all previous components are discarded. 130*bcb5dc79SHONG Yifan 131*bcb5dc79SHONG Yifan 132*bcb5dc79SHONG Yifan**PARAMETERS** 133*bcb5dc79SHONG Yifan 134*bcb5dc79SHONG Yifan 135*bcb5dc79SHONG Yifan| Name | Description | Default Value | 136*bcb5dc79SHONG Yifan| :------------- | :------------- | :------------- | 137*bcb5dc79SHONG Yifan| <a id="paths.join-path"></a>path | A path segment. | none | 138*bcb5dc79SHONG Yifan| <a id="paths.join-others"></a>others | Additional path segments. | none | 139*bcb5dc79SHONG Yifan 140*bcb5dc79SHONG Yifan**RETURNS** 141*bcb5dc79SHONG Yifan 142*bcb5dc79SHONG YifanA string containing the joined paths. 143*bcb5dc79SHONG Yifan 144*bcb5dc79SHONG Yifan 145*bcb5dc79SHONG Yifan<a id="paths.normalize"></a> 146*bcb5dc79SHONG Yifan 147*bcb5dc79SHONG Yifan## paths.normalize 148*bcb5dc79SHONG Yifan 149*bcb5dc79SHONG Yifan<pre> 150*bcb5dc79SHONG Yifanpaths.normalize(<a href="#paths.normalize-path">path</a>) 151*bcb5dc79SHONG Yifan</pre> 152*bcb5dc79SHONG Yifan 153*bcb5dc79SHONG YifanNormalizes a path, eliminating double slashes and other redundant segments. 154*bcb5dc79SHONG Yifan 155*bcb5dc79SHONG YifanThis function mimics the behavior of Python's `os.path.normpath` function on 156*bcb5dc79SHONG YifanPOSIX platforms; specifically: 157*bcb5dc79SHONG Yifan 158*bcb5dc79SHONG Yifan- If the entire path is empty, "." is returned. 159*bcb5dc79SHONG Yifan- All "." segments are removed, unless the path consists solely of a single 160*bcb5dc79SHONG Yifan "." segment. 161*bcb5dc79SHONG Yifan- Trailing slashes are removed, unless the path consists solely of slashes. 162*bcb5dc79SHONG Yifan- ".." segments are removed as long as there are corresponding segments 163*bcb5dc79SHONG Yifan earlier in the path to remove; otherwise, they are retained as leading ".." 164*bcb5dc79SHONG Yifan segments. 165*bcb5dc79SHONG Yifan- Single and double leading slashes are preserved, but three or more leading 166*bcb5dc79SHONG Yifan slashes are collapsed into a single leading slash. 167*bcb5dc79SHONG Yifan- Multiple adjacent internal slashes are collapsed into a single slash. 168*bcb5dc79SHONG Yifan 169*bcb5dc79SHONG Yifan 170*bcb5dc79SHONG Yifan**PARAMETERS** 171*bcb5dc79SHONG Yifan 172*bcb5dc79SHONG Yifan 173*bcb5dc79SHONG Yifan| Name | Description | Default Value | 174*bcb5dc79SHONG Yifan| :------------- | :------------- | :------------- | 175*bcb5dc79SHONG Yifan| <a id="paths.normalize-path"></a>path | A path. | none | 176*bcb5dc79SHONG Yifan 177*bcb5dc79SHONG Yifan**RETURNS** 178*bcb5dc79SHONG Yifan 179*bcb5dc79SHONG YifanThe normalized path. 180*bcb5dc79SHONG Yifan 181*bcb5dc79SHONG Yifan 182*bcb5dc79SHONG Yifan<a id="paths.relativize"></a> 183*bcb5dc79SHONG Yifan 184*bcb5dc79SHONG Yifan## paths.relativize 185*bcb5dc79SHONG Yifan 186*bcb5dc79SHONG Yifan<pre> 187*bcb5dc79SHONG Yifanpaths.relativize(<a href="#paths.relativize-path">path</a>, <a href="#paths.relativize-start">start</a>) 188*bcb5dc79SHONG Yifan</pre> 189*bcb5dc79SHONG Yifan 190*bcb5dc79SHONG YifanReturns the portion of `path` that is relative to `start`. 191*bcb5dc79SHONG Yifan 192*bcb5dc79SHONG YifanBecause we do not have access to the underlying file system, this 193*bcb5dc79SHONG Yifanimplementation differs slightly from Python's `os.path.relpath` in that it 194*bcb5dc79SHONG Yifanwill fail if `path` is not beneath `start` (rather than use parent segments to 195*bcb5dc79SHONG Yifanwalk up to the common file system root). 196*bcb5dc79SHONG Yifan 197*bcb5dc79SHONG YifanRelativizing paths that start with parent directory references only works if 198*bcb5dc79SHONG Yifanthe path both start with the same initial parent references. 199*bcb5dc79SHONG Yifan 200*bcb5dc79SHONG Yifan 201*bcb5dc79SHONG Yifan**PARAMETERS** 202*bcb5dc79SHONG Yifan 203*bcb5dc79SHONG Yifan 204*bcb5dc79SHONG Yifan| Name | Description | Default Value | 205*bcb5dc79SHONG Yifan| :------------- | :------------- | :------------- | 206*bcb5dc79SHONG Yifan| <a id="paths.relativize-path"></a>path | The path to relativize. | none | 207*bcb5dc79SHONG Yifan| <a id="paths.relativize-start"></a>start | The ancestor path against which to relativize. | none | 208*bcb5dc79SHONG Yifan 209*bcb5dc79SHONG Yifan**RETURNS** 210*bcb5dc79SHONG Yifan 211*bcb5dc79SHONG YifanThe portion of `path` that is relative to `start`. 212*bcb5dc79SHONG Yifan 213*bcb5dc79SHONG Yifan 214*bcb5dc79SHONG Yifan<a id="paths.replace_extension"></a> 215*bcb5dc79SHONG Yifan 216*bcb5dc79SHONG Yifan## paths.replace_extension 217*bcb5dc79SHONG Yifan 218*bcb5dc79SHONG Yifan<pre> 219*bcb5dc79SHONG Yifanpaths.replace_extension(<a href="#paths.replace_extension-p">p</a>, <a href="#paths.replace_extension-new_extension">new_extension</a>) 220*bcb5dc79SHONG Yifan</pre> 221*bcb5dc79SHONG Yifan 222*bcb5dc79SHONG YifanReplaces the extension of the file at the end of a path. 223*bcb5dc79SHONG Yifan 224*bcb5dc79SHONG YifanIf the path has no extension, the new extension is added to it. 225*bcb5dc79SHONG Yifan 226*bcb5dc79SHONG Yifan 227*bcb5dc79SHONG Yifan**PARAMETERS** 228*bcb5dc79SHONG Yifan 229*bcb5dc79SHONG Yifan 230*bcb5dc79SHONG Yifan| Name | Description | Default Value | 231*bcb5dc79SHONG Yifan| :------------- | :------------- | :------------- | 232*bcb5dc79SHONG Yifan| <a id="paths.replace_extension-p"></a>p | The path whose extension should be replaced. | none | 233*bcb5dc79SHONG Yifan| <a id="paths.replace_extension-new_extension"></a>new_extension | The new extension for the file. The new extension should begin with a dot if you want the new filename to have one. | none | 234*bcb5dc79SHONG Yifan 235*bcb5dc79SHONG Yifan**RETURNS** 236*bcb5dc79SHONG Yifan 237*bcb5dc79SHONG YifanThe path with the extension replaced (or added, if it did not have one). 238*bcb5dc79SHONG Yifan 239*bcb5dc79SHONG Yifan 240*bcb5dc79SHONG Yifan<a id="paths.split_extension"></a> 241*bcb5dc79SHONG Yifan 242*bcb5dc79SHONG Yifan## paths.split_extension 243*bcb5dc79SHONG Yifan 244*bcb5dc79SHONG Yifan<pre> 245*bcb5dc79SHONG Yifanpaths.split_extension(<a href="#paths.split_extension-p">p</a>) 246*bcb5dc79SHONG Yifan</pre> 247*bcb5dc79SHONG Yifan 248*bcb5dc79SHONG YifanSplits the path `p` into a tuple containing the root and extension. 249*bcb5dc79SHONG Yifan 250*bcb5dc79SHONG YifanLeading periods on the basename are ignored, so 251*bcb5dc79SHONG Yifan`path.split_extension(".bashrc")` returns `(".bashrc", "")`. 252*bcb5dc79SHONG Yifan 253*bcb5dc79SHONG Yifan 254*bcb5dc79SHONG Yifan**PARAMETERS** 255*bcb5dc79SHONG Yifan 256*bcb5dc79SHONG Yifan 257*bcb5dc79SHONG Yifan| Name | Description | Default Value | 258*bcb5dc79SHONG Yifan| :------------- | :------------- | :------------- | 259*bcb5dc79SHONG Yifan| <a id="paths.split_extension-p"></a>p | The path whose root and extension should be split. | none | 260*bcb5dc79SHONG Yifan 261*bcb5dc79SHONG Yifan**RETURNS** 262*bcb5dc79SHONG Yifan 263*bcb5dc79SHONG YifanA tuple `(root, ext)` such that the root is the path without the file 264*bcb5dc79SHONG Yifanextension, and `ext` is the file extension (which, if non-empty, contains 265*bcb5dc79SHONG Yifanthe leading dot). The returned tuple always satisfies the relationship 266*bcb5dc79SHONG Yifan`root + ext == p`. 267*bcb5dc79SHONG Yifan 268*bcb5dc79SHONG Yifan 269*bcb5dc79SHONG Yifan<a id="paths.starts_with"></a> 270*bcb5dc79SHONG Yifan 271*bcb5dc79SHONG Yifan## paths.starts_with 272*bcb5dc79SHONG Yifan 273*bcb5dc79SHONG Yifan<pre> 274*bcb5dc79SHONG Yifanpaths.starts_with(<a href="#paths.starts_with-path_a">path_a</a>, <a href="#paths.starts_with-path_b">path_b</a>) 275*bcb5dc79SHONG Yifan</pre> 276*bcb5dc79SHONG Yifan 277*bcb5dc79SHONG YifanReturns True if and only if path_b is an ancestor of path_a. 278*bcb5dc79SHONG Yifan 279*bcb5dc79SHONG YifanDoes not handle OS dependent case-insensitivity. 280*bcb5dc79SHONG Yifan 281*bcb5dc79SHONG Yifan**PARAMETERS** 282*bcb5dc79SHONG Yifan 283*bcb5dc79SHONG Yifan 284*bcb5dc79SHONG Yifan| Name | Description | Default Value | 285*bcb5dc79SHONG Yifan| :------------- | :------------- | :------------- | 286*bcb5dc79SHONG Yifan| <a id="paths.starts_with-path_a"></a>path_a | <p align="center"> - </p> | none | 287*bcb5dc79SHONG Yifan| <a id="paths.starts_with-path_b"></a>path_b | <p align="center"> - </p> | none | 288*bcb5dc79SHONG Yifan 289*bcb5dc79SHONG Yifan 290