commit d2a3acff92383ea95602acd4382cf648b5693da4 Author: Damian Johnson atagar@torproject.org Date: Sat Oct 27 15:42:02 2012 -0700
Revised API docs for stem.util.system --- docs/api.rst | 1 + docs/contents.rst | 1 + docs/util/system.rst | 5 +++++ stem/util/system.py | 40 +++++++++++++++++++++++----------------- 4 files changed, 30 insertions(+), 17 deletions(-)
diff --git a/docs/api.rst b/docs/api.rst index 0078810..9a9cc0d 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -30,4 +30,5 @@ Utilities * `stem.util.log <util/log.html>`_ - Logging utilities. * `stem.util.proc <util/proc.html>`_ - Tools to read a process' proc contents. * `stem.util.str_tools <util/str_tools.html>`_ - String utilities. +* `stem.util.system <util/system.html>`_ - Tools related to the local system.
diff --git a/docs/contents.rst b/docs/contents.rst index 5d900c1..c2eb3a5 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -26,4 +26,5 @@ Contents util/log util/proc util/str_tools + util/system
diff --git a/docs/util/system.rst b/docs/util/system.rst new file mode 100644 index 0000000..95cabb5 --- /dev/null +++ b/docs/util/system.rst @@ -0,0 +1,5 @@ +System Utilities +================ + +.. automodule:: stem.util.system + diff --git a/stem/util/system.py b/stem/util/system.py index 798f5ff..6c2be06 100644 --- a/stem/util/system.py +++ b/stem/util/system.py @@ -1,7 +1,7 @@ """ Helper functions for working with the underlying system. These are mostly os dependent, only working on linux, osx, and bsd. In almost all cases they're -best-effort, providing None if the lookup fails. +best-effort, providing **None** if the lookup fails.
**Module Overview:**
@@ -54,7 +54,7 @@ def is_windows(): """ Checks if we are running on Windows.
- :returns: bool to indicate if we're on Windows + :returns: **bool** to indicate if we're on Windows """
return platform.system() == "Windows" @@ -63,7 +63,7 @@ def is_mac(): """ Checks if we are running on Mac OSX.
- :returns: bool to indicate if we're on a Mac + :returns: **bool** to indicate if we're on a Mac """
return platform.system() == "Darwin" @@ -73,7 +73,7 @@ def is_bsd(): Checks if we are within the BSD family of operating systems. This presently recognizes Macs, FreeBSD, and OpenBSD but may be expanded later.
- :returns: bool to indicate if we're on a BSD OS + :returns: **bool** to indicate if we're on a BSD OS """
return platform.system() in ("Darwin", "FreeBSD", "OpenBSD") @@ -88,9 +88,10 @@ def is_available(command, cached=True): PATH so this lookup will fail for them.
:param str command: command to search for - :param bool cached: makes use of available cached results if True + :param bool cached: makes use of available cached results if **True**
- :returns: True if an executable we can use by that name exists in the PATH, False otherwise + :returns: **True** if an executable we can use by that name exists in the + PATH, **False** otherwise """
if " " in command: command = command.split(" ")[0] @@ -116,7 +117,8 @@ def is_running(command):
:param str command: process name to be checked
- :returns: True if the process is running, False if it's not among ps results, and None if ps can't be queried + :returns: **True** if the process is running, **False** if it's not among ps + results, and **None** if ps can't be queried """
# Linux and the BSD families have different variants of ps. Guess based on @@ -166,7 +168,7 @@ def get_pid_by_name(process_name):
:param str process_name: process name for which to fetch the pid
- :returns: int with the process id, None if it can't be determined + :returns: **int** with the process id, **None** if it can't be determined """
# attempts to resolve using pgrep, failing if: @@ -275,7 +277,7 @@ def get_pid_by_port(port):
:param int port: port where the process we're looking for is listening
- :returns: int with the process id, None if it can't be determined + :returns: **int** with the process id, **None** if it can't be determined """
# attempts to resolve using netstat, failing if: @@ -387,7 +389,7 @@ def get_pid_by_open_file(path):
:param str path: location of the socket file to query against
- :returns: int with the process id, None if it can't be determined + :returns: **int** with the process id, **None** if it can't be determined """
# resolves using lsof which works on both Linux and BSD, only failing if: @@ -416,7 +418,8 @@ def get_cwd(pid): Provices the working directory of the given process.
:param int pid: process id of the process to be queried - :returns: str with the absolute path for the process' present working directory, None if it can't be determined + :returns: **str** with the absolute path for the process' present working + directory, **None** if it can't be determined """
# try fetching via the proc contents if it's available @@ -481,7 +484,7 @@ def get_bsd_jail_id(pid):
:param int pid: process id of the jail id to be queried
- :returns: int for the jail id, zero if this can't be determined + :returns: **int** for the jail id, zero if this can't be determined """
# Output when called from a FreeBSD jail or when Tor isn't jailed: @@ -513,9 +516,10 @@ def expand_path(path, cwd = None): unix-specific and paths never have an ending slash.
:param str path: path to be expanded - :param str cwd: current working directory to expand relative paths with, our process' if this is None + :param str cwd: current working directory to expand relative paths with, our + process' if this is **None**
- :returns: str of the path expanded to be an absolute path + :returns: **str** of the path expanded to be an absolute path """
if is_windows(): @@ -554,11 +558,13 @@ def call(command, suppress_exc = True): are not permitted.
:param str command: command to be issued - :param bool suppress_exc: if True then None is returned on failure, otherwise this raises the exception + :param bool suppress_exc: if **True** then **None** is returned on failure, + otherwise this raises the exception
- :returns: list with the lines of output from the command, None in case of failure if suppress_exc is True + :returns: **list** with the lines of output from the command, **None** in + case of failure if suppress_exc is **True**
- :raises: OSError if this fails and suppress_exc is False + :raises: **OSError** if this fails and suppress_exc is **False** """
try: