‘filesysobjects.apppaths’ - Module

The filesysobjects.apppaths module provides advanced operations on application resource paths and search paths.

Implementation Details

Glob Parameters

The ‘glob‘ wildcard definitions are a subset of regular expressions which additionally deviate slightly by their semantics. In the case of a dot for example this could be in addition ambiguous.

# file path name: /a/b/xname
path0 = '/a/b/x.*'

# regexpr: matches
# glob:    does not match

Therefore the resolution of contained path-elements as ‘glob’ expressions are resolved dynamically by applying the glob module onto the file system nodes. See also Variants of Pathname Parameters - Literals, RegExpr, and Glob.

Regular Expressions

The regular expressions support the full scope of the standard Pyhton ‘re‘ module. The expressions are used as post-filter onto a set of fetched file system node path names.

The regexpr are by default compiled/loaded statically during load time of the module. The regular expressions for the path analysis contain the ‘os.path.sep‘ of the current platform which could be altered as parameter by some interfaces. In this case the function interfaces compile the adapted regexpr into a local stack-variable, where the compiled match object is cached by the module ‘re‘, but potentially will be compiled for each call again. The object interface may nont have to handle with this within the lifetime of the instances. See also Variants of Pathname Parameters - Literals, RegExpr, and Glob.

Common Call Parameters

spath

The path to be processed. Valid scope types:

type	description	example
literal	literal match	‘/my/path/file01.ext’
re	Python regular expression re	‘/my/path/file[0-3]{2}.ext’
glob	Python glob	‘/my/path/file[0-3][0-3].ext’

Special precautions are required in case of ambiguity. For example the syntax term

/./  or \\.\\

has already different meanings in the syntax domains, but last not least adds another semantic for common filesystems.

1. the dot is literally a dot for literals and globs
2. the dot is any character for regualr expressions
3. the dot as a single character is the current directory for most filesystems

The ambiguity could be resolved e.g. by

/.{1}/
/\./
/[.]/

plist

List of path strings to be searched. By default first match is used. The concrete processing varies by the interfaces.

['/my/search/path0', '/my/search/path1', '/my/search/path2']

default := sys.path

appre - Application Prefix

Adds application prefix, URI scheme. This also forces the appropriate path separator for specific standards.

apppre = (True|False)

The application prefix e.g. for file-URI [RFC8089] is added as

apppre = True

 /a/b/c             =>  file:///a/b/c
 c:\a\b\c           =>  file:c:/a/b/c    # see [RFC8089] Appendix
 \a\b\c             =>  file:///a/b/c    # see [RFC8089] Appendix

apppre = False

 /a/b/c              =>  /a/b/c
 c:\a\b\c            =>  c:\a\b\c        # see [RFC8089] Appendix
 \a\b\c              =>  \a\b\c          # see [RFC8089] Appendix
 file:///a/b/c       =>  file:///a/b/c
 file:c:\a\b\c       =>  file:c:/a/b/c   # see [RFC8089] Appendix
 file:c:/a/b/c       =>  file:c:/a/b/c   # see [RFC8089] Appendix
 file://\a\b\c       =>  file:///a/b/c   # see [RFC8089] Appendix
 file:///a/b/c       =>  file:///a/b/c   # see [RFC8089] Appendix

default := False

appsplit - Split

Adds application prefix, URI scheme. This also forces the appropriate path separator for specific standards.

appsplit = (True|False)

The application prefix e.g. for file-URI [RFC8089] is added as

/a/b/c    =>  file:///a/b/c
c:\a\b\c  =>  file:c:/a/b/c  # see [RFC8089] Appendix
\a\b\c    =>  file:///a/b/c  # see [RFC8089] Appendix

default := False

keepsep

Modifies the behavior of ‘strip’ parameter. If ‘False’, the trailing separator is dropped.

splitapppathx('/a/b', keepsep=False)   => ('', 'a', 'b')
splitapppathx('/a/b/', keepsep=False)  => ('', 'a', 'b')

for ‘True’ trailing separators are kept as directory marker:

splitapppathx('/a/b', keepsep=True)    => ('', 'a', 'b')
splitapppathx('/a/b/', keepsep=True)   => ('', 'a', 'b', '')

The following defaults apply:

default := False # for URIs except file://, smb://
default := True  # for file path names

pathsep

Replaces path separator set by the spf, e.g. for a URI pathlist from an alternate platform. The resulting character selects the type of the scanner APPPATHSCANNER [source].

pathsep := (';' | ':')

Is used in the absence of spf as the platform discriminator.

The path separator also effects the compilation of regular expressions, when these contain free separator characters, which are interpreted and transformed accordingly to the choosen platform.

strip

Strips null-entries, reduces by dropping redundancies. The strip parameter influences the match of regular expressions, which just do a pattern match, thus hit null-separator directories too. The strip of these prevents from unwanted matches on separator characters.

strip := (
     True      # clear null-separators
   | False     # no strip at all
   | all       # clear any redundancy
   | contain   # contained sub directories
   | multiple  # multiple occurance
)

The True and False parameters are supported commonly, while the remaining are supported by special interfaces only.

default := True

stripquote

Strips special Python style filesysobject triple-quotes.

/my/path/with/"""double-quoted"""/dirs => /my/path/with/double-quoted/dirs
/my/path/with/'''single-quoted'''/dirs => /my/path/with/single-quoted/dirs

Current version does not support nested triple-quotes; neither homogeneous, nor heterogeneous.

spf - Source Platform

The Source-Platform, defines the characters to be used as path separator, and the additional concrete semantics for the specific platform. The platform is hereby associated with a specific resource address type, this is the common standard. Default is the current platform, with a single character for the ‘os.pathsep’ and the support for the specific semantics like DOS drives for the platform ‘win’. Application and URL/URI file prefixes and tags like ‘smb://‘, ‘file:’, ‘file://‘, ‘file:////‘, and ‘file://///‘ are detected in any case. Thus these are treated as reserved words.

The syntax is:

spf := (<predefined>|<bitmask>|<pathsep>)

bitmask := (
      RTE_WIN32  | RTE_POSIX | RTE_LINUX
    | RTE_DARWIN | RTE_BSD
)
pathsep := (':' | ';')
predefined := (
    'bsd' | 'darwin' | 'linux' | 'posix' | 'solaris'
    | 'uri' | 'win' | 'win32'
)

For details refer to paths.getspf()

• posix, RTE_POSIX:

  The Posix platform, is aware of the posix syntax and semantics, single character ‘/’ as separator. Ignored pattern for potential DOS drives.

• win, RTE_WIN32:

  The Windows platform. Is aware of the Windows syntax and semantics, single character ‘\’ as separator. Recognizes string pattern of DOS drives.

• RTE_LINUX, RTE_DARWIN, RTE_BSD

  The Linux, Darwin/OS-X, BSD, and the Solaris platform are mapped to the Posix style file path names.

For mixed input for example:

spf := ':;'

See also tpf and spf.

tpf - Target Platform

Target platform for the file pathname. The platform is hereby associated with a specific resource address type, this is the common standard. Due to some deviations from the expected behavior in case of cross platform development the following options are defined:

tpf	numeric	compatible to os.normpath	cross platform	behaviour
cnp		yes(posix)	no	calls posixpath.normpath()
cnw		yes(win)	no	calls ntpath.normpath()
local		yes	no	calls local os.path.normpath()
posix	RTE_POSIX	no (*pchar)	yes* Portable for IEEE1003.1	transforms all separators to ‘/’ or ‘:’
uri		no	yes	transforms all separators to ‘/’
win	RTE_WIN32	no	no	transforms all separators to ‘\\’ or ‘;’
default		no	no	adapts ‘win’(on win) or ‘posix’(on posix) to local os

For details refer to paths.gettpf(), for a detailed comparison refer to ‘filesysobjects.normpathx’ vs. ‘os.path.normpath’.

local:

Compatible to local ‘os.path.normpath()’, this includes the original permitted input characters.

On POSIX platforms(Linux, MacOS, ...), e.g.:

d:/  => d:
d:\\  => d:\\

On Windows platforms, e.g.:

d:/  => d:\\
d:\\  => d:\\

posix:

POSIX based style with os.path.sep = ‘/’ and os.pathsep = ‘;’. The special escape-characters are kept, additionally the following chars by escaping: [/\\:;]. The special case of ambiguous non-intentionally escape-character ‘\\\\’ could be eliminated by an odd number of ‘\\’.

E.g. Linux, MacOS/OS-X, BSD, Solaris, etc.:

d:/  => d:/
d:\\  => d:/

This mode is literally compatible across all supported platforms.

win:

MS-Windows style with os.path.sep= ‘\\’ and os.pathsep = ‘:’. The special escape-characters are kept, additionally the following chars by escaping: [/\\:;]. The special case of ambiguous non-intentionally escape-character ‘\\\\’ could be eliminated by an odd number of ‘\\’.

d:/  => d:\\
d:\\  => d:\\

This mode is literally compatible across all supported platforms.

default:

Adapt ‘os.path.sep’ and ‘os.pathsep’ to local native os, else wise the same behavior as the modes ‘posix’ or ‘win’.

This mode is in term of the structure including drives of Windows based file systems compatible across all supported platforms. But the os.path.sep, and the os.pathsep are adapted to the local platform.

On POSIX platforms(Linux, MacOS, ...), e.g.:

d:/  => d:
d:\\  => d:\\

On Windows platforms, e.g.:

d:/  => d:\\
d:\\  => d:\\

See also tpf and spf.

Supported Conversions

The filesysobjects provides functions for the normalization and the split of resource paths. This includes the cross-conversion of the major filesysytem platforms Posix and Windows. In addition various conversions are supported. These comprise the equivalent conversion between semantically compatible representations, and the conversion between syntactical compatible respresentations without assured semantic equivalency. The latter requires for the semantical equivalency additional conventions, e.g. for the conversion of ‘z:mypath’ from windows to Posix.

The split of all supported platforms for custom applications is supported.

normpathx

The normpathx supports the normalization of resource paths for the native platform, and the cross-conversion for a limited set of other platforms when the call parameters spf and tpf are used.

The following basic cross-conversions are supported.

	posix	win	cygwin	file (0)	file (2)	file (3)	file (4)	file (5)	unc
posix	c	f	c	c	c	c
win	f	c	c	c	c	c
cygwin	c	c	c	c	c	c
file (0)	c	c	c	c	c	c
file (2)					c
file (3)	c	c	c	c	c	c
file (4)							c	c	c
file (5)							c	c	c
unc		f	f				c	c	c

c: Could be converted into equivalent representation.

f: Format conversion without assured equivalency. The accuracy depends on additional conventions.

(0): file uri - short form:

'file:/my/path'   == '/my/path'
'file:c:/my/path' == 'c:/my/path' == 'c:\my\path'

(2): file uri - remote file:

'file\://myhost/my/path' == '//myhost/my/path'

(3): file uri - traditional:

'file:///my/path'== '/my/path'

(4): file uri - UNC:

'file:////myhost/myshare/my/path' == '\\myhost\myshare\my\path'

(5): file uri - UNC:

'file://///myhost/myshare/my/path' == '\\myhost\myshare\my\path'

For details of the sub-conversion, e.g. file-URI with 4 or 5 slashes refer to the API.

normapppathx and normpathx

The following basic cross-conversions by the functions normapppathx and normpathx between source and target platforms are supported. The call parameters spf and tpf control the representation.

	posix	win	cygwin	file (0)	file (2)	file (3)	file (4)	file (5)	unc	smb	cifs	http	https
posix	c	f	c	c	c	c
win	f	c	c	c	c	c			c
cygwin	c	c	c
file (0)	c	c	c	c	c	c
file (2)										f	f
file (3)	c	c	c	c		c				f	f
file (4)									c	f	f
file (5)									c	f	f
unc		c					c	c	c	c	c
smb		c					c	c	c	c	c
cifs		c					c	c	c	c	c
http												c	c
https												c	c

c: Could be converted into equivalent representation.

f: Format conversion without assured equivalency. The accuracy depends on additional conventions.

(0): file uri - short form: ‘file:/my/path‘, ‘file:c:/my/path‘

(2): file uri - remote file: ‘file://myhost/my/path‘

(3): file uri - traditional: ‘file:///my/path‘

(4): file uri - UNC: ‘file:////myhost/myshare/my/path‘

(5): file uri - UNC: ‘file://///myhost/myshare/my/path‘

For details of the sub-conversion, e.g. file-URI with 4 or 5 slashes refer to the API.

spliapppathx and splitpathx

The split-functions splitapppathx and splitpathx for custom behaviour are applicable on all supported types. This includes also the conversion of the path component.

Module

The ‘filesysobjects.apppaths’ module provides operations on static application resource paths.

Constants

Application Path Scanner - Parser

The scanner and parser for application resource name rules in accordance to Posix/IEEE-1003.1 [POSIX], UNC [MS-DTYP]/[MS-SMB]/[MS-CIFS]/[FAT], URI [RFC8089]/[RFC3986], and others. Provides for multiple mixed entries in search-path syntax, adds some minor causal constraints on esoteric and rare cases for ambiguity resolution.

The base for the application resource path compilers of filesysobjects.apppaths.normapppathx and filesysobjects.apppaths.splitapppathx.

• APPPATHPARSER

  The main regular expression for split of PATH variables with support for URIs.

  filesysobjects.apppaths.APPPATHSCANNER_COL = <_sre.SRE_Pattern object at 0x26e8370>

  Scanner/Parser for colon based search path separator:

  os.pathsep == ':'
  

  The applied rules are:

   4: ('file://[/]' +2SEP | unc://)  +(host)  +1SEP  +(share)  +(object)  # [MS-DTYP] 2.2.57
  12: ('file://')                    +()      +()    +(drive)  +(path)    # RFC8089 -
  20: ('file://')                    +(auth)  +()    +()       +(path)    # RFC8089 - non-local files
  28: ('file://|file:')              +()      +()    +()       +(path)    # RFC8089 - traditional
  36: ('smb://'|'cifs://')  +(host)  +1SEP  +(share)  +(path)             # RFC-SMB
  44: (2SEP)                +(host)  +1SEP  +(share)  +(path)             # [MS-DTYP] 2.2.57 - a share present
  52: (scheme '://')           +(auth)  +1SEP  +(path)   +"?" +(query-fragment)  # RFC3869
  60: ()                    +()      +()    +(drive)  +(path)             # MS-DOS / WIN
  68: ()                    +()      +()    +(drive)  +(path)             # MS-DOS / WIN
  76: ()                    +()      +()    +(drive)  +()                 # MS-DOS / WIN
  84: ()                    +()      +()    +()       +(path)             # general filesystems
  92: ()                    +()       +()   +()       +()
  94 os.pathsep
  

  filesysobjects.apppaths.APPPATHSCANNER_SEM = <_sre.SRE_Pattern object at 0x26d7fd0>

  Scanner/Parser for semicolon based search path separator.

  os.pathsep == ';'
  

  The applied rules are corresponding to APPPATHSCANNER_COL.

• APPPATHINDEX

  filesysobjects.apppaths.APPPATHINDEX = (4, 12, 20, 28, 36, 44, 52, 60, 68, 76, 84, 92)

  Helper with group indexes pointing onto the supported syntax terms of APPPATHSCANNER.

• APPTYPES

  filesysobjects.apppaths.APPTYPES = ('share', 'ldsys', 'rfsys', 'lfsys', 'smb', 'share', 'uri', 'ldsys', 'ldsys', 'ldsys', 'lfsys', 'lfsys')

  Helper with human readable enums for types of path variable elements of APPPATHINDEX.

• APPTYPES_L2

  filesysobjects.apppaths.APPTYPES_L2 = {'//': ('share',), 'cifs://': ('smb',), '\\\\': ('share',), 'http://': ('http',), 'https://': ('https',), 'smb://': ('smb',), 'unc://': ('share',)}

  Helper with human readable enums for secondary level-2 types of APPTYPES.

Functions

addpath_to_searchpath

filesysobjects.apppaths.addpath_to_searchpath(spath, plist=None, **kargs)

Adds a path to ‘plist’.

In case of relative path searches in provided ‘plist’, or ‘kargs[searchplist]’a hook, when found verifies the existence within file system, in case of success adds the completed path to ‘plist’ the list.

In case of ‘glob’ adds all entries.

Args:

spath:

A path to be added to ‘plist’. See common options for details. Valid scope types:

• literal : X
• re : -
• blob : -

default := caller-file-position.

plist:

List to for the storage, and by default search list too. See common options for details.

default := sys.path

kargs:

append:

Append, this is equal to pos=len(plist).

checkreal:

Checks redundancy by resolving real path, else literally.

exist:

Checks whether exists, else nothing is done.

pos:

A specific position for insertion within range(0,len(plist)).

pos := #pos

prepend:

Prepend, this is equal to pos=0.

redundant:

Add relative, allow redundant when same is already present.

relative:

Add relative sub path to provided base.

relative := <base>:

searchplist:

Alternative list to search for checks.

spf:

Source platform, defines the input syntax domain. For the syntax refer to API in the manual at spf.

For additi0onal details refer to tpf and spf, paths.getspf(), normapppathx(), normpathx().

tpf:

Source platform, defines the input syntax domain. For the syntax refer to the API in the manual at tpf.

For additi0onal details refer to tpf and spf, paths.gettpf(), normapppathx(), normpathx().

Returns:

When successful returns insertion position, else a ‘value<0’. The insertion position in case of multiple items is the position of the last.

Raises:

AppPathError passed through exceptions

delpath_from_searchpath

filesysobjects.apppaths.delpath_from_searchpath(dellist, plist=None, **kargs)

Deletes a list of paths from ‘plist’.

Args:

dellist:

A list of paths to be deleted from ‘plist’. Valid scope types:

• literal : X
• re : X
• glob : X

see kargs[regexpr|glob].

default := None

plist:

List of search paths.

default := sys.path

kargs:

The following keys are additional before comparison, on ‘dellist’ only when no match pattern is provided:

case:

Calls on both: os.path.normcase

esc:

Calls on both: escapepathx/unescapepathx

exist:

Calls on both: os.path.exists

noexist:

Calls on both: not os.path.exists

norm:

Calls on both: normpathx

norm:

Calls on both: os.path.normpath

real:

Calls on both: os.path.realpath

regexpr|glob:

Input is a list of

regexpr:

regular expressions, just processed by

‘re.match(dl,pl)’

glob:

process glob, and check containment in set

Returns:

When successful returns True, else False.

Raises:

passed through exceptions

gettop_from_pathstring

filesysobjects.apppaths.gettop_from_pathstring(spath, plist=None, **kargs)

Searches for a partial path spath in a list of search paths plist. The current version supports for pure in-memory evaluation of literals and regexpr.

The following example of input with default parameters

spath := 'a/b/c'
plist := [
   '/my/path/a/c/x/y/a/b/x/d/e/r',
   '/my/path/a/c/x/y/a/b/c/d/e/r',
]

results in the first match:

result := '/my/path/a/c/x/y/a/b/c'
#
# shortes top-match: '/my/path/a/c/x/y/' + 'a/b/c'
#

Same for a regular expression:

spath := 'a/.*/[cxy]/[def]{1}'

results again in:

result := '/my/path/a/c/x/y/a/b/c'

The match is performed by the re module based on re.split spanning multiple directories in case of reguar expressions. Thus the expressions require some caution when constraints are required. The function itself serves as a framework providing parameterization of the match criteria.

Args:

spath:

A path to be appended to an item from ‘plist’.

plist:

List of search strings to be extended by the subpath spath.

default := sys.path

kargs:

hook:

Returns the insertion point of spath without the spath itself.

keepsep:

Keeps significant separators, e.g. a trailing ‘os.sep’.

default := True

matchidx:

Use the n-th match of the resulting path component only. The path component excludes the authority and share for network paths.

matchidx := #idx:

0 <= idx   ; first match

• Ignore matches for ‘< #idx‘
• return match for ‘== #idx‘, and stop search

default := 0 # first match

Depends on reverse.

pathsep:

Replaces the path separator set by the spf.

pathsep := (';' | ':')

pattern:

Sets and activates scope and type of match pattern. The pattern is matched node-by-node for each corresponding directory level:

pattern := (literal | regexpr)

• literal:

  Match literally. Pattern are treated as characters.

• regexpr:

  Match regular expression for individual nodes, implies no contained reserved characters of the current file system, so ‘os.sep’ and no ‘os.pathsep’.

default := literal

raw:

Suppress normalization by call of ‘os.path.normpath’.

reverse:

This reverses the resulting search order from bottom-up to top-down. Takes effect on ‘redundant’ only.

split:

Returns the path prefix matched on the search list, and the relative sub path outside the search list as a tuple.

split := (True | False)

For example the input:

spath := 'a/b/c'
plist := [
   '/my/path/a/c/x/y/a/b/x/d/e/r',
   '/my/path/a/c/x/y/a/b/c/d/e/r',
]

results in:

result := ('/my/path/a/c/x/y', 'a/b/c')

spf:

Source platform, defines the input syntax domain. For the syntax refer to API in the manual at spf.

For additi0onal details refer to tpf and spf, paths.getspf(), normapppathx(), normpathx().

strip:

Strips null-entries.

default := True

tpf:

Source platform, defines the input syntax domain. For the syntax refer to the API in the manual at tpf.

For additi0onal details refer to tpf and spf, paths.gettpf(), normapppathx(), normpathx().

Returns:

When successful returns by default the expanded pathname, else None. The return value in case of success depends on the parameters:

• if split == True: returns a tuple

  result = (result[0], result[1],)
  

  result[0]: The matched path including the resolved searched sub-path spath.

  result[1]: The remainder.

• if split == True and hook == True: returns a tuple

  result = (result[0], result[1], result[2],)
  

  result[0]: The matched path excluding the sub-path spath.

  result[1]: The resolved searched sub-path spath.

  result[2]: The remainder.

• else: returns an str

  result = <str>
  

  • if hook == True:

    The matched path excluding the sub-path spath and an evtl. present remainder.

  • else:

    A string of the matched path including the resolved searched sub-path spath, excluding an evtl. present remainder.

Raises:

AppPathError

FileSysObjectsError

passed-through

gettop_from_pathstring_iter

filesysobjects.apppaths.gettop_from_pathstring_iter(spath, plist=None, **kargs)

Iterates all matches in plist,see gettop_from_pathstring.

join_apppathx_entry

filesysobjects.apppaths.join_apppathx_entry(entry, **kw)

Assembles the components of an application path entry.

Known standard applications are:

cifs , file, ftp, http, https, smb, unc, uri
<unc-file-path>, <posix-app-file-path>

The path entry is not normalized again, thus has to be in the appropriate platform syntax.

Args:

entry:

Application entry as provided by splitapppathx().

kw:

apppre:

Add application prefix.

tpf:

Target platform.

Returns:

Entry as a single stings.

Raises:

pass-through

normapppathx

filesysobjects.apppaths.normapppathx(spath, **kargs)

Generic extention of normpathx() by application schemes and search path syntax.

Args:

spath:

Accepts path, or search-path.

kargs:

Supports the parameters of splitapppathx()

apppre:

Application scheme.

appsplit:

Split into scheme and components of an application path.

spf:

Source platform.

tpf:

Target platform.

Returns:

Normalized path or search-path.

Raises:

pass-through: see splitapppathx()

set_uppertree_searchpath

filesysobjects.apppaths.set_uppertree_searchpath(start=None, top=None, plist=None, **kargs)

Prepends each directory path from from ‘start’ on upward to ‘top’ in-place into plist. For example:

start :=  /my/top/a/b/c
top   :=  /my/top

results in:

plist := [
   '/my/top/a/b/c',
   '/my/top/a/b',
   '/my/top/a',
   '/my/top',
]

Args:

start:

Start components of a path string. See common options for details. Valid scope types:

• literal : X
• re : -
• blob : -

default := caller-file-position.

top:

End component of a path string. The node ‘top’ is included. Valid scope types:

• literal : X
• re : -
• blob : -

default := <same-as-start>

plist:

List to for the storage. See common options for details.

default := sys.path

kargs:

append:

Appends the set of search paths.

matchidx:

Ignore matches ‘< #idx’, adds match ‘== #idx’ and returns.

matchidx := #idx

default := 0 # all

matchcnt:

The maximal number of matches returned when multiple occur.

matchcnt=#num:

matchlvl:

Increment of match for top node when multiple are in the path.

matchlvl := #num:

See common options for details.

matchlvlbackward:

Increment of match for top node when multiple are in the path.

matchlvlbackward := #num:

See common options for details.

noTypeCheck:

Suppress required identical types of ‘top’ and ‘start’. As a rule of thumb for current version, the search component has to be less restrictive typed than the searched. The default applicable type matches are:

 top    ¦ start
--------+---------------------
 lfsys  ¦ lfsys, ldsys, share
        | smb, cifs,
 ldsys  ¦ ldsys
 share  ¦ share
 smb    ¦ smb
 cifs   ¦ cifs
 http   ¦ http, https
 https  ¦ https, http

See common options for details.

prepend:

Prepends the set of search paths. This is default.

raw:

Suppress normalization by call of ‘os.path.normpath’.

relonly:

The paths are inserted relative to the top node only. This is mainly for test purposes. The intermix of relative and absolute path entries is not verified.

reverse:

This reverses the resulting search order

from bottom-up to top-down.

unique:

Insert non-present only, else present entries are not checked, thus the search order is changed in general for ‘prepend’, while for ‘append’ the present still covers the new entry.

Returns:

When successful returns ‘True’, else returns either ‘False’, or raises an exception.

Raises:

AppPathError

pass-through

splitapppathx

filesysobjects.apppaths.splitapppathx(spath, **kargs)

Splits PATH variables which may include URI type prefixes into a list of single path entries. The default behavior is to split a search path into a list of contained path entries. E.g:

p = 'file:///a/b/c:/d/e::x/y:smb://host/share/q/w:http://host/a/b/:https://host/a?xy#123'

Is split into:

px = [
    'file:///a/b/c',
    'file://host/a/b/c',
    'file://///host/share/a/b/c',
    '/d/e',
    '',
    'x/y',
    'smb://host/share/q/w',
    '//host/share/q/w',
    'http://a/b/',
    'https://host/a?xy#123',
]

With parameter ‘appsplit‘ set the paths entries are sub-split into their schemes and type specific items

px = [
    ('lfsys',   '',      '',       '/a/b/c'),
    ('rfsys',   'host',  '',       '/a/b/c'),
    ('unc',     'host',  'share',  '/a/b/c'),
    ('lfsys',   '',      '',       '/d/e'),
    ('lfsys',   '',      '',       ''),
    ('lfsys',   '',      '',       'x/y'),
    ('smb',     'host',  'share',  'q/w'),
    ('share',   'host',  'share',  'q/w'),
    ('share',   'host',  'share',  'q/w'),

    ('http',    'host',   '',      '/a/b/',   ''),
    ('https',   'host',   '',      '/a',      'xy#123'),
]

For reserved prefix keywords as parts of the name, these should be escaped.

Args:

spath:

The search path to be split.

kargs:

The provided key-options are also transparently passed through to ‘normpathx()’ [see] - if not ‘raw’.

apppre:

Adds application prefix.

appsplit = (True|False)

default := False

appsplit:

Splits into tuples of application entries.

appsplit = (True|False)

default := False

For example:

file:///my/path/a

results for True in:

(lfsys, '', '', '/my/path/a')

delnulpsep:

Delete empty search paths.

default := True

escape:

Escapes backslash.

default := False

keepsep:

Modifies the behavior of ‘strip’ parameter. If ‘False’, the trailing separator is dropped.

splitapppathx('/a/b', keepsep=False)   => ('', 'a', 'b')
splitapppathx('/a/b/', keepsep=False)  => ('', 'a', 'b')

for ‘True’ trailing separators are kept as directory marker:

splitapppathx('/a/b', keepsep=True)    => ('', 'a', 'b')
splitapppathx('/a/b/', keepsep=True)   => ('', 'a', 'b', '')

default := False # for URIs except file://, smb:// default := True # for file path names

normpathx:

Calls normapthx() on path-part.

normpathx := (
     True   # call normpathx
   | False  # do not normalize
)

default := True

pathsep:

Replaces path separator set by the spf, e.g. for a URI pathlist from an alternate platform. The resulting path separator selects the type of the scanner APPPATHSCANNER.

pathsep := (';' | ':')

raw:

Displays a list of unaltered split path items, superposes ‘rpath’ and ‘rtype’.

raw = (True|False)

default := False

rpath:

Displays the path as provided raw sub string.

For further details refer to ‘splitapppathx’ [see].

rpath = (True|False)

rtype:

Displays the type prefix as provided raw sub string.

For further details refer to ‘splitapppathx’ [see].

rtype = (True|False)

spf:

Source platform, defines the input syntax domain. For the syntax refer to API in the manual at spf.

For additi0onal details refer to tpf and spf, paths.getspf(), normapppathx(), normpathx().

strict:

Validates for the target OS/FS, throws exception when invalid characters are contained.

strip:

Strips null-entries.

default := True

tpf:

Source platform, defines the input syntax domain. For the syntax refer to the API in the manual at tpf.

For additi0onal details refer to tpf and spf, paths.gettpf(), normapppathx(), normpathx().

unescape:

Unescapes backslash.

default := False

Returns:

When split successful returns a list of tuples:

appsplit == False

    [
        <pathvar-item>,
        ...
    ]

appsplit == True

    [
        (TYPE, host-name, share-name, pathname),
        ...
    ]

The tuple contains:

(TYPE, host-name, share-name, pathname)

  TYPE := (raw|cifs|smb|share|http|https|lfsys|rfsys|ldsys)
     raw := (<raw-pathvar-item>)
     cifs := ('cifs://')
     smb := ('smb://')
     share := ('file:///'+2SEP|'file://'+2SEP|2SEP)
     rfsys := ('file://')
     lfsys := ('file://'|'')
     ldsys := [a-z]':'

     http := ('http://')
     https := ('http://')

  host-name := (host-name|'')
  share-name := (valid-share-name|'')
  valid-share-name := (
     smb-share-name
     | cifs-share-name
     | win-drive-share-name
     | win-drive-os
     | win-special-share-name
  )
  pathname := "pathname on target"

specials:

   raw := ('raw', '', '', raw-pathvar-item)
   rpath := (TYPE, host-name, share-name, raw-pathname)
   rtype := (raw-type, host-name, share-name, pathname)
   rtype + rpath := (raw-type, host-name, share-name, raw-pathname)

For compatibility the URI for http/https adds one item ‘query+fragment’, while the share remains empty.

('http' | 'https') := (TYPE, host-name, '', pathname, query+fragment)

else:

('lfsys', '', '', apstr)

REMARK:

The hostname may contain in current release any suboption, but is not tested with options at all.

Raises:

PathError

passed-through

splitapppathx_getlocalpath

filesysobjects.apppaths.splitapppathx_getlocalpath(elems, **kargs)

Joins application elements to a path for local access.

Args:

elems:

Elements as provided by ‘splitapppathx’

kargs:

tpf:

Target platform for the file pathname, for details refer to normpathx().

Returns:

When successful the local access path, else None.

Raises:

AppPathError passed through exceptions

Exceptions

AppPathError

exception filesysobjects.apppaths.AppPathError

Path error.