[tor-commits] [stem/master] Converting stem.util.system to reStructuredText
atagar at torproject.org
atagar at torproject.org
Wed Jun 6 04:30:17 UTC 2012
commit 3319642a609cd4995724877b90af76cd44067085
Author: Damian Johnson <atagar at torproject.org>
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:
More information about the tor-commits
mailing list