filesysobjects.plugins package

Submodules

filesysobjects.plugins.http module

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

filesysobjects.plugins.http.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.

filesysobjects.plugins.http.APPPATHSCANNER_COL = <_sre.SRE_Pattern object at 0x3bcc4e0>

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)
20: ('file://')                    +(auth)  +()    +()       +(path)
28: ('file://')                    +()      +()    +()       +(path)
36: ('smb://'|'cifs://')  +(host)  +1SEP  +(share)  +(path)
44: (2SEP)                +(host)  +1SEP  +(share)  +(path) # in general a share present - on POSIX too???
52: (scheme '://')           +(auth)  +1SEP  +(path)   +"?" +(query-fragment)
60: ()                    +()      +()    +(drive)  +(path)
68: ()                    +()      +()    +(drive)  +(path)
76: ()                    +()      +()    +(drive)  +()
84: ()                    +()      +()    +()       +(path)
92: ()                    +()       +()   +()       +()
94 os.pathsep
filesysobjects.plugins.http.APPPATHSCANNER_SEM = <_sre.SRE_Pattern object at 0x3fa0ca0>

Scanner/Parser for semicolon based search path separator.

os.pathsep == ';'

The applied rules are corresponding to APPPATHSCANNER_COL.

filesysobjects.plugins.http.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.

filesysobjects.plugins.http.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.

filesysobjects.plugins.http.ESC_CHAR_MAP = {'\x07': '\\a', '\t': '\\t', '\x08': '\\b', '\x0b': '\\v', '\n': '\\n', '\r': '\\r', '\x0c': '\\f'}

maps unambiguous escape characters to escape sequences

filesysobjects.plugins.http.INVALIDCHARS = <_sre.SRE_Pattern object at 0x3c701c0>

super position of both: r’[:<>*?0]’

filesysobjects.plugins.http.INVALIDCHARSPOSIX = <_sre.SRE_Pattern object at 0x3147140>

posix:

r'\0'
filesysobjects.plugins.http.INVALIDCHARSWIN = <_sre.SRE_Pattern object at 0x3c70990>

windows:

r'[:<>*?]'
filesysobjects.plugins.http.OSSEP = '/'

os separator

filesysobjects.plugins.http.OSSEPCLS = '[/]'

character class os separator

filesysobjects.plugins.http.OSSEPCLSN = '[^/]'

character class without separator

filesysobjects.plugins.http.UNESC_CHAR_MAP = {'a': '\x07', 'b': '\x08', 'f': '\x0c', 'n': '\n', 'r': '\r', 't': '\t', 'v': '\x0b'}

maps escape characters for escape sequences to unescape

filesysobjects.plugins.http.addpath_to_searchpath(spath, plist=None, **kargs)[source]

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
filesysobjects.plugins.http.delpath_from_searchpath(dellist, plist=None, **kargs)[source]

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
filesysobjects.plugins.http.gettop_from_pathstring(spath, plist=None, **kargs)[source]

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 only.

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

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

passed-through

filesysobjects.plugins.http.gettop_from_pathstring_iter(spath, plist=None, **kargs)[source]

Iterates all matches in plist,see gettop_from_pathstring.

filesysobjects.plugins.http.join_apppathx_entry(entry, **kw)[source]

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
filesysobjects.plugins.http.normapppathx(spath, **kargs)[source]

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()
filesysobjects.plugins.http.set_uppertree_searchpath(start=None, top=None, plist=None, **kargs)[source]

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

filesysobjects.plugins.http.splitapppathx(spath, **kargs)[source]

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‘

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

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

filesysobjects.plugins.http.splitapppathx_getlocalpath(elems, **kargs)[source]

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

filesysobjects.plugins.smb module

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

filesysobjects.plugins.smb.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.

filesysobjects.plugins.smb.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)
20: ('file://')                    +(auth)  +()    +()       +(path)
28: ('file://')                    +()      +()    +()       +(path)
36: ('smb://'|'cifs://')  +(host)  +1SEP  +(share)  +(path)
44: (2SEP)                +(host)  +1SEP  +(share)  +(path) # in general a share present - on POSIX too???
52: (scheme '://')           +(auth)  +1SEP  +(path)   +"?" +(query-fragment)
60: ()                    +()      +()    +(drive)  +(path)
68: ()                    +()      +()    +(drive)  +(path)
76: ()                    +()      +()    +(drive)  +()
84: ()                    +()      +()    +()       +(path)
92: ()                    +()       +()   +()       +()
94 os.pathsep
filesysobjects.plugins.smb.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.

filesysobjects.plugins.smb.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.

filesysobjects.plugins.smb.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.

filesysobjects.plugins.smb.ESC_CHAR_MAP = {'\x07': '\\a', '\t': '\\t', '\x08': '\\b', '\x0b': '\\v', '\n': '\\n', '\r': '\\r', '\x0c': '\\f'}

maps unambiguous escape characters to escape sequences

filesysobjects.plugins.smb.INVALIDCHARS = <_sre.SRE_Pattern object at 0x267f0f8>

super position of both: r’[:<>*?0]’

filesysobjects.plugins.smb.INVALIDCHARSPOSIX = <_sre.SRE_Pattern object at 0x23d0a48>

posix:

r'\0'
filesysobjects.plugins.smb.INVALIDCHARSWIN = <_sre.SRE_Pattern object at 0x267f030>

windows:

r'[:<>*?]'
filesysobjects.plugins.smb.OSSEP = '/'

os separator

filesysobjects.plugins.smb.OSSEPCLS = '[/]'

character class os separator

filesysobjects.plugins.smb.OSSEPCLSN = '[^/]'

character class without separator

filesysobjects.plugins.smb.UNESC_CHAR_MAP = {'a': '\x07', 'b': '\x08', 'f': '\x0c', 'n': '\n', 'r': '\r', 't': '\t', 'v': '\x0b'}

maps escape characters for escape sequences to unescape

filesysobjects.plugins.smb.addpath_to_searchpath(spath, plist=None, **kargs)[source]

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
filesysobjects.plugins.smb.delpath_from_searchpath(dellist, plist=None, **kargs)[source]

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
filesysobjects.plugins.smb.gettop_from_pathstring(spath, plist=None, **kargs)[source]

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 only.

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

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

passed-through

filesysobjects.plugins.smb.gettop_from_pathstring_iter(spath, plist=None, **kargs)[source]

Iterates all matches in plist,see gettop_from_pathstring.

filesysobjects.plugins.smb.join_apppathx_entry(entry, **kw)[source]

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
filesysobjects.plugins.smb.normapppathx(spath, **kargs)[source]

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()
filesysobjects.plugins.smb.set_uppertree_searchpath(start=None, top=None, plist=None, **kargs)[source]

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

filesysobjects.plugins.smb.splitapppathx(spath, **kargs)[source]

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‘

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

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

filesysobjects.plugins.smb.splitapppathx_getlocalpath(elems, **kargs)[source]

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

Module contents

The package ‘filesysobjects’ provides utilities for the handling of file system like resource paths as class trees containing files as objects.