Convenient file input and output (pwkit.io)

The pwkit package provides many tools to ease reading and writing data files. The most generic such tools are located in this module. The most important tool is the Path class for object-oriented navigation of the filesystem.

The functionality in this module can be grouped into these categories:

• The Path object

• Functions helping with Unicode safety

• Other functions in pwkit.io (generally being superseded by Path)

The Path object

class pwkit.io.Path(*args, **kwargs)

This is an extended version of the pathlib.Path class. (pathlib is built into Python 3.x and is available as a backport to Python 2.x.) It represents a path on the filesystem.

The methods and attributes on Path objects fall into several broad categories:

• Manipulating and dissecting paths

• Filesystem interrogation

• Filesystem modifications

• Data input and output

Constructors are:

Path(part, *more)

Returns a new path equivalent to os.path.join (part, *more), except the arguments may be either strings or other Path instances.

classmethod cwd()

Returns a new path containing the absolute path of the current working directory.

classmethod create_tempfile(want='handle', resolution='try_unlink', suffix='', **kwargs)

Returns a context manager managing the creation and destruction of a named temporary file. The operation of this function is exactly like that of the bound method Path.make_tempfile(), except that instead of creating a temporary file with a name similar to an existing path, this function creates one with a name selected using the standard OS-dependent methods for choosing names of temporary files.

The overwrite resolution is not allowed here since there is no original path to overwrite.

Note that by default the returned context manager returns a file-like object and not an actual Path instance; use want="path" to get a Path.

Manipulating and dissecting paths

Child paths can be created by using the division operator, that is:

parent = Path ('directory')
child = parent / 'subdirectory'

Combining a relative path with an absolute path in this way will just yield the absolute path:

>>> foo = Path ('relative') / Path ('/a/absolute')
>>> print (foo)
<<< /a/absolute

Paths should be converted to text by calling str() or unicode() on them.

Instances of Path have the following attributes that help you create new paths or break them into their components:

anchor	The concatenation of the drive and root, or ''.
drive	The drive prefix (letter or UNC path), if any.
name	The final path component, if any.
parent	The logical parent of the path.
parents	A sequence of this path's logical parents.
parts	An object providing sequence-like access to the components in the filesystem path.
stem	The final path component, minus its last suffix.
suffix	The final component's last suffix, if any.
suffixes	A list of the final component's suffixes, if any.

And they have the following related methods:

absolute()	Return an absolute version of this path.
as_uri()	Return the path as a 'file' URI.
expand([user, vars, glob, resolve])	Return a new Path with various expansions performed.
format(*args, **kwargs)	Return a new path formed by calling str.format() on the textualization of this path.
get_parent([mode])	Get the path of this path’s parent directory.
is_absolute()	True if the path is absolute (has both a root and, if applicable, a drive).
joinpath(*args)	Combine this path with one or several arguments, and return a new path representing either a subpath (if all arguments are relative paths) or a totally different path (if one of the arguments is anchored).
make_relative(other)	Return a new path that is the equivalent of this one relative to the path other.
relative_to(*other)	Return the relative path to another path identified by the passed arguments.
resolve([strict])	Make the path absolute, resolving all symlinks on the way and also normalizing it (for example turning slashes into backslashes under Windows).
with_name(name)	Return a new path with the file name changed.
with_suffix(suffix)	Return a new path with the file suffix changed.

Detailed descriptions of attributes

Path.anchor

The concatenation of drive and root.

Path.drive

The Windows or network drive of the path. The empty string on POSIX.

Path.name

The final path component. The name of /foo/ is "foo". The name of /foo/. is "foo" as well. The name of /foo/.. is "..".

Path.parent

This path’s parent, in a textual sense: the parent of foo is ., but the parent of . is also .. The parent of /bar is /; the parent of / is also /.

See also

Path.get_parent()

Path.parents

An immutable, indexable sequence of this path’s parents. Here are some examples showing the semantics:

>>> list(Path("/foo/bar").parents)
<<< [Path("/foo"), Path("/")]
>>> list(Path("/foo/bar/").parents)
<<< [Path("/foo"), Path("/")]
>>> list(Path("/foo/bar/.").parents)
<<< [Path("/foo"), Path("/")]
>>> list(Path("/foo/./bar/.").parents)
<<< [Path("/foo"), Path("/")]
>>> list(Path("wib/wob").parents)
<<< [Path("wib"), Path(".")]
>>> list(Path("wib/../wob/.").parents)
<<< [Path("wib/.."), Path("wib"), Path(".")]

See also

Path.get_parent()

Path.parts

A tuple of the path components. Examples:

>>> Path('/a/b').parts
<<< ('/', 'a', 'b')
>>> Path('a/b').parts
<<< ('a', 'b')
>>> Path('/a/b/').parts
<<< ('/', 'a', 'b')
>>> Path('a/b/.').parts
<<< ('a', 'b')
>>> Path('/a/../b/./c').parts
<<< ('/', 'a', '..', 'b', 'c')
>>> Path('.').parts
<<< ()
>>> Path('').parts
<<< ()

Path.stem

The name without its suffix. The stem of "foo.tar.gz" is "foo.tar". The stem of "noext" is "noext". It is an invariant that name = stem + suffix.

Path.suffix

The suffix of the name, including the period. If there is no period, the empty string is returned:

>>> print (Path("foo.tar.gz").suffix)
<<< .gz
>>> print (Path("foo.dir/.").suffix)
<<< .dir
>>> print (repr (Path("noextension").suffix))
<<< ''

Path.suffixes

A list of all suffixes on name, including the periods. The suffixes of "foo.tar.gz" are [".tar", ".gz"]. If name contains no periods, the empty list is returned.

Detailed descriptions of methods

Path.absolute()

Return an absolute version of the path. Unlike resolve(), does not normalize the path or resolve symlinks.

Path.as_uri()

Return the path stringified as a file:/// URI.

Path.expand(user=False, vars=False, glob=False, resolve=False)

Return a new Path with various expansions performed. All expansions are disabled by default but can be enabled by passing in true values in the keyword arguments.

userbool (default False)

Expand ~ and ~user home-directory constructs. If a username is unmatched or $HOME is unset, no change is made. Calls os.path.expanduser().

varsbool (default False)

Expand $var and ${var} environment variable constructs. Unknown variables are not substituted. Calls os.path.expandvars().

globbool (default False)

Evaluate the path as a glob expression and use the matched path. If the glob does not match anything, do not change anything. If the glob matches more than one path, raise an IOError.

resolvebool (default False)

Call resolve() on the return value before returning it.

Path.format(*args, **kwargs)

Return a new path formed by calling str.format() on the textualization of this path.

Path.get_parent(mode='naive')

Get the path of this path’s parent directory.

Unlike the parent attribute, this function can correctly ascend into parent directories if self is "." or a sequence of "..". The precise way in which it handles these kinds of paths, however, depends on the mode parameter:

"textual"

Return the same thing as the parent attribute.

"resolved"

As textual, but on the resolve()-d version of the path. This will always return the physical parent directory in the filesystem. The path pointed to by self must exist for this call to succeed.

"naive"

As textual, but the parent of "." is "..", and the parent of a sequence of ".." is the same sequence with another "..". Note that this manipulation is still strictly textual, so results when called on paths like "foo/../bar/../other" will likely not be what you want. Furthermore, p.get_parent(mode="naive") never yields a path equal to p, so some kinds of loops will execute infinitely.

Path.is_absolute()

Returns whether the path is absolute.

Path.joinpath(*args)

Combine this path with several new components. If one of the arguments is absolute, all previous components are discarded.

Path.make_relative(other)

Return a new path that is the equivalent of this one relative to the path other. Unlike relative_to(), this will not throw an error if self is not a sub-path of other; instead, it will use .. to build a relative path. This can result in invalid relative paths if other contains a directory symbolic link.

If self is an absolute path, it is returned unmodified.

Path.relative_to(*other)

Return this path as made relative to another path identified by other. If this is not possible, raise ValueError.

Path.resolve()

Make this path absolute, resolving all symlinks and normalizing away ".." and "." components. The path must exist for this function to work.

Path.with_name(name)

Return a new path with the file name changed.

Path.with_suffix(suffix)

Return a new path with the file suffix changed, or a new suffix added if there was none before. suffix must start with a ".". The semantics of the suffix attribute are maintained, so:

>>> print (Path ('foo.tar.gz').with_suffix ('.new'))
<<< foo.tar.new

Filesystem interrogation

These methods probe the actual filesystem to test whether the given path, for example, is a directory; but they do not modify the filesystem.

exists()	Whether this path exists.
glob(pattern)	Iterate over this subtree and yield all existing files (of any kind, including directories) matching the given relative pattern.
is_block_device()	Whether this path is a block device.
is_char_device()	Whether this path is a character device.
is_dir()	Whether this path is a directory.
is_fifo()	Whether this path is a FIFO.
is_file()	Whether this path is a regular file (also True for symlinks pointing to regular files).
is_socket()	Whether this path is a socket.
is_symlink()	Whether this path is a symbolic link.
iterdir()	Iterate over the files in this directory.
match(path_pattern)	Return True if this path matches the given pattern.
readlink()	Assuming that this path is a symbolic link, read its contents and return them as another Path object.
rglob(pattern)	Recursively yield all existing files (of any kind, including directories) matching the given relative pattern, anywhere in this subtree.
scandir()	Iteratively scan this path, assuming it’s a directory.
stat(*[, follow_symlinks])	Return the result of the stat() system call on this path, like os.stat() does.

Detailed descriptions

Path.exists()

Returns whether the path exists.

Path.glob(pattern)

Assuming that the path is a directory, iterate over its contents and return sub-paths matching the given shell-style glob pattern.

Path.is_block_device()

Returns whether the path resolves to a block device file.

Path.is_char_device()

Returns whether the path resolves to a character device file.

Path.is_dir()

Returns whether the path resolves to a directory.

Path.is_fifo()

Returns whether the path resolves to a Unix FIFO.

Path.is_file()

Returns whether the path resolves to a regular file.

Path.is_socket()

Returns whether the path resolves to a Unix socket.

Path.is_symlink()

Returns whether the path resolves to a symbolic link.

Path.iterdir()

Iterate over the files in this directory. Does not yield any result for the special paths ‘.’ and ‘..’.

Assuming the path is a directory, generate a sequence of sub-paths corresponding to its contents.

Path.match(pattern)

Test whether this path matches the given shell glob pattern.

Path.readlink()

Assuming that this path is a symbolic link, read its contents and return them as another Path object. An “invalid argument” OSError will be raised if this path does not point to a symbolic link.

Path.rglob(pattern)

Recursively yield all files and directories matching the shell glob pattern pattern below this path.

Path.scandir()

Iteratively scan this path, assuming it’s a directory. This requires and uses the scandir module.

scandir is different than iterdir because it generates DirEntry items rather than Path instances. DirEntry objects have their properties filled from the directory info itself, so querying them avoids syscalls that would be necessary with iterdir().

The generated values are scandir.DirEntry objects which have some information pre-filled. These objects have methods inode(), is_dir(), is_file(), is_symlink(), and stat(). They have attributes name (the basename of the entry) and path (its full path).

Path.stat()

Run os.stat() on the path and return the result.

Filesystem modifications

These functions actually modify the filesystem.

chmod(mode, *[, follow_symlinks])	Change the permissions of the path, like os.chmod().
copy_to(dest[, preserve])	Copy this path — as a file — to another dest.
ensure_dir([mode, parents])	Ensure that this path exists as a directory.
ensure_parent([mode, parents])	Ensure that this path's parent directory exists.
make_tempfile([want, resolution, suffix])	Get a context manager that creates and cleans up a uniquely-named temporary file with a name similar to this path.
mkdir([mode, parents, exist_ok])	Create a new directory at this given path.
rellink_to(target[, force])	Make this path a symlink pointing to the given target, generating the proper relative path using make_relative().
rename(target)	Rename this path to the target path.
rmdir()	Remove this directory.
rmtree([errors])	Recursively delete this directory and its contents.
symlink_to(target[, target_is_directory])	Make this path a symlink pointing to the target path.
touch([mode, exist_ok])	Create this file with the given access mode, if it doesn't exist.
unlink([missing_ok])	Remove this file or link.
try_unlink()	Try to unlink this path.

Detailed descriptions

Path.chmod(mode)

Change the mode of the named path. Remember to use octal 0o755 notation!

Path.copy_to(dest, preserve='mode')

Copy this path — as a file — to another dest.

The preserve argument specifies which meta-properties of the file should be preserved:

none

Only copy the file data.

mode

Copy the data and the file mode (permissions, etc).

all

Preserve as much as possible: mode, modification times, etc.

The destination dest may be a directory.

Returns the final destination path.

Path.ensure_dir(mode=511, parents=False)

Ensure that this path exists as a directory.

This function calls mkdir() on this path, but does not raise an exception if it already exists. It does raise an exception if this path exists but is not a directory. If the directory is created, mode is used to set the permissions of the resulting directory, with the important caveat that the current os.umask() is applied.

It returns a boolean indicating if the directory was actually created.

If parents is true, parent directories will be created in the same manner.

Path.ensure_parent(mode=511, parents=False)

Ensure that this path’s parent directory exists.

Returns a boolean whether the parent directory was created. Will attempt to create superior parent directories if parents is true.

Path.make_tempfile(want='handle', resolution='try_unlink', suffix='', **kwargs)

Get a context manager that creates and cleans up a uniquely-named temporary file with a name similar to this path.

This function returns a context manager that creates a secure temporary file with a path similar to self. In particular, if str(self) is something like foo/bar, the path of the temporary file will be something like foo/bar.ame8_2.

The object returned by the context manager depends on the want argument:

"handle"

An open file-like object is returned. This is the object returned by tempfile.NamedTemporaryFile. Its name on the filesystem is accessible as a string as its name attribute, or (a customization here) as a Path instance as its path attribute.

"path"

The temporary file is created as in "handle", but is then immediately closed. A Path instance pointing to the path of the temporary file is instead returned.

If an exception occurs inside the context manager block, the temporary file is left lying around. Otherwise, what happens to it upon exit from the context manager depends on the resolution argument:

"try_unlink"

Call try_unlink() on the temporary file — no exception is raised if the file did not exist.

"unlink"

Call unlink() on the temporary file — an exception is raised if the file did not exist.

"keep"

The temporary file is left lying around.

"overwrite"

The temporary file is rename()-d to overwrite self.

For instance, when rewriting important files, it’s typical to write the new data to a temporary file, and only rename the temporary file to the final destination at the end — that way, if a problem happens while writing the new data, the original file is left unmodified; otherwise you’d be stuck with a partially-written version of the file. This pattern can be accomplished with:

p = Path ('path/to/important/file')
with p.make_tempfile (resolution='overwrite', mode='wt') as h:
    print ('important stuff goes here', file=h)

The suffix argument is appended to the temporary file name after the random portion. It defaults to the empty string. If you want it to operate as a typical filename suffix, include a leading ".".

Other kwargs are passed to tempfile.NamedTemporaryFile.

Path.mkdir(mode=0o777, parents=False)

Create a directory at this path location. Creates parent directories if parents is true. Raises OSError if the path already exists, even if parents is true.

Path.rellink_to(target, force=False)

Make this path a symlink pointing to the given target, generating the proper relative path using make_relative(). This gives different behavior than symlink_to(). For instance, Path ('a/b').symlink_to ('c') results in a/b pointing to the path c, whereas rellink_to() results in it pointing to ../c. This can result in broken relative paths if (continuing the example) a is a symbolic link to a directory.

If either target or self is absolute, the symlink will point at the absolute path to target. The intention is that if you’re trying to link /foo/bar to bee/boo, it probably makes more sense for the link to point to /path/to/.../bee/boo rather than ../../../../bee/boo.

If force is true, try_unlink() will be called on self before the link is made, forcing its re-creation.

Path.rename(target)

Rename this path to target.

Path.rmdir()

Delete this path, if it is an empty directory.

Path.rmtree(errors='warn')

Recursively delete this directory and its contents. The errors keyword specifies how errors are handled:

“warn” (the default)

Print a warning to standard error.

“ignore”

Ignore errors.

Path.symlink_to(target, target_is_directory=False)

Make this path a symlink pointing to the given target.

Path.touch(mode=0o666, exist_ok=True)

Create a file at this path with the given mode, if needed.

Path.unlink()

Unlink this file or symbolic link.

Path.try_unlink()

Try to unlink this path. If it doesn’t exist, no error is returned. Returns a boolean indicating whether the path was really unlinked.

Data input and output

open([mode, buffering, encoding, errors, ...])	Open the file pointed by this path and return a file object, as the built-in open() function does.
try_open([null_if_noexist])	Call Path.open() on this path (passing kwargs) and return the result.
as_hdf_store([mode])	Return the path as an opened pandas.HDFStore object.
read_astropy_ascii(**kwargs)	Open as an ASCII table, returning a astropy.table.Table object.
read_fits(**kwargs)	Open as a FITS file, returning a astropy.io.fits.HDUList object.
read_fits_bintable([hdu, drop_nonscalar_ok])	Open as a FITS file, read in a binary table, and return it as a pandas.DataFrame, converted with pkwit.numutil.fits_recarray_to_data_frame().
read_hdf(key, **kwargs)	Open as an HDF5 file using pandas and return the item stored under the key key.
read_inifile([noexistok, typed])	Open assuming an “ini-file” format and return a generator yielding data records using either pwkit.inifile.read_stream() (if typed is false) or pwkit.tinifile.read_stream() (if it’s true).
read_json([mode])	Use the json module to read in this file as a JSON-formatted data structure.
read_lines([mode, noexistok])	Generate a sequence of lines from the file pointed to by this path, by opening as a regular file and iterating over it.
read_numpy(**kwargs)	Read this path into a numpy.ndarray using numpy.load().
read_numpy_text([dfcols])	Read this path into a numpy.ndarray as a text file using numpy.loadtxt().
read_pandas([format])	Read using pandas.
read_pickle()	Open the file, unpickle one object from it using pickle, and return it.
read_pickles()	Generate a sequence of objects by opening the path and unpickling items until EOF is reached.
read_tabfile(**kwargs)	Read this path as a table of typed measurements via pwkit.tabfile.read().
read_text([encoding, errors, newline])	Read this path as one large chunk of text.
read_toml([encoding, errors, newline])	Read this path as a TOML document.
read_yaml([encoding, errors, newline])	Read this path as a YAML document.
write_pickle(obj)	Dump obj to this path using cPickle.
write_pickles(objs)	objs must be iterable.
write_yaml(data[, encoding, errors, newline])	Read data to this path as a YAML document.

Detailed descriptions

Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)

Open the file pointed at by the path and return a file object. This delegates to the modern io.open() function, not the global builtin open().

Path.try_open(null_if_noexist=False, **kwargs)

Call Path.open() on this path (passing kwargs) and return the result. If the file doesn’t exist, the behavior depends on null_if_noexist. If it is false (the default), None is returned. Otherwise, os.devnull is opened and returned.

Path.as_hdf_store(mode='r', **kwargs)

Return the path as an opened pandas.HDFStore object. Note that the HDFStore constructor unconditionally prints messages to standard output when opening and closing files, so use of this function will pollute your program’s standard output. The kwargs are forwarded to the HDFStore constructor.

Path.read_astropy_ascii(**kwargs)

Open as an ASCII table, returning a astropy.table.Table object. Keyword arguments are passed to astropy.io.ascii.open(); valid ones likely include:

• names = <list> (column names)

• format (‘basic’, ‘cds’, ‘csv’, ‘ipac’, …)

• guess = True (guess table format)

• delimiter (column delimiter)

• comment = <regex>

• header_start = <int> (line number of header, ignoring blank and comment lines)

• data_start = <int>

• data_end = <int>

• converters = <dict>

• include_names = <list> (names of columns to include)

• exclude_names = <list> (names of columns to exclude; applied after include)

• fill_values = <dict> (filler values)

Path.read_fits(**kwargs)

Open as a FITS file, returning a astropy.io.fits.HDUList object. Keyword arguments are passed to astropy.io.fits.open(); valid ones likely include:

• mode = 'readonly' (or “update”, “append”, “denywrite”, “ostream”)

• memmap = None

• save_backup = False

• cache = True

• uint = False

• ignore_missing_end = False

• checksum = False

• disable_image_compression = False

• do_not_scale_image_data = False

• ignore_blank = False

• scale_back = False

Path.read_fits_bintable(hdu=1, drop_nonscalar_ok=True, **kwargs)

Open as a FITS file, read in a binary table, and return it as a pandas.DataFrame, converted with pkwit.numutil.fits_recarray_to_data_frame(). The hdu argument specifies which HDU to read, with its default 1 indicating the first FITS extension. The drop_nonscalar_ok argument specifies if non-scalar table values (which are inexpressible in pandas.DataFrame`s) should be silently ignored (``True`) or cause a ValueError to be raised (False). Other kwargs are passed to astropy.io.fits.open(), (see Path.read_fits()) although the open mode is hardcoded to be "readonly".

Path.read_hdf(key, **kwargs)

Open as an HDF5 file using pandas and return the item stored under the key key. kwargs are passed to pandas.read_hdf().

Path.read_inifile(noexistok=False, typed=False)

Open assuming an “ini-file” format and return a generator yielding data records using either pwkit.inifile.read_stream() (if typed is false) or pwkit.tinifile.read_stream() (if it’s true). The latter version is designed to work with numerical data using the pwkit.msmt subsystem. If noexistok is true, a nonexistent file will result in no items being generated rather than an IOError being raised.

Path.read_json(mode='rt', **kwargs)

Use the json module to read in this file as a JSON-formatted data structure. Keyword arguments are passed to json.load(). Returns the read-in data structure.

Path.read_lines(mode='rt', noexistok=False, **kwargs)

Generate a sequence of lines from the file pointed to by this path, by opening as a regular file and iterating over it. The lines therefore contain their newline characters. If noexistok, a nonexistent file will result in an empty sequence rather than an exception. kwargs are passed to Path.open().

Path.read_numpy(**kwargs)

Read this path into a numpy.ndarray using numpy.load(). kwargs are passed to numpy.load(); they likely are:

mmap_modeNone, ‘r+’, ‘r’, ‘w+’, ‘c’

Load the array using memory-mapping

allow_picklebool = True

Whether Pickle-format data are allowed; potential security hazard.

fix_importsbool = True

Try to fix Python 2->3 import renames when loading Pickle-format data.

encoding‘ASCII’, ‘latin1’, ‘bytes’

The encoding to use when reading Python 2 strings in Pickle-format data.

Path.read_numpy_text(dfcols=None, **kwargs)

Read this path into a numpy.ndarray as a text file using numpy.loadtxt(). In normal conditions the returned array is two-dimensional, with the first axis spanning the rows in the file and the second axis columns (but see the unpack and dfcols keywords).

If dfcols is not None, the return value is a pandas.DataFrame constructed from the array. dfcols should be an iterable of column names, one for each of the columns returned by the numpy.loadtxt() call. For convenience, if dfcols is a single string, it will by turned into an iterable by a call to str.split().

The remaining kwargs are passed to numpy.loadtxt(); they likely are:

dtypedata type

The data type of the resulting array.

commentsstr

If specific, a character indicating the start of a comment.

delimiterstr

The string that separates values. If unspecified, any span of whitespace works.

convertersdict

A dictionary mapping zero-based column number to a function that will turn the cell text into a number.

skiprowsint (default=0)

Skip this many lines at the top of the file

usecolssequence

Which columns keep, by number, starting at zero.

unpackbool (default=False)

If true, the return value is transposed to be of shape (cols, rows).

ndminint (default=0)

The returned array will have at least this many dimensions; otherwise mono-dimensional axes will be squeezed.

Path.read_pandas(format='table', **kwargs)

Read using pandas. The function pandas.read_FORMAT is called where FORMAT is set from the argument format. kwargs are passed to this function. Supported formats likely include clipboard, csv, excel, fwf, gbq, html, json, msgpack, pickle, sql, sql_query, sql_table, stata, table. Note that hdf is not supported because it requires a non-keyword argument; see Path.read_hdf().

Path.read_pickle()

Open the file, unpickle one object from it using pickle, and return it.

Path.read_pickles()

Generate a sequence of objects by opening the path and unpickling items until EOF is reached.

Path.read_tabfile(**kwargs)

Read this path as a table of typed measurements via pwkit.tabfile.read(). Returns a generator for a sequence of pwkit.Holder objects, one for each row in the table, with attributes for each of the columns.

tabwidthint (default=8)

The tab width to assume. Defaults to 8 and should not be changed unless absolutely necessary.

modestr (default=’rt’)

The file open mode, passed to io.open().

noexistokbool (default=False)

If true, a nonexistent file will result in no items being generated, as opposed to an IOError.

kwargskeywords

Additional arguments are passed to io.open().

Path.read_text(encoding=None, errors=None, newline=None)

Read this path as one large chunk of text.

This function reads in the entire file as one big piece of text and returns it. The encoding, errors, and newline keywords are passed to open().

This is not a good way to read files unless you know for sure that they are small.

Path.read_toml(encoding=None, errors=None, newline=None, **kwargs)

Read this path as a TOML document.

The TOML parsing is done with the pytoml module. The encoding, errors, and newline keywords are passed to open(). The remaining kwargs are passed to toml.load().

Returns the decoded data structure.

Path.read_yaml(encoding=None, errors=None, newline=None, **kwargs)

Read this path as a YAML document.

The YAML parsing is done with the yaml module. The encoding, errors, and newline keywords are passed to open(). The remaining kwargs are passed to yaml.load().

Returns the decoded data structure.

Path.write_pickle(obj)

Dump obj to this path using cPickle.

Path.write_pickles(objs)

objs must be iterable. Write each of its values to this path in sequence using cPickle.

Path.write_yaml(data, encoding=None, errors=None, newline=None, **kwargs)

Read data to this path as a YAML document.

The encoding, errors, and newline keywords are passed to open(). The remaining kwargs are passed to yaml.dump().

Functions helping with Unicode safety

get_stdout_bytes()	Get a reference to the standard output stream that accepts bytes, not unicode characters.
get_stderr_bytes()	Get a reference to the standard error stream that accepts bytes, not unicode characters.

pwkit.io.get_stdout_bytes()

Get a reference to the standard output stream that accepts bytes, not unicode characters.

Returns: a file-like object hooked up to the process’ standard output.

Usually, you want to write text to a process’s standard output stream (“stdout”), so you want sys.stdout to be a stream that accepts Unicode. The function pwkit.cli.unicode_stdio() sets this up in Python 2, which has an imperfect hack to allow Unicode output to work most of the time. However, there are other times when you really do want to write arbitrary binary data to stdout. Depending on whether you’re using Python 2 or Python 3, or whether pwkit.cli.unicode_stdio() has been called, the right way to get access to the underlying byte-based stream is different. This function encapsulates these checks and works across all of these cases.

pwkit.io.get_stderr_bytes()

Get a reference to the standard error stream that accepts bytes, not unicode characters.

Returns: a file-like object hooked up to the process’ standard error.

Usually, you want to write text to a process’s standard error stream (“stderr”), so you want sys.stderr to be a stream that accepts Unicode. The function pwkit.cli.unicode_stdio() sets this up in Python 2, which has an imperfect hack to allow Unicode output to work most of the time. However, there are other times when you really do want to write arbitrary binary data to stderr. Depending on whether you’re using Python 2 or Python 3, or whether pwkit.cli.unicode_stdio() has been called, the right way to get access to the underlying byte-based stream is different. This function encapsulates these checks and works across all of these cases.

Other functions in pwkit.io

These are generally superseded by operations on Path.

pwkit.io.try_open(*args, **kwargs)

Placeholder.

pwkit.io.words(linegen)

Placeholder.

pwkit.io.pathwords(path, mode='rt', noexistok=False, **kwargs)

Placeholder.

pwkit.io.pathlines(path, mode='rt', noexistok=False, **kwargs)

Placeholder.

pwkit.io.make_path_func(*baseparts)

Placeholder.

pwkit.io.djoin(*args)

Placeholder.

pwkit.io.rellink(source, dest)

Placeholder.

pwkit.io.ensure_dir(path, parents=False)

Placeholder.

pwkit.io.ensure_symlink(src, dst)

Placeholder.