[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Converting stem.util.system to reStructuredText



commit 3319642a609cd4995724877b90af76cd44067085
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Tue Jun 5 20:02:20 2012 -0700

    Converting stem.util.system to reStructuredText
---
 stem/util/system.py |  126 ++++++++++++++++++++++-----------------------------
 1 files changed, 54 insertions(+), 72 deletions(-)

diff --git a/stem/util/system.py b/stem/util/system.py
index a4ba186..e5583bc 100644
--- a/stem/util/system.py
+++ b/stem/util/system.py
@@ -1,18 +1,22 @@
 """
 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.
 
-is_bsd - checks if we're running on the bsd family of operating systems
-is_available - determines if a command is availabe on this system
-is_running - determines if a given process is running
-get_pid_by_name - gets the pid for a process by the given name
-get_pid_by_port - gets the pid for a process listening to a given port
-get_pid_by_open_file - gets the pid for the process with an open file
-get_cwd - provides the current working directory for a given process
-get_bsd_jail_id - provides the BSD jail id a given process is running within
-expand_path - expands relative paths and ~ entries
-call - runs the given system command and provides back the results
+**Module Overview:**
+
+::
+
+  is_bsd - checks if we're running on the bsd family of operating systems
+  is_available - determines if a command is availabe on this system
+  is_running - determines if a given process is running
+  get_pid_by_name - gets the pid for a process by the given name
+  get_pid_by_port - gets the pid for a process listening to a given port
+  get_pid_by_open_file - gets the pid for the process with an open file
+  get_cwd - provides the current working directory for a given process
+  get_bsd_jail_id - provides the BSD jail id a given process is running within
+  expand_path - expands relative paths and ~ entries
+  call - runs the given system command and provides back the results
 """
 
 import os
@@ -48,8 +52,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"
@@ -59,8 +62,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")
@@ -71,13 +73,10 @@ def is_available(command, cached=True):
   than one command is present (for instance "ls -a | grep foo") then this
   just checks the first.
   
-  Arguments:
-    command (str) - command to search for
-    cached (bool) - makes use of available cached results if True
+  :param str command: command to search for
+  :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]
@@ -101,12 +100,9 @@ def is_running(command):
   """
   Checks for if a process with a given name is running or not.
   
-  Arguments:
-    command (str) - process name to be checked
+  :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
@@ -144,19 +140,19 @@ def get_pid_by_name(process_name):
   """
   Attempts to determine the process id for a running process, using...
   
-  1. pgrep -x <name>
-  2. pidof <name>
-  3. ps -o pid -C <name> (linux)
-     ps axc | egrep " <name>$" (bsd)
-  4. lsof -tc <name>
+  ::
+  
+    1. pgrep -x <name>
+    2. pidof <name>
+    3. ps -o pid -C <name> (linux)
+       ps axc | egrep " <name>$" (bsd)
+    4. lsof -tc <name>
   
   Results with multiple instances of the process are discarded.
   
-  Arguments:
-    process_name (str) - process name for which to fetch the pid
+  :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:
@@ -254,17 +250,17 @@ def get_pid_by_port(port):
   Attempts to determine the process id for a process with the given port,
   using...
   
-  1. netstat -npltu | grep 127.0.0.1:<port>
-  2. sockstat -4l -P tcp -p <port>
-  3. lsof -wnP -iTCP -sTCP:LISTEN | grep ":<port>"
+  ::
+  
+    1. netstat -npltu | grep 127.0.0.1:<port>
+    2. sockstat -4l -P tcp -p <port>
+    3. lsof -wnP -iTCP -sTCP:LISTEN | grep ":<port>"
   
   Most queries limit results to listening TCP connections.
   
-  Arguments:
-    port (int) - port where the process we're looking for is listening
+  :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:
@@ -367,13 +363,13 @@ def get_pid_by_open_file(path):
   Attempts to determine the process id for a process with the given open file,
   using...
   
-  lsof -w <path>
+  ::
+  
+    lsof -w <path>
   
-  Arguments:
-    path (str) - location of the socket file to query against
+  :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:
@@ -401,12 +397,8 @@ def get_cwd(pid):
   """
   Provices the working directory of the given process.
   
-  Arguments:
-    pid (int) - 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
+  :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
   """
   
   # try fetching via the proc contents if it's available
@@ -469,11 +461,9 @@ def get_bsd_jail_id(pid):
   Gets the jail id for a process. These seem to only exist for FreeBSD (this
   style for jails does not exist on Linux, OSX, or OpenBSD).
   
-  Arguments:
-    pid (int) - process id of the jail id to be queried
+  :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:
@@ -504,13 +494,10 @@ def expand_path(path, cwd = None):
   appending a current working directory if the path was relative. This is
   unix-specific and paths never have an ending slash.
   
-  Arguments:
-    path (str) - path to be expanded
-    cwd  (str) - current working directory to expand relative paths with, our
-                 process' if this is None.
+  :param str path: path to be expanded
+  :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 platform.system() == "Windows":
@@ -543,17 +530,12 @@ def call(command, suppress_exc = True):
   results. This is not actually ran in a shell so pipes and other shell syntax
   are not permitted.
   
-  Arguments:
-    command (str)       - command to be issued
-    suppress_exc (bool) - if True then None is returned on failure, otherwise
-                          this raises the exception
+  :param str command: command to be issued
+  :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:



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits