fspath.fspath module

semantic path names and much more

class fspath.fspath.FSPath(pathname)

Bases: str

A path name to a file or folder.

Handling path names more comfortable, e.g.:

• concatenate path names with the division operator /

• call functions like mkdir on path names

• get properties like EXISTS

>>> from fspath import FSPath
>>> tmp = FSPath('~/tmp')
>>> tmp
'/home/user/tmp'
>>> tmp.EXISTS
False

no additional import, no juggling with os.join(...)

simply slash / and foo.<method> calls

>>> [(tmp/x).makedirs() for x in ('foo', 'bar')]
True, True
>>> for n in tmp.listdir():
...     print(tmp / n)
...
/home/user/tmp/foo
/home/user/tmp/bar

downloads & archives

>>> arch = foo / 'fspath.zip'
>>> url = 'https://github.com/return42/fspath/archive/master.zip'

download – super easy download + segmentation + nice ticker

>>> arch.download(url, chunksize=1024, ticker=True)
/home/user/tmp/foo/fspath.zip: [87.9 KB][===============    ]  83%

FSPath.extract – extract in one step, no matter ZIP or TAR

>>> arch.ISTAR, arch.ISZIP
(False, True)
>>> arch.extract(foo)
['fspath-master/', 'fspath-master/.gitignore'
, 'fspath-master/MAINFEST.in', 'fspath-master/Makefile'
, 'fspath-master/README.rst',  ... ]

For more examples see our slide-show.

property ABSPATH

The absolute pathname

E.g: ../to/../to/folder/filename.ext –> /path/to/folder/filename.ext

property ATIME

Return the last access time, reported by os.stat().

property BASENAME

The path name with suffix, but without the folder name.

E.g.: /path/to/folder/filename.ext –> filename.ext

property CTIME

Return the metadata change time, reported by os.stat().

property DIRNAME

The path name of the folder, where the file is located

E.g.: /path/to/folder/filename.ext –> /path/to/folder

property EXECUTABLE

True if file is executable

property EXISTS

True if file/pathname exist

property EXPANDUSER

Path with an initial component of ~ or ~user replaced by that user’s home.

property EXPANDVARS

Path with environment variables expanded.

property FILENAME

The path name without folder and suffix.

E.g.: /path/to/folder/filename.ext –> filename

property ISABSPATH

True if path is absolute

property ISDIR

True if path is a folder

property ISFILE

True if path is a file

property ISLINK

True if path is a symbolic link

property ISMOUNT

True if path is a mountpoint

property ISTAR

True if path is a TAR archive file

property ISZIP

True if path is a ZIP file

property MTIME

Return the last modification time, reported by os.stat().

property NTPATH

The path name in the Windows (NT) notation.

OS = {'altsep': None, 'curdir': '.', 'defpath': '/bin:/usr/bin', 'devnull': '/dev/null', 'extsep': '.', 'linesep': '\n', 'pathsep': ':', 'sep': '/'}

property POSIXPATH

The path name in POSIX notation.

Helpfull if you are on MS-Windows and need the POSIX name.

Popen(*args, **kwargs)

Get a subprocess.Popen object (proc).

The path name of the self-object is the programm to call. The program arguments are given py *args and the *kwargs are passed to the subprocess.Popen constructor. The universal_newlines=True is true by default.

see https://docs.python.org/3/library/subprocess.html#popen-constructor

from fspath import FSPath
proc = FSPath("arp").Popen("-a",)
stdout, stderr = proc.communicate()
retVal = proc.returncode
print("stdout: %s" % stdout)
print("stderr: %s" % stderr)
print("exit code = %d" % retVal)

property READABLE

True if file/path is readable

property REALPATH

The real pathname without symbolic links.

property SIZE

Size in bytes

property SKIPSUFFIX

The complete file name without suffix.

E.g.: /path/to/folder/filename.ext –> /path/to/folder/filename

property SUFFIX

The filename suffix

E.g.: /path/to/folder/filename.ext –> .ext

property VALUE

string of the path name

property WRITEABLE

True if file/path is writeable

chdir()

change the current working directory to self.

copyfile(dest, preserve=False)

Copy the file src to the file or directory dest.

Dest str:

The destination may be a directory

Preserve bool:

copies permission bits

copytree(dest, symlinks=False, ignore=None)

Recursively copy the entire directory tree

delete()

remove file/folder

download(url, chunksize=1048576, ticker=False, pipe=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Download URL into file

The default chunksize is 1048576 Bytes, with ticker=True an progress-bar is prompted.

E.g. to download FSPath’s README.rst with a progressbar on stdout:

url = "https://raw.githubusercontent.com/return42/fspath/master/README.rst"

readme = FSPath("README.rst")
readme.download(url, ticker=True)

extract(folder='.', pwd=None, ticker=False, pipe=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Extract TAR or ZIP archive to ‘folder’

Uses extractall from tarfile.TarFile and zipfile.Zipfile to extract into folder.

Folder str:

folder to extract into

Pwd str:

password for crypted (only ZIP)

Returns:

members in an iterable form (list or just iterator)

filesize(precision=None)

Filesize in bytes or with precision

classmethod getCWD()

Current working directory.

classmethod getHOME()

User’s home folder.

glob(pattern, relpath=False)

Return an iterator which yields the paths matching a pathname pattern.

The pattern may contain simple shell-style wildcards a la fnmatch. However, unlike fnmatch, filenames starting with a dot are special cases that are not matched by ‘*’ and ‘?’ patterns.

listdir()

Return a iterator which yields the names of the files in the directory.

makedirs(mode=509)

Recursive directory creation, default mode is 0o775 (octal).

Parameters:

mode (int) – file permissons

Returns:

created (True) already exists (True),

Raises:

Exception – in case of errors (permissons, etc.)

move(dest)

Move path to another location (dest)

openBinaryFile(mode='rb', errors='strict', buffering=None)

Open file as binary file.

wraps io.open:

• except argument closefd (meaningless when using filenames)

• except argument encoding (meaningless since binary)

• except argument newline (meaningless since binary)

• mode='rb' is default

openTextFile(mode='rt', encoding='utf-8', errors='strict', buffering=1, newline=None)

Open file as text file.

wraps io.open:

• except argument closefd (meaningless when using filenames)

• encoding='utf-8' is default

• mode='rt' is default

• buffering=1 is default (selects line buffering)

reMatchFind(name, use_files=True, use_dirs=True, followlinks=False, relpath=False)

Returns iterator which yields matching path names

Parameters:

• use_files – iterator includes names of files

• use_dirs – iterator includes names of folders

• followlinks – follow symbolic links

To find all C and header files use:

folder.reMatchFind("*\.[ch]")

To find the first C or header file use:

next(myFolder.reMatchFind("*\.[ch]"), None)

readFile(encoding='utf-8', errors='strict')

read entire file

relpath(start)

Return a relative version of a path

rmfile()

remove file

rmtree(ignore_errors=False, onerror=None)

remove tree

splitpath()

Split a pathname.

Return tuple (head, tail) where tail is everything after the final slash. Either part may be empty.

startFile()

Start a file with its associated application.

suffix(new_suffix)

Return path name with new_suffix

walk(topdown=True, onerror=None, followlinks=False)

Directory tree generator.

For each directory in the directory tree rooted at top (including top itself, but excluding ‘.’ and ‘..’), yields a 3-tuple:

folder, dirnames, filenames

dirnames is a list of the names of the subdirectories in dirpath (excluding ‘.’ and ‘..’). filenames is a list of the names of the non-directory files in dirpath.

Note that the names in the lists are just names, with no path components. To get a full path (which begins with top) to a file or directory in dirpath, do folder / name.

By default, os.walk does not follow symbolic links to subdirectories on systems that support them. In order to get this functionality, set the optional argument ‘followlinks’ to true.

Caution

If you pass a relative pathname for top, don’t change the current working directory between resumptions of walk. walk never changes the current directory, and assumes that the client doesn’t either.

For more details see os.walk

fspath.fspath.callEXE(cmd, *args, **kwargs)

Synchronous command call cmd with arguments *args .

The *kwargs are passed to the subprocess.Popen constructor. The return value is a three-digit tuple (stdout, stderr, rc).

from fspath import callEXE
out, err, rc = callEXE("arp", "-a")

print("stdout: %s" % out)
print("stderr: %s" % err)
print("exit code = %d" % rc)