Package psicons :: Package core :: Module utils
[hide private]
[frames] | no frames]

Module utils

source code

Miscellaneous utilities for use in writing and using commands.

Often we will want to name or create a file based on from pre-existing file paths:

Thus, here we provide a set of functions for extracting components from a file path and extrapolating new names from the same. For consistency, here is the terminology used:

dir
the path of the directory a file is in
base
the local name of a file, e.g. "foo.txt", "schedule.doc"
ext
the extension of a file, e.g. ".txt", ".doc". Note this includes the separating period, so that the extensions of files "foo.txt", "foo." and "foo" and ".txt", "." and "" respectively.
stem
the base file name, without the extension, e.g. "foo" and "schedule" for "foo.txt", "schedule.doc" respectively.
substem
the stem of a file name, less the final "word" e.g. "foo" and "schedule_abc" for "foo-bar.txt" and "schedule_abc_2011.doc" respectively.
Functions [hide private]
 
dir_base(p)
Return the directory and file name of a path.
source code
 
dirbase_from_path(p)
Return the directory and file name of a path.
source code
 
dir_stem_ext(p)
Return the directory, stem of the file name and extension from a path.
source code
 
dirstemext_from_path(p)
Return the directory, stem of the file name and extension from a path.
source code
 
substem_mod(s)
Split the 'stem' of a file name into a core name and a trailing modifier.
source code
 
interpolate(str, sub_hash)
Interpolate the bracketed sections of the passed string as keyed substrings.
source code
 
interpolate_from_path(p, tmpl, subs={})
Interpolate using qualities of a file path.
source code
Variables [hide private]
  INTERP_RE = re.compile(r'\{([^\}]+)\}')
  SUBSTEM_RE = re.compile(r'.([\.-]\S+)$')
  __package__ = 'psicons.core'
Function Details [hide private]

dir_base(p)

source code 

Return the directory and file name of a path.

For example:

>>> dir_base ('bar.foo')
('', 'bar.foo')
>>> dir_base ('/bar.foo')
('/', 'bar.foo')
>>> dir_base ('baz/bar.foo')
('baz/', 'bar.foo')
>>> dir_base ('/quux/baz/bar.foo')
('/quux/baz/', 'bar.foo')

We use here the Python convention of referring to the file name (as opposed to path) as the "base". Also, there's an apparent oddity in the native splitting of paths, to do with the parent directory:

>>> path.split ('bar.foo')
('', 'bar.foo')
>>> path.split ('/bar.foo')
('/', 'bar.foo')
>>> path.split ('baz/bar.foo')
('baz', 'bar.foo')

That is, the dividing filesep only appears if there is nothing else in the directory component. This makes things difficult if you are trying to pick apart a file path and reassemble it - do I need a file separator? was there one there before? Fortunately path.join is reasonably clever about fusing paths, but this is still an inconsistency and so is fixed here.

Parameters:
  • p - a file name or path
Returns:
the directory and base name of the file path

dirbase_from_path(p)

source code 

Return the directory and file name of a path.

For example:

>>> dir_base ('bar.foo')
('', 'bar.foo')
>>> dir_base ('/bar.foo')
('/', 'bar.foo')
>>> dir_base ('baz/bar.foo')
('baz/', 'bar.foo')
>>> dir_base ('/quux/baz/bar.foo')
('/quux/baz/', 'bar.foo')

We use here the Python convention of referring to the file name (as opposed to path) as the "base". Also, there's an apparent oddity in the native splitting of paths, to do with the parent directory:

>>> path.split ('bar.foo')
('', 'bar.foo')
>>> path.split ('/bar.foo')
('/', 'bar.foo')
>>> path.split ('baz/bar.foo')
('baz', 'bar.foo')

That is, the dividing filesep only appears if there is nothing else in the directory component. This makes things difficult if you are trying to pick apart a file path and reassemble it - do I need a file separator? was there one there before? Fortunately path.join is reasonably clever about fusing paths, but this is still an inconsistency and so is fixed here.

Parameters:
  • p - a file name or path
Returns:
the directory and base name of the file path

dir_stem_ext(p)

source code 

Return the directory, stem of the file name and extension from a path.

For example:

>>> dir_stem_ext ('bar.foo')
('', 'bar', '.foo')
>>> dir_stem_ext ('bar.')
('', 'bar', '.')
>>> dir_stem_ext ('bar')
('', 'bar', '')
>>> dir_stem_ext ('baz/bar.foo')
('baz/', 'bar', '.foo')
>>> dir_stem_ext ('/quux/baz/bar.foo')
('/quux/baz/', 'bar', '.foo')

Note this uses the file separator convention of dir_base.

Parameters:
  • p - a file name or path
Returns:
the directory and base name stem and extension of the file path

dirstemext_from_path(p)

source code 

Return the directory, stem of the file name and extension from a path.

For example:

>>> dir_stem_ext ('bar.foo')
('', 'bar', '.foo')
>>> dir_stem_ext ('bar.')
('', 'bar', '.')
>>> dir_stem_ext ('bar')
('', 'bar', '')
>>> dir_stem_ext ('baz/bar.foo')
('baz/', 'bar', '.foo')
>>> dir_stem_ext ('/quux/baz/bar.foo')
('/quux/baz/', 'bar', '.foo')

Note this uses the file separator convention of dir_base.

Parameters:
  • p - a file name or path
Returns:
the directory and base name stem and extension of the file path

substem_mod(s)

source code 

Split the 'stem' of a file name into a core name and a trailing modifier.

Many file names are structured as "foo-mod.ext" or "foo.mod.ext" where "mod" is some qualifier, e.g. "report-2.doc", "programme.20101201.txt". This sniffs out the usual forms of these endings and if found, splits and returns the name there.

For example:

>>> substem_mod ('report-2')
('report', '-2')
>>> substem_mod ('programme.20101201')
('programme', '.20101201')
>>> substem_mod ('report 2')
('report 2', '')
>>> substem_mod ('programme_20101201')
('programme_20101201', '')
Parameters:
  • s - a file (base) name
Returns:
the substem and modifier (trailing word) of the file name

interpolate(str, sub_hash)

source code 

Interpolate the bracketed sections of the passed string as keyed substrings.

The intent for this is as a very simple templating or substitution system to be used in configurations and the like.

For example:

>>> d = {'foo': '123', 'bar': '456'}
>>> interpolate ('abcdef', d)
'abcdef'
>>> interpolate ('abc{foo}def', d)
'abc123def'
>>> interpolate ('ab{foo}cd{bar}ef', d)
'ab123cd456ef'
Parameters:
  • str - a string containing parens delimited locations for substitution
  • sub_hash (dict) - words and substitutions to be used on the string
Returns:
the string with substitutions made

interpolate_from_path(p, tmpl, subs={})

source code 

Interpolate using qualities of a file path.

This allows a new file name or path (or actually any string) to be generated by interpolation from a file path. This allows construction of paths to files in the same directory, files with the same name but different extension, files with the same name except for a suffix, etc.

The substitution keywords are:

ext
input path file extension, e.g. ".txt"
base
input path file base (name), e.g. "foo-bar.txt"
stem
input path file name stem, e.g. "foo-bar"
dir
input path directory, e.g. "quux/"
dirstem
input path directory and stem, e.g. "quux/foo-bar"
substem
input path substem, e.g. "foo"
mod
input path modifier, e.g. "-bar"
date
current date
time
current time

For example:

>>> pth = '/foo/bar.baz'
>>> interpolate_from_path (pth, '{stem}.new{ext}')
'bar.new.baz'
>>> d = {'prefix': 'PRFX', 'ext': '.txt'}
>>> interpolate_from_path (pth, '{prefix}{stem}.new{ext}', d)
'PRFXbar.new.txt'
Parameters:
  • p (str) - a file name or path
  • tmpl (str) - the template for the output, containing parens delimited locations for substitution
  • subs (dict) - additional words and substitutions to be used on the string
Returns:
the template string with substitutions made