Toolshed: system
¶
Import System Module¶
import Naked.toolshed.system
Import System C Module¶
import Naked.toolshed.c.system
The C module must be compiled before you import it. See the naked build documentation for more information.
Description¶
The system
module includes functions for file and directory paths, file and directory testing, file extension testing, file listings, file filters, file metadata, and decorators that insert file paths into function and method parameters. It also includes functions for simple printing to the standard output and standard error streams with exit code handling.
File I/O methods are available in the Naked.toolshed.file
and Naked.toolshed.c.file
modules. Additional information is available in the Toolshed: file documentation.
File and Directory Path Functions¶
-
Naked.toolshed.system.
cwd
()¶ Returns the current working directory path.
Returns: (string) current working directory path
-
Naked.toolshed.system.
directory
(file_path)¶ Returns the directory path to the file in
file_path
.Parameters: file_path (string) – the absolute or relative file path to a file Returns: (string) the directory path that contains the file in file_path
-
Naked.toolshed.system.
file_extension
(file_path)¶ Returns the file extension from a file path.
Parameters: file_path (string) – the absolute or relative file path to a file Returns: (string) the file extension, including the period character
-
Naked.toolshed.system.
filename
(file_path)¶ Returns the base filename from an absolute
file_path
.Parameters: file_path (string) – the absolute or relative file path to a file Returns: (string) base file name including the file extension
-
Naked.toolshed.system.
fullpath
(file_name)¶ Returns the absolute path to a file that is in the current working directory, including the basename of the file.
Parameters: file_name (string) – the name of a file in the current working directory Returns: (string) the absolute path to a file that is in the current working directory
-
Naked.toolshed.system.
make_path
(*path_strings)¶ Returns the OS independent file path from path component parameters
Parameters: *path_strings (string) – tuple of path component strings
from Naked.toolshed.system import make_path file_path = make_path('user', 'guido', 'python', 'file.txt')
Returns: (string) the OS independent path from the path component parameters in *path_strings
File and Directory Path Examples are available below.
File Path Decorators¶
-
@
Naked.toolshed.system.
currentdir_to_basefile
¶ Concatenates the absolute working directory path (string) to the basename of a file in the first parameter of the decorated function
-
@
Naked.toolshed.system.
currentdir_firstparam
¶ Adds the current working directory path (string) as the first parameter of the decorated function
-
@
Naked.toolshed.system.
currentdir_lastparam
¶ Adds the current working directory (string) as the last parameter of the decorated function
File Path Decorator Examples are available below.
File and Directory Testing Functions¶
-
Naked.toolshed.system.
dir_exists
(dir_path)¶ Test for the existence of a directory at the path
dir_path
. This function confirms that the path is a directory and not a symbolic link or file.Parameters: dir_path (string) – the path to be tested for the presence of a directory Returns: (boolean) True
= directory exists atdir_path
;False
= directory does not exist atdir_path
-
Naked.toolshed.system.
file_exists
(file_path)¶ Test for the existence of a file at the path
file_path
. This function confirms that the path is a file and not a symbolic link or directory.Parameters: file_path (string) – the path to be tested for the presence of a file Returns: (boolean) True
= file exists atfile_path
;False
= file does not exist atfile_path
-
Naked.toolshed.system.
is_file
(file_path)¶ Test whether a path resolves to an existing file.
Parameters: file_path (string) – the path to be tested for a file Returns: (boolean) True
= thefile_path
path is a file;False
= thefile_path
path is not a file
-
Naked.toolshed.system.
is_dir
(dir_path)¶ Test whether a path resolves to an existing directory.
Parameters: dir_path (string) – the path to be tested for a directory Returns: (boolean) True
= thedir_path
path is a directory;False
= thedir_path
path is not a directory
File and Directory Testing Examples are available below.
File Metadata Functions¶
-
Naked.toolshed.system.
file_size
(file_path)¶ Returns the size of the file at
file_path
in bytes.Parameters: file_path (string) – the path to the file Returns: (integer) the size of the file in bytes
-
Naked.toolshed.system.
file_mod_time
(file_path)¶ Returns the date and time of the last file modification
Parameters: file_path (string) – the path to the file Returns: (string) The date and time of the last file modification with the format 'Wed Jan 29 23:49:04 2014'
.
File Metadata Examples are available below.
File Listings Functions¶
-
Naked.toolshed.system.
list_all_files
(dir_path)¶ List all files in the path
dir_path
.Parameters: dir_path (string) – the directory path containing the files of interest Returns: (list) Python list with each file path in dir_path
mapped to a list item
-
Naked.toolshed.system.
list_all_files_cwd
()¶ List all files in the current working directory.
Returns: (list) Python list with each file path in the current working directory mapped to a list item
-
Naked.toolshed.system.
list_filter_files
(extension_filter, dir_path)¶ List all files in the path
dir_path
that match the file extension filterextension_filter
. Takes a file extension with or without the associated period character (e.g..py
orpy
).Parameters: - extension_filter (string) – the file extension filter to be used for file selection
- dir_path (string) – the directory path containing the files of interest
Returns: (list) Python list with each matching file path in
dir_path
mapped to a list item
-
Naked.toolshed.system.
list_filter_files_cwd
(extension_filter)¶ List all files in the current working directory that match the file extension filter
extension_filter
. Takes a file extension with or without the associated period character (e.g..py
orpy
).Parameters: extension_filter (string) – the file extension filter to be used for file selection Returns: (list) Python list with each matching file path in current working directory mapped to a list item
-
Naked.toolshed.system.
list_match_pattern
(match_pattern)¶ List all files that match a wildcard
match_pattern
parameter.Parameters: match_pattern (string) – the wildcard match pattern (e.g. '/test/*.py'
)Returns: (list) Python list with each matching file path mapped to a list item
File Listings Examples are available below.
Directory Write Function¶
-
Naked.toolshed.system.
make_dirs
(directory_path)¶ Writes a new directory path to disk if it does not already exist. This function does not overwrite an existing directory path. Will perform a recursive directory tree write for multi-level directory structures. Returns
True
if the directory write is successful. ReturnsFalse
if the directory write does not occur (e.g. requested directory already exists).Parameters: directory_path (string) – the directory path to be written to disk Returns: (boolean) True
= successful directory path write;False
= unsuccessful directory path write
Directory Write Examples are available below.
Symbolic Link Functions¶
-
Naked.toolshed.system.
is_link
(link_path)¶ Test for the presence of a symbolic link at
link_path
.Parameters: link_path (string) – the path to test for the presence of a symbolic link Returns: (boolean) True
= the pathlink_path
is a symbolic link;False
= the pathlink_path
is not a symbolic link
-
Naked.toolshed.system.
real_path
(link_path)¶ Return the real file path pointed to by the path
link_path
.Parameters: link_path (string) – the symbolic link path Returns: (string) the real file path pointed to by the symbolic link link_path
Data Stream Functions¶
-
Naked.toolshed.system.
stdout
(text)¶ Print the
text
string to the standard output stream with a newline character appended to thetext
string. Identical to the Pythonprint()
function.Parameters: text (string) – the string that will be printed to the standard output stream
-
Naked.toolshed.system.
stdout_iter
(iter)¶ Print the items in an iterable object (
iter
) to the standard output stream with a newline after each item.Parameters: iter (object) – An iterable object type in which all of the iterable items provide support for either the __str__
or__repr__
functions.
-
Naked.toolshed.system.
stdout_iter_xnl
(iter)¶ Print the items in an iterable object (
iter
) to the standard output stream without a newline character after each item. This prints the items in sequence on the same line of output.Parameters: iter (object) – An iterable object type in which all of the iterable items provide support for either the __str__
or__repr__
functions.
-
Naked.toolshed.system.
stdout_xnl
(text)¶ Print the
text
string to the standard output stream without a newline character appended to thetext
string.Parameters: text (string) – the string that will be printed to the standard output stream
-
Naked.toolshed.system.
stderr
(text[, exit])¶ Print the
text
string to the standard error stream with an optional non-zero exit status code. A newline character is appended to thetext
string. For non-zeroexit
integers,SystemExit()
is raised with the exit status code.SystemExit()
is not raised by default (or ifexit
is assigned a value of 0).Parameters: - text (string) – the string that will be printed to the standard error stream
- exit (integer) – (optional) the exit status code
-
Naked.toolshed.system.
stderr_xnl
(text[, exit])¶ Print the
text
string to the standard error stream with an optional non-zero exit status code. This function does not append a newline character to the end of thetext
string before printing it to the standard error stream. If the exit status code is changed to a non-zero integer,SystemExit()
is raised with the exit status code.SystemExit()
is not raised by default (or ifexit
is assigned a value of 0).Parameters: - text (string) – the string that will be printed to the standard error stream
- exit (integer) – (optional) the exit status code
Data Stream Examples are available below.
Application Exit Functions¶
-
Naked.toolshed.system.
exit_failure
()¶ Exit the application with exit status code 1.
-
Naked.toolshed.system.
exit_success
()¶ Exit the application with exit status code 0.
-
Naked.toolshed.system.
exit_with_status
(exit_code)¶ Exit the application with exit status code
exit_code
.Parameters: exit_code (integer) – the exit status code. By default, an exit status code of 0 is used.
Application Exit Examples are available below.
File and Directory Path Examples¶
Current Working Directory
from Naked.toolshed.system import cwd
curr_dir = cwd()
Make OS Independent Path String
from Naked.toolshed.system import make_path
file_path = make_path('path', 'to', 'test.txt')
print(file_path) # prints path with OS dependent path delimiters
Directory Path to File
from Naked.toolshed.system import directory, make_path
filepath = make_path('path', 'to', 'test.txt')
dir_path = directory(dir_path)
print(dir_path) # prints '/path/to/' with OS dependent delimiters
File Extension
from Naked.toolshed.system import file_extension, make_path
file_path = make_path('path', 'to', 'test.txt')
extension = file_extension(file_path)
print(extension) # prints '.txt'
Filename
from Naked.toolshed.system import filename, make_path
file_path = make_path('path', 'to', 'test.txt')
file_name = filename(file_path)
print(file_name) # prints 'test.txt'
Absolute File Path
from Naked.toolshed.system import fullpath, make_path
# file /usr/c/test/test.txt & current working directory is /usr/c/test/
absolute_path = fullpath('test.txt')
print(absolute_path) # prints '/usr/c/test/test.txt' with OS dependent delimiters
File Path Decorator Examples¶
Current Working Directory Path Concatenation to First Parameter
from Naked.toolshed.system import currentdir_to_basefile
@currentdir_to_basefile
def tester(path):
print(path)
# when run as tester('test.txt') from /usr/c/test/, prints '/usr/c/test/test.txt' with OS dependent delimiters
Current Working Directory Path as First Parameter
from Naked.toolshed.system import currentdir_firstparam
@currentdir_firstparam
def tester(path=''):
print(path)
# when run as tester() from /usr/c/test/, prints '/usr/c/test/' with OS dependent delimiters
Current Working Directory Path as Last Parameter
from Naked.toolshed.system import currentdir_lastparam
@currentdir_lastparam
def tester(file_name, dir_path=''):
print(dir_path + file_name)
# when run as tester('test.txt') from /usr/c/test/, prints '/usr/c/test/test.txt' with OS dependent delimiters
File and Directory Testing Examples¶
Directory Testing
from Naked.toolshed.system import dir_exists, make_path
# /usr/c/test does exist
dir_path = make_path('usr', 'c', 'test')
if dir_exists(dir_path):
print('yep') # prints 'yep'
File Testing
from Naked.toolshed.system import file_exists, make_path
# /usr/c/test/test.txt exists
file_path = make_path('usr', 'c', 'test', 'test.txt')
if file_exists('/usr/c/test/test.txt'):
print('yep') # prints yep
File Metadata Examples¶
File Size
from Naked.toolshed.system import file_size
size = file_size('test.txt')
print(size) # prints size of 'test.txt' in current working directory in bytes
File Modification Time and Date
from Naked.toolshed.system import file_mod_time
m_time = file_mod_time('test.txt')
print(m_time) # prints 'Wed Jan 29 23:49:04 2014'
File Listings Examples¶
For the following examples, the test directory contains the files: ‘test.txt’, ‘pytest.py’, and ‘rbtest.rb’
All Files in Current Working Directory
from Naked.toolshed.system import list_all_files_cwd
file_list = list_all_files_cwd()
for x in file_list:
print(x)
# prints:
# test.txt
# pytest.py
# rbtest.rb
All Files in Target Directory
from Naked.toolshed.system import list_all_files
dir_path = make_path('path', 'to', 'test')
file_list = list_all_files(dir_path)
for x in file_list:
print(x)
# prints:
# test.txt
# pytest.py
# rbtest.rb
Filter Files by File Extension in Current Working Directory
from Naked.toolshed.system import list_filter_files_cwd
file_list = list_filter_files_cwd('.py')
for x in file_list:
print(x)
# prints:
# pytest.py
Filter Files by Wildcard
from Naked.toolshed.system import list_match_pattern
file_list = list_match_pattern('./*.py')
for x in file_list:
print(x)
# prints:
# pytest.py
Directory Write Examples¶
Make Directory When it Does Not Exist
from Naked.toolshed.system import make_dirs
if make_dirs('test'):
print('success') # prints 'success'
else:
print('fail')
Make Directory When it Does Exist
from Naked.toolshed.system import make_dirs
if make_dirs('test'):
print('success')
else:
print('fail') # prints 'fail'
Data Stream Examples¶
Standard Output Stream Write, With Newline
from Naked.toolshed.system import stdout
stdout('This is a test string')
# prints 'This is a test string\n' to standard output with OS dependent newline character(s)
Standard Output Stream Write, Without Newline
from Naked.toolshed.system import stdout_xnl
stdout_xnl('This is a test string')
# prints 'This is a test string' to standard output
Standard Output Stream Write with Iterable Object, With Newline
from Naked.toolshed.system import stdout_iter
the_list = ['test', 'this', 'string']
stdout_iter(the_list)
# prints to standard output:
# test
# this
# string
Standard Output Stream Write with Iterable Object, Without Newline
from Naked.toolshed.system import stdout_iter_xnl
the_list = ['1', ' ' , '2', ' ' , '3']
stdout_iter_xnl(the_list)
# prints '1 2 3' to standard output
Standard Error Stream Write, With Newline, with Exit Status Code 1
from Naked.toolshed.system import stderr
stderr("Um, that was an error.", 1)
# prints 'Um, that was an error.\n' to standard output with OS dependent newline character(s) and raises SystemExit(1)
Standard Error Stream Write, Without Newline, Without SystemExit
from Naked.toolshed.system import stderr_xnl
stderr_xnl("Um, that was an error.")
# prints 'Um, that was an error' to standard error and does not raise SystemExit()
Application Exit Examples¶
Exit with Zero Status Code
from Naked.toolshed.system import exit_success
# successful code here
exit_success() # raises SystemExit(0)
Exit with Status Code 1
from Naked.toolshed.system import exit_failure
# failing code here
exit_failure() # raises SystemExit(1)
Exit with Any Status Code
from Naked.toolshed.system import exit_with_status
# failing code here
exit_with_status(10) # raises SystemExit(10)