[tor-commits] [stem/master] Revised API docs for stem.util.system

[atagar at torproject.org]

commit d2a3acff92383ea95602acd4382cf648b5693da4
Author: Damian Johnson <atagar at 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: