`commandio` package

Submodules

commandio.command module

Command module for UNIX command line interactions.

`Command`	Creates a command object for UNIX command line binaries/programs/applications to be executed.
`DependencyError`	Exception intended for unment dependencies

class commandio.command.Command(command, env=None)[source]

Creates a command object for UNIX command line binaries/programs/applications to be executed. Primary use and use-cases are intended for the subprocess module and its associated classes (i.e. Popen/call/run).

The input argument is a command (string).

Note

The specified command used must be in the system path variable.

command

Command to be executed/run on the command line.

Type: str

env

Dictionary of environment variables to add to subshell.

Type: Dict[str, str]

Usage example:

>>> echo = Command("echo 'Hi! I have arrived!'")
>>> echo
Command(command="echo 'Hi! I have arrived!'", env=None)
>>>
>>> echo.run()
(0, None, None)
Hi! I have arrived! # Output is directed to the shell

Parameters

command (str) – Command to be used.
env (Optional[Dict[str, str]]) – Dictionary of environment variables to add to subshell.

check_dependency(raise_exc=True)[source]

Checks the dependency of some command line executable. Should the dependency not be met, then an exception is raised. Check the system path should problems arise and ensure that the executable of interest is installed and is in the system path.

Usage example:

>>> figlet = Command("figlet python")
>>> figlet.check_dependency() # Raises exception if not in system path

Parameters: raise_exc (bool) – If true, an exception is raised if the dependency is not in the system path. Defaults to False.
Raises: DependencyError – Dependency error exception is raised if the dependency is not met. Defaults to
Return type: bool
Returns: Returns True if dependency is met, OR raises exception (if raise_exc is True)/ returns False otherwise.

run(log=None, debug=False, dryrun=False, stdout=None, shell=False, raise_exc=True)[source]

Uses python’s built-in subprocess module to execute (run) a command from the command line.

The standard output and error can optionally be written to file.

Note

The contents of the stdout output file will be empty if shell is set to True.
shell should remain False as setting it to True exposes risks for the injection of malicious code.

Usage example:

>>> echo = Command("echo 'Hi! I have arrived!'")
>>> echo
Command(command="echo 'Hi! I have arrived!'", env=None)
>>>
>>> # Run/execute command
>>> echo.run()
(0, '', '')

Parameters

log (Union[LogFile, str, None]) – LogFile object or str.
debug (bool) – Sets logging function verbosity to DEBUG level.
dryrun (bool) – Dry run – does not run task. Command is recorded to the log file.
stdout (Optional[str]) – Output file to write standard output to.
shell (bool) – Use shell to execute command.
raise_exec – If true, raises RuntimeError exception if the return code of the command is not 0 - otherwise no exception is raised with non-0 return codes.

Raises

RuntimeError – Exception that is raised if the return code of the command is not 0 and the raise_exc argument is set to True.

Return type

Tuple[int, Optional[str], Optional[str]]

Returns

Return code for command execution (int).
Standard output writtent to file should the ‘stdout’ option be used (str).
Standard error writtent to file should the ‘stdout’ option be used (str).

class commandio.command.DependencyError[source]: Exception intended for unment dependencies

class commandio.command.Command(command, env=None)[source]

Bases: object

Creates a command object for UNIX command line binaries/programs/applications to be executed. Primary use and use-cases are intended for the subprocess module and its associated classes (i.e. Popen/call/run).

The input argument is a command (string).

Note

The specified command used must be in the system path variable.

command

Command to be executed/run on the command line.

Type: str

env

Dictionary of environment variables to add to subshell.

Type: Dict[str, str]

Usage example:

>>> echo = Command("echo 'Hi! I have arrived!'")
>>> echo
Command(command="echo 'Hi! I have arrived!'", env=None)
>>>
>>> echo.run()
(0, None, None)
Hi! I have arrived! # Output is directed to the shell

Parameters

command (str) – Command to be used.
env (Optional[Dict[str, str]]) – Dictionary of environment variables to add to subshell.

check_dependency(raise_exc=True)[source]

Checks the dependency of some command line executable. Should the dependency not be met, then an exception is raised. Check the system path should problems arise and ensure that the executable of interest is installed and is in the system path.

Usage example:

>>> figlet = Command("figlet python")
>>> figlet.check_dependency() # Raises exception if not in system path

Parameters: raise_exc (bool) – If true, an exception is raised if the dependency is not in the system path. Defaults to False.
Raises: DependencyError – Dependency error exception is raised if the dependency is not met. Defaults to
Return type: bool
Returns: Returns True if dependency is met, OR raises exception (if raise_exc is True)/ returns False otherwise.

command: str

env: Dict[str, str] = None

run(log=None, debug=False, dryrun=False, stdout=None, shell=False, raise_exc=True)[source]

Uses python’s built-in subprocess module to execute (run) a command from the command line.

The standard output and error can optionally be written to file.

Note

The contents of the stdout output file will be empty if shell is set to True.
shell should remain False as setting it to True exposes risks for the injection of malicious code.

Usage example:

>>> echo = Command("echo 'Hi! I have arrived!'")
>>> echo
Command(command="echo 'Hi! I have arrived!'", env=None)
>>>
>>> # Run/execute command
>>> echo.run()
(0, '', '')

Parameters

log (Union[LogFile, str, None]) – LogFile object or str.
debug (bool) – Sets logging function verbosity to DEBUG level.
dryrun (bool) – Dry run – does not run task. Command is recorded to the log file.
stdout (Optional[str]) – Output file to write standard output to.
shell (bool) – Use shell to execute command.
raise_exec – If true, raises RuntimeError exception if the return code of the command is not 0 - otherwise no exception is raised with non-0 return codes.

Raises

RuntimeError – Exception that is raised if the return code of the command is not 0 and the raise_exc argument is set to True.

Return type

Tuple[int, Optional[str], Optional[str]]

Returns

Return code for command execution (int).
Standard output writtent to file should the ‘stdout’ option be used (str).
Standard error writtent to file should the ‘stdout’ option be used (str).

exception commandio.command.DependencyError[source]

Bases: Exception

Exception intended for unment dependencies

commandio.enums module

Enums module for the commandio package.

LogLevel

Log level enumerators.

class commandio.enums.LogLevel(value)[source]: Log level enumerators.

class commandio.enums.LogLevel(value)[source]

Bases: Enum

Log level enumerators.

critical: str = 'critical'

debug: str = 'debug'

error: str = 'error'

info: str = 'info'

warning: str = 'warning'

commandio.fileio module

File IO methods, functions and operations for the commandio package.

File

This class creates a File object that encapsulates a number of methods and properites for file and filename handling, and file manipulation.

class commandio.fileio.File(src, ext='', assert_exists=False)[source]

This class creates a File object that encapsulates a number of methods and properites for file and filename handling, and file manipulation.

File object base class that inherits from the IOBaseObj abstract base class.

src

Input file.

Type: str

ext

File extension of input file. If no extension is provided, it is inferred.

Type: str

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     file.touch()
...     file.write_txt("some text")
...
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file
"file_name.txt"

Parameters

src (Union[NewType()(file, str), str]) – Input file (need not exist at runtime/instantiated).
ext (Optional[str]) – File extension of input file. If no extension is provided, it is inferred.
assert_exists (bool) – Asserts that the specified input file must exist.

copy(dst)[source]

Copies file to some source destination.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     new_file: str = file.copy("file2.txt")
...
>>> new_file
"/abs/path/to/file2.txt"
>>>
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.copy("file2.txt")
"/abs/path/to/file2.txt"

Parameters

dst (Union[NewType()(file, str), NewType()(directory, str), str]) – Destination file path.
relative – Symbolically link the file using a relative path.

Return type

str

Returns

String that corresponds to the copied file.

file_parts(ext='')[source]

Similar to MATLAB’s fileparts, this function splits a file and its path into its constituent parts:

file path

filename

extension

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     print(file.file_parts())
...
("path/to/file", "filename", ".txt")
>>>
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.file_parts()
("path/to/file", "filename", ".txt")

Parameters

ext (str) – File extension, needed if the file extension of file object is longer than 4 characters.

Return type

Tuple[NewType()(directory, str), NewType()(file, str), str]

Returns

Absolute file path, excluding filename.
Filename, excluding extension.
File extension.

read(remove_newline=False)[source]

Reads input file text.

Usage example:

>>> from typing import Lines
>>>
>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     lines: List[str] = file.read(remove_newline=True)
...
>>> lines
['These are the file contents','new lines are separate elements']
>>>
>>> # or
>>>
>>> file = File("file_name.txt")
>>> lines: List[str] = file.read(remove_newline=True)
>>> lines
['These are the file contents','new lines are separate elements']

Parameters: remove_newline (bool) – Strip newline characters. Defaults to False.
Return type: List[str]
Returns: List of strings, with each element corresponding to a newline in the file.

remove()[source]

Removes file.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     file.remove()
...
>>>
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.remove()

Return type: None

rm_ext(ext='')[source]

Removes file extension from the file.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     file.touch()
...     print(file.rm_ext())
...
"file_name"
>>>
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.rm_ext()
"file_name"

Parameters: ext (str) – File extension.
Return type: str
Returns: Filename as string with no extension.

touch()[source]

Creates an empty file.

This class method is analagous to UNIX’s touch command.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     file.touch()
...
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.touch()

Return type: None

write(txt='')[source]

Writes/appends text to file.

Note

Text written to file is ALWAYS utf-8 encoded.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     file.write("<Text to be written>")
...
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.write("<Text to be written>")

Parameters: txt (str) – Text/string to be written to file.
Return type: None

class commandio.fileio.File(src, ext='', assert_exists=False)[source]

Bases: IOBaseObj

This class creates a File object that encapsulates a number of methods and properites for file and filename handling, and file manipulation.

File object base class that inherits from the IOBaseObj abstract base class.

src: Input file.

ext: File extension of input file. If no extension is provided, it is inferred.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     file.touch()
...     file.write_txt("some text")
...
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file
"file_name.txt"

Parameters

src (Union[NewType()(file, str), str]) – Input file (need not exist at runtime/instantiated).
ext (Optional[str]) – File extension of input file. If no extension is provided, it is inferred.
assert_exists (bool) – Asserts that the specified input file must exist.

copy(dst)[source]

Copies file to some source destination.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     new_file: str = file.copy("file2.txt")
...
>>> new_file
"/abs/path/to/file2.txt"
>>>
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.copy("file2.txt")
"/abs/path/to/file2.txt"

Parameters

dst (Union[NewType()(file, str), NewType()(directory, str), str]) – Destination file path.
relative – Symbolically link the file using a relative path.

Return type

str

Returns

String that corresponds to the copied file.

ext: str

file_parts(ext='')[source]

Similar to MATLAB’s fileparts, this function splits a file and its path into its constituent parts:

file path

filename

extension

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     print(file.file_parts())
...
("path/to/file", "filename", ".txt")
>>>
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.file_parts()
("path/to/file", "filename", ".txt")

Parameters

ext (str) – File extension, needed if the file extension of file object is longer than 4 characters.

Return type

Tuple[NewType()(directory, str), NewType()(file, str), str]

Returns

Absolute file path, excluding filename.
Filename, excluding extension.
File extension.

read(remove_newline=False)[source]

Reads input file text.

Usage example:

>>> from typing import Lines
>>>
>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     lines: List[str] = file.read(remove_newline=True)
...
>>> lines
['These are the file contents','new lines are separate elements']
>>>
>>> # or
>>>
>>> file = File("file_name.txt")
>>> lines: List[str] = file.read(remove_newline=True)
>>> lines
['These are the file contents','new lines are separate elements']

Parameters: remove_newline (bool) – Strip newline characters. Defaults to False.
Return type: List[str]
Returns: List of strings, with each element corresponding to a newline in the file.

remove()[source]

Removes file.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     file.remove()
...
>>>
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.remove()

Return type: None

rm_ext(ext='')[source]

Removes file extension from the file.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     file.touch()
...     print(file.rm_ext())
...
"file_name"
>>>
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.rm_ext()
"file_name"

Parameters: ext (str) – File extension.
Return type: str
Returns: Filename as string with no extension.

src: str

touch()[source]

Creates an empty file.

This class method is analagous to UNIX’s touch command.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     file.touch()
...
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.touch()

Return type: None

write(txt='')[source]

Writes/appends text to file.

Note

Text written to file is ALWAYS utf-8 encoded.

Usage example:

>>> # Using class object as context manager
>>> with File("file_name.txt") as file:
...     file.write("<Text to be written>")
...
>>> # or
>>>
>>> file = File("file_name.txt")
>>> file.write("<Text to be written>")

Parameters: txt (str) – Text/string to be written to file.
Return type: None

commandio.iobase module

Abstract base class file IO methods, functions and operations for the commandio package.

IOBaseObj

IO abstract base class (ABC) object that encapsulates methods related to file and directory manipulation.

class commandio.iobase.IOBaseObj(src)[source]

IO abstract base class (ABC) object that encapsulates methods related to file and directory manipulation.

This ABC cannot be directly instantiated, and MUST used by a child/sub-class that inherits from this class. Additionally, the ``copy` class method (shown in abstract methods) MUST be overwritten when inheriting from this class.

src

Input string that represents a file or directory.

Type: str

Abstract methods:

copy: Copies a file or recursively copies a directory using copy and copytree from shutil. This method may need to be implemented differently should other aspects of the data need to be preserved (i.e. needing to copy the file metadata with the file).

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...

Parameters: src (str) – Input string that represents a file or directory.

abspath(follow_sym_links=False)[source]

Returns the absolute file path.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC methods
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.abspath())
...
"abspath/to/file_namt.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.abspath()
"abspath/to/file_namt.txt"

Parameters: follow_sym_links (bool) – If set to true, the absolute path of the symlinked file is returned.
Return type: Optional[str]
Returns: String that represents the absolute file path if it exists, otherwise None is returned.

basename()[source]

Retrieves file or directory basename.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.basename())
...
"file_namt.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.basename()
"file_namt.txt"

Return type: Union[NewType()(file, str), NewType()(directory, str), str]
Returns: String that represents the basename of the file or directory.

abstract copy(dst)[source]

Copies file or recursively copies a directory to some destination.

This method is an abstract method AND MUST be overwritten when the parent class IOBaseObj is being inherited from. This allows for the definition of different types of copy methods (e.g. deep vs shallow copies of a file, or the copying of file metadata.)

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC methods
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     new_file: str = file.copy("file2.txt")
...     print(new_file)
...
"/abs/path/to/file2.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.copy("file2.txt")
"/abs/path/to/file2.txt"

Parameters: dst (Union[NewType()(file, str), NewType()(directory, str), str]) – Destination file path.
Return type: Union[NewType()(file, str), NewType()(directory, str), str]
Returns: String that corresponds to the copied file or directory.

dirname()[source]

Retrieves file or directory basename.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.dirname())
...
"/abs/path/to"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.dirname()
"/abs/path/to"

Return type: Union[NewType()(file, str), NewType()(directory, str), str]
Returns: String that represents the directory name of the file or the parent directory of the directory.

exists()[source]

Tests if a file or directory exists.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.exists())
...
False
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.exists()
False

Return type: bool
Returns: Returns True if the file or directory exists and False otherwise.

join(*args)[source]

Joins directory or dirname of a file with additional pathname components.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.join("file2.txt"))
...
"/abs/path/to/dirname/file1/file2.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.join("file2.txt")
"/abs/path/to/dirname/file1/file2.txt"

Parameters: *args – Variable length argument list.
Returns: New file path with the specified directories.
Return type: str

move(dst)[source]

Renames/moves a file/directory.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.move("file2.txt"))
...
"file2.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.move("file2.txt")
"file2.txt"

Parameters: dst (Union[NewType()(file, str), NewType()(directory, str), str]) – Destination file path.
Return type: Union[NewType()(file, str), NewType()(directory, str), str]
Returns: String that represents the path of the new file or directory.

relpath(dst)[source]

Returns the relative file path to some destination.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.relpath('new_dir/file2.txt'))
...
"../file_namt.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.relpath('new_dir/file2.txt')
"../file_namt.txt"

Parameters: dst (Union[NewType()(file, str), NewType()(directory, str), str]) – Destination file path relative to src file path.
Return type: Union[NewType()(file, str), NewType()(directory, str), str]
Returns: String that reprents the relative file path of the object from the destination file or directory.

sym_link(dst, relative=False)[source]

Creates a symbolic link with an absolute or relative file path.

Note

If a directory is used as the input object, then the linked destination is returned.
This WILL NOT WORK on Windows platforms

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC methods
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     linked_file: str = file.sym_link("file2.txt")
...     print(linked_file)
...
"file2.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.sym_link("file2.txt")
"file2.txt"

Parameters

dst (Union[NewType()(file, str), NewType()(directory, str), str]) – Destination file path.
relative (bool) – Symbolically link the file or directory using a relative path.

Return type

Union[NewType()(file, str), NewType()(directory, str), str]

Returns

String that reprents the absolute path of the sym linked file path.

class commandio.iobase.IOBaseObj(src)[source]

Bases: ABC

IO abstract base class (ABC) object that encapsulates methods related to file and directory manipulation.

This ABC cannot be directly instantiated, and MUST used by a child/sub-class that inherits from this class. Additionally, the ``copy` class method (shown in abstract methods) MUST be overwritten when inheriting from this class.

src: Input string that represents a file or directory.

Abstract methods:

copy: Copies a file or recursively copies a directory using copy and copytree from shutil. This method may need to be implemented differently should other aspects of the data need to be preserved (i.e. needing to copy the file metadata with the file).

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...

Parameters: src (str) – Input string that represents a file or directory.

abspath(follow_sym_links=False)[source]

Returns the absolute file path.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC methods
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.abspath())
...
"abspath/to/file_namt.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.abspath()
"abspath/to/file_namt.txt"

Parameters: follow_sym_links (bool) – If set to true, the absolute path of the symlinked file is returned.
Return type: Optional[str]
Returns: String that represents the absolute file path if it exists, otherwise None is returned.

basename()[source]

Retrieves file or directory basename.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.basename())
...
"file_namt.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.basename()
"file_namt.txt"

Return type: Union[NewType()(file, str), NewType()(directory, str), str]
Returns: String that represents the basename of the file or directory.

abstract copy(dst)[source]

Copies file or recursively copies a directory to some destination.

This method is an abstract method AND MUST be overwritten when the parent class IOBaseObj is being inherited from. This allows for the definition of different types of copy methods (e.g. deep vs shallow copies of a file, or the copying of file metadata.)

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC methods
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     new_file: str = file.copy("file2.txt")
...     print(new_file)
...
"/abs/path/to/file2.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.copy("file2.txt")
"/abs/path/to/file2.txt"

Parameters: dst (Union[NewType()(file, str), NewType()(directory, str), str]) – Destination file path.
Return type: Union[NewType()(file, str), NewType()(directory, str), str]
Returns: String that corresponds to the copied file or directory.

dirname()[source]

Retrieves file or directory basename.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.dirname())
...
"/abs/path/to"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.dirname()
"/abs/path/to"

Return type: Union[NewType()(file, str), NewType()(directory, str), str]
Returns: String that represents the directory name of the file or the parent directory of the directory.

exists()[source]

Tests if a file or directory exists.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.exists())
...
False
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.exists()
False

Return type: bool
Returns: Returns True if the file or directory exists and False otherwise.

join(*args)[source]

Joins directory or dirname of a file with additional pathname components.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.join("file2.txt"))
...
"/abs/path/to/dirname/file1/file2.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.join("file2.txt")
"/abs/path/to/dirname/file1/file2.txt"

Parameters: *args – Variable length argument list.
Returns: New file path with the specified directories.
Return type: str

move(dst)[source]

Renames/moves a file/directory.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.move("file2.txt"))
...
"file2.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.move("file2.txt")
"file2.txt"

Parameters: dst (Union[NewType()(file, str), NewType()(directory, str), str]) – Destination file path.
Return type: Union[NewType()(file, str), NewType()(directory, str), str]
Returns: String that represents the path of the new file or directory.

relpath(dst)[source]

Returns the relative file path to some destination.

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC method
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     print(file.relpath('new_dir/file2.txt'))
...
"../file_namt.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.relpath('new_dir/file2.txt')
"../file_namt.txt"

Parameters: dst (Union[NewType()(file, str), NewType()(directory, str), str]) – Destination file path relative to src file path.
Return type: Union[NewType()(file, str), NewType()(directory, str), str]
Returns: String that reprents the relative file path of the object from the destination file or directory.

src: str

sym_link(dst, relative=False)[source]

Creates a symbolic link with an absolute or relative file path.

Note

If a directory is used as the input object, then the linked destination is returned.
This WILL NOT WORK on Windows platforms

Usage example:

>>> # Initialize child class and inherit
>>> #   from IOBaseObj ABC
>>> class SomeFileClass(IOBaseObj):
...     def __init__(self, src: str):
...         super().__init__(src)
...
...     # Overwrite IOBaseObj ABC methods
...     def copy(self, dst: str):
...         return super().copy(dst)
...
>>> # Using class object as context manager
>>> with SomeFileClass("file_name.txt") as file:
...     linked_file: str = file.sym_link("file2.txt")
...     print(linked_file)
...
"file2.txt"
>>>
>>> # OR
>>> file = SomeFileClass("file_name.txt")
>>> file.sym_link("file2.txt")
"file2.txt"

Parameters

dst (Union[NewType()(file, str), NewType()(directory, str), str]) – Destination file path.
relative (bool) – Symbolically link the file or directory using a relative path.

Return type

Union[NewType()(file, str), NewType()(directory, str), str]

Returns

String that reprents the absolute path of the sym linked file path.

commandio.logutil module

Logging utility module.

LogFile

Convenience class that creates a log file object for logging purposes.

class commandio.logutil.LogFile(log_file='', print_to_screen=False, format_log_str=False, use_root_logger=False, level='info', exc_info=False, stack_info=False, stacklevel=1)[source]

Convenience class that creates a log file object for logging purposes.

log_file

Log filename.

Type: str

Usage examples:

>>> log = LogFile("file.log",False)
>>> log
"file.log"

Parameters

file – Log filename (need not exist at runtime).
print_to_screen (bool) – If true, prints output to standard output (stdout) as well.
format_log_str (bool) – If true, this formats the logging information with more detail.
use_root_logger (bool) – If true, ALL information is written to a single log file.
level (str) – Logging level. Options include: * info * debug * critical * error * warning
exc_info (bool) – Adds exception information to the logging message.
stack_info (bool) – Adds stack information to the logging message.
stacklevel (int) – If greater than 1, the corresponding number of stack frames are skipped when computing the line number and function name set in the LogRecord for the logging event.

critical(msg, use_header=False)[source]

Write critical messages/information to file.

Usage example:

>>> log = LogFile("file.log")
>>> log.critical("<str>")

Parameters

msg (str) – String to be printed to log file.
use_header (bool) – Give log message a section header.

Return type

None

debug(msg='', use_header=False)[source]

Writes debug information to file.

Usage examples:

>>> log = LogFile("file.log")
>>> log.debug("<str>")

Parameters

msg (str) – String to be printed to log file.
use_header (bool) – Give log message a section header.

Return type

None

error(msg='', use_header=False)[source]

Writes error information to file.

Usage examples:

>>> log = LogFile("file.log")
>>> log.error("<str>")

Parameters

msg (str) – String to be printed to log file.
use_header (bool) – Give log message a section header.

Return type

None

info(msg='', use_header=False)[source]

Writes information to log file.

Usage examples:

>>> log = LogFile("file.log")
>>> log.info("<str>")

Parameters

msg (str) – String to be printed to log file.
use_header (bool) – Give log message a section header.

Return type

None

log(log_cmd='', use_header=False)[source]

Log function for logging commands and messages to some log file.

Usage examples:

>>> log = LogFile("file.log")
>>> log.log("<str>")

Parameters

log_cmd (str) – Message to be written to log file.
use_header (bool) – Give log message a section header.

Return type

None

warning(msg='', use_header=False)[source]

Writes warnings to file.

Usage examples:

>>> log = LogFile("file.log")
>>> log.warning("<str>")

Parameters

msg (str) – String to be printed to log file.
use_header (bool) – Give log message a section header.

Return type

None

class commandio.logutil.LogFile(log_file='', print_to_screen=False, format_log_str=False, use_root_logger=False, level='info', exc_info=False, stack_info=False, stacklevel=1)[source]

Bases: File

Convenience class that creates a log file object for logging purposes.

log_file: Log filename.

Usage examples:

>>> log = LogFile("file.log",False)
>>> log
"file.log"

Parameters

file – Log filename (need not exist at runtime).
print_to_screen (bool) – If true, prints output to standard output (stdout) as well.
format_log_str (bool) – If true, this formats the logging information with more detail.
use_root_logger (bool) – If true, ALL information is written to a single log file.
level (str) – Logging level. Options include: * info * debug * critical * error * warning
exc_info (bool) – Adds exception information to the logging message.
stack_info (bool) – Adds stack information to the logging message.
stacklevel (int) – If greater than 1, the corresponding number of stack frames are skipped when computing the line number and function name set in the LogRecord for the logging event.

critical(msg, use_header=False)[source]

Write critical messages/information to file.

Usage example:

>>> log = LogFile("file.log")
>>> log.critical("<str>")

Parameters

msg (str) – String to be printed to log file.
use_header (bool) – Give log message a section header.

Return type

None

debug(msg='', use_header=False)[source]

Writes debug information to file.

Usage examples:

>>> log = LogFile("file.log")
>>> log.debug("<str>")

Parameters

msg (str) – String to be printed to log file.
use_header (bool) – Give log message a section header.

Return type

None

error(msg='', use_header=False)[source]

Writes error information to file.

Usage examples:

>>> log = LogFile("file.log")
>>> log.error("<str>")

Parameters

msg (str) – String to be printed to log file.
use_header (bool) – Give log message a section header.

Return type

None

ext: str

info(msg='', use_header=False)[source]

Writes information to log file.

Usage examples:

>>> log = LogFile("file.log")
>>> log.info("<str>")

Parameters

msg (str) – String to be printed to log file.
use_header (bool) – Give log message a section header.

Return type

None

log(log_cmd='', use_header=False)[source]

Log function for logging commands and messages to some log file.

Usage examples:

>>> log = LogFile("file.log")
>>> log.log("<str>")

Parameters

log_cmd (str) – Message to be written to log file.
use_header (bool) – Give log message a section header.

Return type

None

src: str

warning(msg='', use_header=False)[source]

Writes warnings to file.

Usage examples:

>>> log = LogFile("file.log")
>>> log.warning("<str>")

Parameters

msg (str) – String to be printed to log file.
use_header (bool) – Give log message a section header.

Return type

None

commandio.tmpdir module

Temporary working directory module for the commandio package.

TmpDir

Temporary directory class that creates (random) temporary directories and files given a parent directory.

class commandio.tmpdir.TmpDir(src, use_cwd=False, cleanup=True)[source]

Temporary directory class that creates (random) temporary directories and files given a parent directory.

This class inherits methods from the WorkDir base class.

src

Input temproary working directory.

Type: str

parent_dir

Parent directory of the specified temproary directory.

Type: str

Usage example:

>>> with TmpDir("/path/to/temporary_directory",False) as tmp_dir:
 ...     cwd = os.getcwd()
 ...     print("My temporary directory")
 ...     os.chdir(tmp_dir.src)
 ...     # do more stuff
 ...     os.chdir(cwd)
 ...
 >>> # or
 >>>
 >>> tmp_dir = TmpDir("/path/to/temporary_directory")
 >>> tmp_dir
 "/path/to/temporary_directory"
 >>> tmp_dir.rmdir(rm_parent=False)

Parameters

src (Union[NewType()(directory, str), str]) – Temporary parent directory name/path.
use_cwd (bool) – Use current working directory as working direcory.
cleanup (bool) – Perform clean-up of the temporary directory.

class commandio.tmpdir.TmpDir(src, use_cwd=False, cleanup=True)[source]

Bases: WorkDir

Temporary directory class that creates (random) temporary directories and files given a parent directory.

This class inherits methods from the WorkDir base class.

src

Input temproary working directory.

Type: str

parent_dir: Parent directory of the specified temproary directory.

Usage example:

>>> with TmpDir("/path/to/temporary_directory",False) as tmp_dir:
 ...     cwd = os.getcwd()
 ...     print("My temporary directory")
 ...     os.chdir(tmp_dir.src)
 ...     # do more stuff
 ...     os.chdir(cwd)
 ...
 >>> # or
 >>>
 >>> tmp_dir = TmpDir("/path/to/temporary_directory")
 >>> tmp_dir
 "/path/to/temporary_directory"
 >>> tmp_dir.rmdir(rm_parent=False)

Parameters

src (Union[NewType()(directory, str), str]) – Temporary parent directory name/path.
use_cwd (bool) – Use current working directory as working direcory.
cleanup (bool) – Perform clean-up of the temporary directory.

parent_dir: str

src: str

commandio.tmpfile module

Temporary file module for the commandio package.

TmpFile

Creates and manipulates temporary files via inheritance from the File object base class.

class commandio.tmpfile.TmpFile(tmp_dir='', tmp_file='', ext='')[source]

Creates and manipulates temporary files via inheritance from the File object base class.

file: Temporary file name.

ext

File extension of input file. If no extension is provided, it is inferred.

Type: str

Usage example:

>>> tmp_directory = TmpDir("/path/to/temporary_directory")
>>>
>>> temp_file = TmpFile(tmp_directory.tmp_dir,
...                             ext="txt")
...
>>> temp_file
"/path/to/temporary_directory/temporary_file.txt"

Parameters

tmp_file (Union[NewType()(file, str), str, None]) – Temporary file name.
ext (Optional[str]) – Temporary directory file extension.

class commandio.tmpfile.TmpFile(tmp_dir='', tmp_file='', ext='')[source]

Bases: File

Creates and manipulates temporary files via inheritance from the File object base class.

file: Temporary file name.

ext

File extension of input file. If no extension is provided, it is inferred.

Type: str

Usage example:

>>> tmp_directory = TmpDir("/path/to/temporary_directory")
>>>
>>> temp_file = TmpFile(tmp_directory.tmp_dir,
...                             ext="txt")
...
>>> temp_file
"/path/to/temporary_directory/temporary_file.txt"

Parameters

tmp_file (Union[NewType()(file, str), str, None]) – Temporary file name.
ext (Optional[str]) – Temporary directory file extension.

ext: str

src: str

commandio.util module

Utility module for the commandio package.

timeops

Decorator function that times some operation and writes that time to a log file object.

commandio.util.timeops(log=None)[source]

Decorator function that times some operation and writes that time to a log file object.

Usage example:

>>> from logutil import LogFile
>>> log = LogFile('my_log_file.log')
>>>
>>> @timeops(log)
>>> def my_func(args*, log):
...     for i in args:
...         log.log(f"This is an arg: {i}")
...     return None
...
>>> # The length of time to complete the operation
>>> # should be written to the log file.
>>> myfunc(args*, log)

Parameters: log (Optional[LogFile]) – Log file object to be written to.
Return type: callable
Returns: Callable function/class

commandio.workdir module

Working directory module for the commandio package.

WorkDir

Working directory base class that instantiates WorkDir objects that creates and manipulates working directories.

class commandio.workdir.WorkDir(src, use_cwd=False)[source]

Working directory base class that instantiates WorkDir objects that creates and manipulates working directories.

src

Input working directory.

Type: str

parent_dir

Parent directory.

Type: str

Usage example:

>>> # Using class object as context manager
>>> ## Create work directory , then clean-up (remove it)
>>> with WorkDir(src="/path/to/working_directory", use_cwd=False) as work:
...     work.mkdir()
...     work.rmdir(rm_parent=False)
...
>>> # or
>>>
>>> work = WorkDir(src="/path/to/working_directory",
...                use_cwd=False)
>>> work.mkdir()
>>> work
"/path/to/working_directory"
>>> work.rmdir(rm_parent=False)

Parameters

src (Union[NewType()(directory, str), str]) – Working directory name/path. This directory need not exist at runtime.
use_cwd (bool) – Use current working directory as the parent directory.

copy(dst)[source]

Recursively copies a directory to some destination.

Usage example:

>>> # Using class object as context manager
>>> with WorkDir("/path/to/working_directory") as work_dir:
...     work: str = work_dir.copy("/path/to/new/directory")
...
>>> work
"/path/to/new/directory"
>>>
>>> # or
>>>
>>> work = WorkDir("/path/to/working_directory")
>>> work.copy("/path/to/new/directory")
"/path/to/new/directory"

Parameters: dst (Union[NewType()(directory, str), str]) – Destination file path.
Return type: str
Returns: String that corresponds to the copied work.

mkdir()[source]

Makes/creates the working directory.

This class method is analogous to UNIX’s mkdir -p command and option combination.

Usage example:

>>> # Using class object as context manager
>>> with WorkDir(src="/path/to/working_directory", use_cwd=False) as work:
...     work.mkdir()
...
>>> # or
>>>
>>> work = WorkDir(src="/path/to/working_directory",
...                use_cwd=False)
>>> work.mkdir()
>>> work
"/path/to/working_directory"

Return type: None

rmdir(rm_parent=False)[source]

Removes working directory, and the parent directory if indicated to do so.

This class method is analogous to UNIX’s rm -rf command and option combination.

Usage example:

>>> # Using class object as context manager
>>> with WorkDir(src="/path/to/working_directory", use_cwd=False) as work:
...     work.mkdir()
...     work.rmdir(rm_parent=False)
...
>>> # or
>>>
>>> work = WorkDir(src="/path/to/working_directory",
...                use_cwd=False)
>>> work.mkdir()
>>> work.rmdir(rm_parent=False)

Parameters: rm_parent (bool) – Removes parent directory as well.
Return type: None

class commandio.workdir.WorkDir(src, use_cwd=False)[source]

Bases: IOBaseObj

Working directory base class that instantiates WorkDir objects that creates and manipulates working directories.

src

Input working directory.

Type: str

parent_dir: Parent directory.

Usage example:

>>> # Using class object as context manager
>>> ## Create work directory , then clean-up (remove it)
>>> with WorkDir(src="/path/to/working_directory", use_cwd=False) as work:
...     work.mkdir()
...     work.rmdir(rm_parent=False)
...
>>> # or
>>>
>>> work = WorkDir(src="/path/to/working_directory",
...                use_cwd=False)
>>> work.mkdir()
>>> work
"/path/to/working_directory"
>>> work.rmdir(rm_parent=False)

Parameters

src (Union[NewType()(directory, str), str]) – Working directory name/path. This directory need not exist at runtime.
use_cwd (bool) – Use current working directory as the parent directory.

copy(dst)[source]

Recursively copies a directory to some destination.

Usage example:

>>> # Using class object as context manager
>>> with WorkDir("/path/to/working_directory") as work_dir:
...     work: str = work_dir.copy("/path/to/new/directory")
...
>>> work
"/path/to/new/directory"
>>>
>>> # or
>>>
>>> work = WorkDir("/path/to/working_directory")
>>> work.copy("/path/to/new/directory")
"/path/to/new/directory"

Parameters: dst (Union[NewType()(directory, str), str]) – Destination file path.
Return type: str
Returns: String that corresponds to the copied work.

mkdir()[source]

Makes/creates the working directory.

This class method is analogous to UNIX’s mkdir -p command and option combination.

Usage example:

>>> # Using class object as context manager
>>> with WorkDir(src="/path/to/working_directory", use_cwd=False) as work:
...     work.mkdir()
...
>>> # or
>>>
>>> work = WorkDir(src="/path/to/working_directory",
...                use_cwd=False)
>>> work.mkdir()
>>> work
"/path/to/working_directory"

Return type: None

parent_dir: str

rmdir(rm_parent=False)[source]

Removes working directory, and the parent directory if indicated to do so.

This class method is analogous to UNIX’s rm -rf command and option combination.

Usage example:

>>> # Using class object as context manager
>>> with WorkDir(src="/path/to/working_directory", use_cwd=False) as work:
...     work.mkdir()
...     work.rmdir(rm_parent=False)
...
>>> # or
>>>
>>> work = WorkDir(src="/path/to/working_directory",
...                use_cwd=False)
>>> work.mkdir()
>>> work.rmdir(rm_parent=False)

Parameters: rm_parent (bool) – Removes parent directory as well.
Return type: None

src: str

Module contents

The commandio package contains modules for reading/writing files, logging, and running commands on the command line.

`command`	Command module for UNIX command line interactions.
`enums`	Enums module for the `commandio` package.
`fileio`	File IO methods, functions and operations for the `commandio` package.
`iobase`	Abstract base class file IO methods, functions and operations for the `commandio` package.
`logutil`	Logging utility module.
`tmpdir`	Temporary working directory module for the `commandio` package.
`tmpfile`	Temporary file module for the `commandio` package.
`util`	Utility module for the `commandio` package.
`workdir`	Working directory module for the `commandio` package.

commandio package

Submodules

commandio.command module

commandio.enums module

commandio.fileio module

commandio.iobase module

commandio.logutil module

commandio.tmpdir module

commandio.tmpfile module

commandio.util module

commandio.workdir module

Module contents

`commandio` package