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
[source]¶ 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 otherPath
instances.
-
classmethod
cwd
()[source]¶ Returns a new path containing the absolute path of the current working directory.
-
classmethod
create_tempfile
(want='handle', resolution='try_unlink', suffix='', **kwargs)[source]¶ 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; usewant="path"
to get aPath
.
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.
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.
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.
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 thatname = 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"]
. Ifname
contains no periods, the empty list is returned.
Detailed descriptions of methods
-
Path.
absolute
()[source]¶ 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)[source]¶ 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.- user : bool (default False)
- Expand
~
and~user
home-directory constructs. If a username is unmatched or$HOME
is unset, no change is made. Callsos.path.expanduser()
. - vars : bool (default False)
- Expand
$var
and${var}
environment variable constructs. Unknown variables are not substituted. Callsos.path.expandvars()
. - glob : bool (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 anIOError
. - resolve : bool (default False)
- Call
resolve()
on the return value before returning it.
-
Path.
format
(*args, **kwargs)[source]¶ Return a new path formed by calling
str.format()
on the textualization of this path.
-
Path.
get_parent
(mode='naive')[source]¶ 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 top
, 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)[source]¶ 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
()[source]¶ 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.
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 () |
Return the result of the stat() system call on this path, like os.stat() does. |
Detailed descriptions
-
Path.
glob
(pattern)[source]¶ Assuming that the path is a directory, iterate over its contents and return sub-paths matching the given shell-style glob pattern.
-
Path.
iterdir
()[source]¶ 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
()[source]¶ 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)[source]¶ Recursively yield all files and directories matching the shell glob pattern pattern below this path.
-
Path.
scandir
()[source]¶ 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 methodsinode()
,is_dir()
,is_file()
,is_symlink()
, andstat()
. They have attributesname
(the basename of the entry) andpath
(its full path).
Filesystem modifications¶
These functions actually modify the filesystem.
chmod (mode) |
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 given 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 given path. |
touch ([mode, exist_ok]) |
Create this file with the given access mode, if it doesn’t exist. |
unlink () |
Remove this file or link. |
try_unlink () |
Try to unlink this path. |
Detailed descriptions
-
Path.
copy_to
(dest, preserve='mode')[source]¶ 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)[source]¶ 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 currentos.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)[source]¶ 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)[source]¶ 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 likefoo/bar
, the path of the temporary file will be something likefoo/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 aPath
instance as its path attribute. "path"
- The temporary file is created as in
"handle"
, but is then immediately closed. APath
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)[source]¶ 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)[source]¶ Make this path a symlink pointing to the given target, generating the proper relative path using
make_relative()
. This gives different behavior thansymlink_to()
. For instance,Path ('a/b').symlink_to ('c')
results ina/b
pointing to the pathc
, whereasrellink_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
tobee/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.
rmtree
(errors='warn')[source]¶ 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)[source]¶ Make this path a symlink pointing to the given target.
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)[source]¶ Open the file pointed at by the path and return a
file
object. This delegates to the modernio.open()
function, not the global builtinopen()
.
-
Path.
try_open
(null_if_noexist=False, **kwargs)[source]¶ 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)[source]¶ Return the path as an opened
pandas.HDFStore
object. Note that theHDFStore
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 theHDFStore
constructor.
-
Path.
read_astropy_ascii
(**kwargs)[source]¶ Open as an ASCII table, returning a
astropy.table.Table
object. Keyword arguments are passed toastropy.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)[source]¶ Open as a FITS file, returning a
astropy.io.fits.HDUList
object. Keyword arguments are passed toastropy.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)[source]¶ Open as a FITS file, read in a binary table, and return it as a
pandas.DataFrame
, converted withpkwit.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 inpandas.DataFrame`s) should be silently ignored (``True`
) or cause aValueError
to be raised (False
). Other kwargs are passed toastropy.io.fits.open()
, (seePath.read_fits()
) although the open mode is hardcoded to be"readonly"
.
-
Path.
read_hdf
(key, **kwargs)[source]¶ Open as an HDF5 file using
pandas
and return the item stored under the key key. kwargs are passed topandas.read_hdf()
.
-
Path.
read_inifile
(noexistok=False, typed=False)[source]¶ Open assuming an “ini-file” format and return a generator yielding data records using either
pwkit.inifile.read_stream()
(if typed is false) orpwkit.tinifile.read_stream()
(if it’s true). The latter version is designed to work with numerical data using thepwkit.msmt
subsystem. If noexistok is true, a nonexistent file will result in no items being generated rather than anIOError
being raised.
-
Path.
read_json
(mode='rt', **kwargs)[source]¶ Use the
json
module to read in this file as a JSON-formatted data structure. Keyword arguments are passed tojson.load()
. Returns the read-in data structure.
-
Path.
read_lines
(mode='rt', noexistok=False, **kwargs)[source]¶ 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)[source]¶ Read this path into a
numpy.ndarray
usingnumpy.load()
. kwargs are passed tonumpy.load()
; they likely are:- mmap_mode : None, ‘r+’, ‘r’, ‘w+’, ‘c’
- Load the array using memory-mapping
- allow_pickle : bool = True
- Whether Pickle-format data are allowed; potential security hazard.
- fix_imports : bool = 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)[source]¶ Read this path into a
numpy.ndarray
as a text file usingnumpy.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 thenumpy.loadtxt()
call. For convenience, if dfcols is a single string, it will by turned into an iterable by a call tostr.split()
.The remaining kwargs are passed to
numpy.loadtxt()
; they likely are:- dtype : data type
- The data type of the resulting array.
- comments : str
- If specific, a character indicating the start of a comment.
- delimiter : str
- The string that separates values. If unspecified, any span of whitespace works.
- converters : dict
- A dictionary mapping zero-based column number to a function that will turn the cell text into a number.
- skiprows : int (default=0)
- Skip this many lines at the top of the file
- usecols : sequence
- Which columns keep, by number, starting at zero.
- unpack : bool (default=False)
- If true, the return value is transposed to be of shape
(cols, rows)
. - ndmin : int (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)[source]¶ Read using
pandas
. The functionpandas.read_FORMAT
is called whereFORMAT
is set from the argument format. kwargs are passed to this function. Supported formats likely includeclipboard
,csv
,excel
,fwf
,gbq
,html
,json
,msgpack
,pickle
,sql
,sql_query
,sql_table
,stata
,table
. Note thathdf
is not supported because it requires a non-keyword argument; seePath.read_hdf()
.
-
Path.
read_pickles
()[source]¶ Generate a sequence of objects by opening the path and unpickling items until EOF is reached.
-
Path.
read_tabfile
(**kwargs)[source]¶ Read this path as a table of typed measurements via
pwkit.tabfile.read()
. Returns a generator for a sequence ofpwkit.Holder
objects, one for each row in the table, with attributes for each of the columns.- tabwidth : int (default=8)
- The tab width to assume. Defaults to 8 and should not be changed unless absolutely necessary.
- mode : str (default=’rt’)
- The file open mode, passed to
io.open()
. - noexistok : bool (default=False)
- If true, a nonexistent file will result in no items being generated, as
opposed to an
IOError
. - kwargs : keywords
- Additional arguments are passed to
io.open()
.
-
Path.
read_text
(encoding=None, errors=None, newline=None)[source]¶ 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)[source]¶ Read this path as a TOML document.
The TOML parsing is done with the
pytoml
module. The encoding, errors, and newline keywords are passed toopen()
. The remaining kwargs are passed totoml.load()
.Returns the decoded data structure.
-
Path.
read_yaml
(encoding=None, errors=None, newline=None, **kwargs)[source]¶ Read this path as a YAML document.
The YAML parsing is done with the
yaml
module. The encoding, errors, and newline keywords are passed toopen()
. The remaining kwargs are passed toyaml.load()
.Returns the decoded data structure.
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
()[source]¶ 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 functionpwkit.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 whetherpwkit.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
()[source]¶ 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 functionpwkit.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 whetherpwkit.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.