API Reference

pyos

exception pyos.FileNotFoundError

A file was not found

exception pyos.IsADirectoryError

Raise when a file is expected but a directory was passed

exception pyos.NotADirectoryError

Raise when a directory is expected but a file was passed

class pyos.Path(*_args, **_kwargs)

A path in Pyos. Where possible the convention follows that of a PurePosixPath in pathlib. The one major exception is that folders are represented with an explicit trailing ‘/’ and anything else is a file.

exists() → bool

Test whether a path point exists

is_dir() → bool

Returns True if this path is a directory path and exists

is_file() → bool

Returns True if this path is a file path and exists

iterdir() → Path'>]

When the path points to a directory, yield path objects of the directory contents:

>>>
>>> p = Path('docs')
>>> for child in p.iterdir(): child
...
Path('docs/conf')
Path('docs/readme')
Path('docs/index.rst')
Path('docs/_build')
Path('docs/_static')

resolve() → Path'>]

Make the path absolute eliminating any . and .. that occur in the path

class pyos.PurePath(path: Union[str, PathLike] = '.')

A path in PyOS. Where possible the convention follows that of a PurePosixPath in pathlib.

This is a ‘pure’ path in a similar sense to pathlib.PurePath in that it does not interact with the database at all.

is_dir_path() → bool

Returns True if this path specified a directory i.e. ends with a trailing ‘/’

is_file_path() → bool

Returns True if this path specifies a file i.e. does not end with a training ‘/’

property parents: Sequence

Get a sequence of paths that are the parents of this path

to_dir() → PurePath

If this path is a file path then a directory with the same name will be returned. Otherwise, this path will be returned

Deprecated since version 0.8.0: This will be removed in 0.9.0. We no longer make a distinction between a file path and dir path

to_file()

If this path is a directory then a file path with the same name will be returned. Otherwise, this path will be returned

Deprecated since version 0.8.0: This will be removed in 0.9.0. We no longer make a distinction between a file path and dir path

exception pyos.PyOSError

Raised when there is a PyOS exception

pyos.working_path(path: Union[str, PathLike])

Context manager that changes the current working directory for the duration of the context, returning to the previous directory on exiting

pyos.db

Database related classes, functions and constants

pyos.db.get_abspath(obj_id, _meta: dict) → str

Given an object id this method will return a string representing the absolute path of the object

pyos.db.get_historian() → Historian

Get the active historian in pyos

pyos.db.get_meta(obj_id: Union[Any, Iterable[Any]])

Get the metadata for a bunch of objects

pyos.db.get_obj_id(path: Union[str, PathLike])

Given a path get the id of the corresponding object. Returns None if not found.

Deprecated since version 0.7.10: This will be removed in 0.8.0. Use next(get_obj_id_from_path()) instead

pyos.db.get_obj_id_from_path(*path: Union[str, PathLike]) → Iterator

Given a path yield the id of the corresponding object. Yields None if not found.

pyos.db.get_obj_name(obj_id, meta: dict) → str

Get the name of an object. This will be the name that is used to represent this object on the virtual filesystem and is stored in the metadata

Deprecated since version 0.8.0: This will be removed in 0.9.0. No longer use metadata to store filesystem location

pyos.db.get_oid(*identifier) → Iterator

Get one or more object ids.

Parameters

identifier – can be any of the following: * an object id * an object instance * a string representing a valid object id * the path to an object these will be tested in order in an attempt to get the object id. If all fail then None will be yielded.

pyos.db.get_path(obj_or_id) → Optional[str]

Given an object or object id get the current path

pyos.db.get_paths(*obj_or_id, historian: Optional[Historian] = None) → Sequence[PathInfo]

Given objects or identifier this will return their current paths as PathInfo tuples in the order that they were passed in. A PathInfo consists of the object id and the corresponding path.

This choice of return value makes it easy to construct dictionaries, e.g.: >>> obj_paths = dict(get_path(‘obj123’, ‘obj456’)) where object ids have been passed in as strings. It is important to note, that when constructing such a dictionary duplicate values will be joined. Whether this is desired will depend on the use case.

pyos.db.homedir(user: str = '') → str

Return the user’s home directory

pyos.db.init(historian: Optional[Historian] = None, use_globally=True) → Historian

Initialise a Historian such that it is ready to be used with pyOS

pyos.db.load(*identifier)

Load one or more objects

pyos.db.path_from_meta_entry(obj_id, meta: dict) → Optional[str]

Deprecated since version 0.8.0: This will be removed in 0.9.0. No longer use metadata to store filesystem location

pyos.db.path_to_meta_dict(path: Union[str, PathLike]) → dict

Parameters

path – the path to get a dictionary for

Returns

the meta dictionary with the path

Deprecated since version 0.8.0: This will be removed in 0.9.0. No longer use metadata to store filesystem location

pyos.db.rename(obj_or_id, dest: Union[str, PathLike])

Rename an object to the dest. If dest is a directory IsADirectoryError is raised.

pyos.db.save_many(to_save: Iterable[Union[Any, Tuple[Any, Union[str, PathLike]]]], overwrite=False, show_progress=True, historian: Optional[Historian] = None)

Save many objects, expects an iterable where each entry is an object to save or a tuple of length 2 containing the object and a path of where to save it.

Parameters

• to_save – the iterable able objects to save

• overwrite – overwrite objects with the same name

• historian – the historian to use

pyos.db.save_one(obj, path: Optional[Union[str, PathLike]] = None, overwrite=False, meta=None, historian: Optional[Historian] = None)

Save one object at the given path. The path can be a filename or a directory or a filename in a directory

Parameters

• obj – the object to save

• path – the optional path to save it to

• overwrite – overwrite if there is already an object at that path

• meta – an optional dictionary of metadata to store with the object

• historian – the historian to use for saving

pyos.db.set_meta(*obj_or_identifier, meta: dict)

Set the metadata for a bunch of objects

pyos.db.set_path(obj_id, path: Union[str, PathLike]) → str

Given an object or object id set the current path and return the new abspath

pyos.db.set_paths(*obj_id_path: Tuple[Any, Union[str, PathLike]], historian: Optional[Historian] = None) → Sequence[PathInfo]

Set the path for one or more objects. This function expects (object or identifier, path) tuples and returns the corresponding PathInfo objects with absolute paths in the same order as the arguments

pyos.db.to_obj_id(identifier)

Get the database object id from the passed identifier. If the identifier is already a mincePy object id it will be returned unaltered. Otherwise, mincePy will try and turn the type into an object id. If it fails, None is returned

pyos.db.update_meta(*obj_or_identifier, meta: dict)

Update the metadata for a bunch of objects

pyos.fs

Higher-level classes and functions for browsing the database as a filesystem

class pyos.fs.BaseNode(name: str, parent: BaseNode = (), historian: Optional[Historian] = None)

Base node for the object system in pyos

delete()

Delete this node and any descendents

property height: int

Get the maximum number of steps from this node to a leaf

move(dest: Union[str, PathLike], overwrite=False)

Move this object (with any children) into the directory given by dest

Parameters

• dest – the destination to move the node to

• overwrite – overwrite if exists

property parent: Optional[BaseNode]

Get the parent node

class pyos.fs.ContainerNode(name: str, parent: BaseNode = (), historian: Optional[Historian] = None)

A node that contains children that can be either directory nodes or object nodes

property showing: set

Returns the current view properties that are being displayed (if the view mode supports them)

class pyos.fs.DirectoryNode(path: Union[str, PathLike], parent: BaseNode = (), entry: Optional[Dict] = None, *, historian: Optional[Historian] = None)

A node representing an object system directory

Parameters

• path – the path this node represents

• parent – parent node

delete()

Delete this node and any descendents

expand(depth=1, populate_objects=False)

Populate the children with what is currently in the database

Parameters

• depth – expand to the given depth, 0 means no expansion, 1 means my child nodes, etc

• populate_objects – if True objects will have their records fetched immediately (as opposed to lazily when needed). This gives a large speedup when the client knows that the all or most of the details of the child objects will be needed as they can be fetched in one call.

move(dest: Union[str, PathLike], overwrite=False)

Move this object (with any children) into the directory given by dest

Parameters

• dest – the destination to move the node to

• overwrite – overwrite if exists

rename(new_name: str)

Rename this filesystem node

class pyos.fs.ObjectNode(obj_id, path: Union[str, PathLike], record: Optional[DataRecord] = None, parent=None, entry: Optional[Dict] = None, historian: Optional[Historian] = None)

A node that represents an object

Parameters

• path – the path this node represents

• parent – parent node

delete()

Delete this node and any descendents

move(dest: Union[str, PathLike], overwrite=False)

Move this object (with any children) into the directory given by dest

Parameters

• dest – the destination to move the node to

• overwrite – overwrite if exists

rename(new_name: str)

Rename this filesystem node

class pyos.fs.ResultsNode(name='results', parent=None, historian: Optional[Historian] = None)

append(node: FilesystemNode, display_name: Optional[str] = None)

Append a node to the results

extend(other: ContainerNode)

Extend this results using incorporating the entries of the other container

pyos.fs.find(*starting_point, meta: Optional[dict] = None, state: Optional[dict] = None, type=None, obj_filter: Optional[Expr] = None, mindepth=0, maxdepth=- 1, historian: Optional[Historian] = None) → FrozenResultsNode

Find objects matching the given criteria

Parameters

• starting_point – the starting points for the search, if not supplied defaults to ‘/’

• meta – filter criteria for the metadata

• state – filter criteria for the object’s saved state

• type – restrict the search to this type (can be a tuple of types)

• mindepth – the minimum depth from the starting point(s) to search in

• maxdepth – the maximum depth from the starting point(s) to search in

• historian – the Historian to use

Returns

results node

pyos.fs.to_node(entry, historian: Historian = None) → FilesystemNode

pyos.fs.to_node(entry: FilesystemNode, historian: Optional[Historian] = None)

pyos.fs.to_node(path: PathLike, historian: Optional[Historian] = None)

Get the node for a given object. This can be either:

1. A directory path -> DirectoryNode

2. An object path -> ObjectNode

pyos.os

Classes and functions related to pyos’ virtual filesystem. This module is modelled on python’s os module and users familiar that will find many of the methods familiar.

class pyos.os.PathLike

An abstract base class for objects representing a pyos path, e.g. pyos.pathlib.PurePath.

pyos.os.chdir(path: Union[str, PathLike])

Change the current working directory to path.

Parameters

path – the path to change to

pyos.os.fspath(file_path: Union[str, PathLike]) → Union[str, bytes]

Return the pyOS representation of the path.

If str is passed in, it is returned unchanged. Otherwise, __fspath__() is called and its value is returned as long as it is a str. In all other cases, TypeError is raised.

pyos.os.getcwd() → str

Return a string representing the current working directory.

pyos.os.isdir(path: Union[str, PathLike]) → bool

Return True if path is an existing directory.

pyos.os.remove(file_path: Union[str, PathLike])

Remove (delete) the file path. If path is a directory, an IsADirectoryError is raised. Use rmdir() to remove directories.

pyos.os.rename(src: Union[str, PathLike], dest: Union[str, PathLike])

Rename the file or directory src to dest. If src is a file and dest is a directory or vice-versa, an IsADirectoryError or a NotADirectoryError will be raised respectively. If both are directories and dest is not empty, an PyOSError is raised. If both are files, dst it will be replaced silently.

pyos.os.unlink(file_path: Union[str, PathLike])

Remove (delete) the file path. This function is semantically identical to remove(); the unlink name is its traditional Unix name. Please see the documentation for remove() for further information.

Parameters

file_path – the path to remove

pyos.psh

class pyos.psh.Log

class pyos.psh.PyosShell(startup_script='', startup_commands: Optional[List[str]] = None, skip_intro=False)

The pyOS shell

An easy but powerful framework for writing line-oriented command interpreters. Extends Python’s cmd package.

Parameters

• completekey – readline name of a completion key, default to Tab

• stdin – alternate input file object, if not specified, sys.stdin is used

• stdout – alternate output file object, if not specified, sys.stdout is used

• persistent_history_file – file path to load a persistent cmd2 command history from

• persistent_history_length – max number of history items to write to the persistent history file

• startup_script – file path to a script to execute at startup

• use_ipython – should the “ipy” command be included for an embedded IPython shell

• allow_cli_args – if True, then cmd2.Cmd.__init__() will process command line arguments as either commands to be run or, if -t or --test are given, transcript files to run. This should be set to False if your application parses its own command line arguments.

• transcript_files – pass a list of transcript files to be run on initialization. This allows running transcript tests when allow_cli_args is False. If allow_cli_args is True this parameter is ignored.

• allow_redirection – If False, prevent output redirection and piping to shell commands. This parameter prevents redirection and piping, but does not alter parsing behavior. A user can still type redirection and piping tokens, and they will be parsed as such but they won’t do anything.

• multiline_commands – list of commands allowed to accept multi-line input

• terminators – list of characters that terminate a command. These are mainly intended for terminating multiline commands, but will also terminate single-line commands. If not supplied, the default is a semicolon. If your app only contains single-line commands and you want terminators to be treated as literals by the parser, then set this to an empty list.

• shortcuts – dictionary containing shortcuts for commands. If not supplied, then defaults to constants.DEFAULT_SHORTCUTS. If you do not want any shortcuts, pass an empty dictionary.

• command_sets – Provide CommandSet instances to load during cmd2 initialization. This allows CommandSets with custom constructor parameters to be loaded. This also allows the a set of CommandSets to be provided when auto_load_commands is set to False

• auto_load_commands – If True, cmd2 will check for all subclasses of CommandSet that are currently loaded by Python and automatically instantiate and register all commands. If False, CommandSets must be manually installed with register_command_set.

do_ipy(_: Namespace) → Optional[bool]

Enter an interactive IPython shell

do_shell(args: Namespace) → None

Execute a command as if at the OS prompt

classmethod execute(*cmd, **kwarg)

Run the passed commands and return

pyos.psh.mod() → str

Get the message of the day string

pyos.psh_lib

Library to help writing psh applications and commands

class pyos.psh_lib.CachingResults(iterator: Iterator, representer: Optional[Callable] = None)

A helper that takes an iterator and wraps it caching the results as a sequence.

Create a caching results sequence. If no representer is supplied the default will be used.

Parameters

• iterator – the iterable to cache results of

• representer – the representer to use, if None the current default will be used.

class pyos.psh_lib.Option(name, call_params=())

An option that can be accepted by a command

new()

Get a new option of this type

class pyos.psh_lib.Options

Container storing options value, using this with separate_opts makes writing tools much easier

class pyos.psh_lib.ResultsDict(results: dict, representer=None)

A custom dictionary representing results from a command

class pyos.psh_lib.ResultsString(result: str, representer=None)

A string that overwrites the __repr__ method

pyos.psh_lib.flag(opt: Union[Option, int], help='')

Decorator for defining an option taken by a command function

pyos.psh_lib.option(opt: Option, help='')

Decorator for defining an option taken by a command function

pyos.psh_lib.parse_fs_entry(*args) → Sequence

Parse objects that can be interpreted as filesystem entries. This can be a path, or a filesystem node.

pyos.psh_lib.prnt(obj, custom_prnt=None)

Pyprnt representer. Use the great pyprnt library to represent the object either as a sequence or a dictionary of the public properties.

See https://github.com/kevink1103/pyprnt for details of pyprnt

pyos.psh_lib.separate_opts(*args) → [<class 'pyos.psh_lib.opts.Options'>, <class 'list'>]

Separate out the options from the other arguments