[tor-commits] [stem/master] Converting stem.util.proc to reStructuredText
atagar at torproject.org
atagar at torproject.org
Wed Jun 6 04:30:17 UTC 2012
commit 57e11a1345ed5547424b03fc5f7d9e663c4661ea
Author: Damian Johnson <atagar at torproject.org>
Date: Tue Jun 5 19:53:00 2012 -0700
Converting stem.util.proc to reStructuredText
---
stem/util/proc.py | 140 +++++++++++++++++++++--------------------------------
1 files changed, 56 insertions(+), 84 deletions(-)
diff --git a/stem/util/proc.py b/stem/util/proc.py
index 1d30a05..5ca0520 100644
--- a/stem/util/proc.py
+++ b/stem/util/proc.py
@@ -6,20 +6,21 @@ connections this way cuts the runtime by around 90% verses the alternatives.
These functions may not work on all platforms (only Linux?).
The method for reading these files (and a little code) are borrowed from
-psutil:
-https://code.google.com/p/psutil/
+`psutil <https://code.google.com/p/psutil/>`_, which was written by Jay Loden,
+Dave Daeschler, Giampaolo Rodola' and is under the BSD license.
-which was written by Jay Loden, Dave Daeschler, Giampaolo Rodola' and is under
-the BSD license.
+**Module Overview:**
-is_available - checks if proc utilities can be used on this system
-get_system_start_time - unix timestamp for when the system started
-get_physical_memory - memory available on this system
-get_cwd - provides the current working directory for a process
-get_uid - provides the user id a process is running under
-get_memory_usage - provides the memory usage of a process
-get_stats - queries statistics about a process
-get_connections - provides the connections made by a process
+::
+
+ is_available - checks if proc utilities can be used on this system
+ get_system_start_time - unix timestamp for when the system started
+ get_physical_memory - memory available on this system
+ get_cwd - provides the current working directory for a process
+ get_uid - provides the user id a process is running under
+ get_memory_usage - provides the memory usage of a process
+ get_stats - queries statistics about a process
+ get_connections - provides the connections made by a process
"""
import os
@@ -47,8 +48,7 @@ def is_available():
"""
Checks if proc information is available on this platform.
- Returns:
- bool that's True if proc contents exist on this platform, False otherwise
+ :returns: bool that's True if proc contents exist on this platform, False otherwise
"""
global IS_PROC_AVAILABLE
@@ -74,11 +74,9 @@ def get_system_start_time():
"""
Provides the unix time (seconds since epoch) when the system started.
- Returns:
- float for the unix time of when the system started
+ :returns: float for the unix time of when the system started
- Raises:
- IOError if it can't be determined
+ :raises: IOError if it can't be determined
"""
global SYS_START_TIME
@@ -100,11 +98,9 @@ def get_physical_memory():
"""
Provides the total physical memory on the system in bytes.
- Returns:
- int for the bytes of physical memory this system has
+ :returns: int for the bytes of physical memory this system has
- Raises:
- IOError if it can't be determined
+ :raises: IOError if it can't be determined
"""
global SYS_PHYSICAL_MEMORY
@@ -126,14 +122,11 @@ def get_cwd(pid):
"""
Provides the current working directory for the given process.
- Arguments:
- pid (int) - process id of the process to be queried
+ :param int pid: process id of the process to be queried
- Returns:
- str with the path of the workign direcctory for the process
+ :returns: str with the path of the workign direcctory for the process
- Raises:
- IOError if it can't be determined
+ :raises: IOError if it can't be determined
"""
start_time, parameter = time.time(), "cwd"
@@ -154,14 +147,11 @@ def get_uid(pid):
"""
Provides the user ID the given process is running under.
- Arguments:
- pid (int) - process id of the process to be queried
+ :param int pid: process id of the process to be queried
- Returns:
- int with the user id for the owner of the process
+ :returns: int with the user id for the owner of the process
- Raises:
- IOError if it can't be determined
+ :raises: IOError if it can't be determined
"""
start_time, parameter = time.time(), "uid"
@@ -181,15 +171,11 @@ def get_memory_usage(pid):
"""
Provides the memory usage in bytes for the given process.
- Arguments:
- pid (int) - process id of the process to be queried
+ :param int pid: process id of the process to be queried
- Returns:
- tuple of two ints with the memory usage of the process, of the form:
- (residentSize, virtualSize)
+ :returns: tuple of two ints with the memory usage of the process, of the form ``(residentSize, virtualSize)``
- Raises:
- IOError if it can't be determined
+ :raises: IOError if it can't be determined
"""
# checks if this is the kernel process
@@ -213,20 +199,18 @@ def get_memory_usage(pid):
def get_stats(pid, *stat_types):
"""
Provides process specific information. Options are:
- Stat.COMMAND command name under which the process is running
- Stat.CPU_UTIME total user time spent on the process
- Stat.CPU_STIME total system time spent on the process
- Stat.START_TIME when this process began, in unix time
- Arguments:
- pid (int) - process id of the process to be queried
- stat_types (Stat) - information to be provided back
+ * **Stat.COMMAND** - command name under which the process is running
+ * **Stat.CPU_UTIME** - total user time spent on the process
+ * **Stat.CPU_STIME** - total system time spent on the process
+ * **Stat.START_TIME** - when this process began, in unix time
+
+ :param int pid: process id of the process to be queried
+ :param Stat stat_types: information to be provided back
- Returns:
- tuple with all of the requested statistics as strings
+ :returns: tuple with all of the requested statistics as strings
- Raises:
- IOError if it can't be determined
+ :raises: IOError if it can't be determined
"""
if CLOCK_TICKS is None:
@@ -282,17 +266,11 @@ def get_connections(pid):
similar results to netstat, lsof, sockstat, and other connection resolution
utilities (though the lookup is far quicker).
- Arguments:
- pid (int) - process id of the process to be queried
+ :param int pid: process id of the process to be queried
- Returns:
- A listing of connection tuples of the form:
- [(local_ipAddr1, local_port1, foreign_ipAddr1, foreign_port1), ...]
-
- IP addresses are strings and ports are ints.
+ :returns: A listing of connection tuples of the form ``[(local_ipAddr1, local_port1, foreign_ipAddr1, foreign_port1), ...]`` (IP addresses are strings and ports are ints)
- Raises:
- IOError if it can't be determined
+ :raises: IOError if it can't be determined
"""
if pid == 0: return []
@@ -354,17 +332,16 @@ def get_connections(pid):
def _decode_proc_address_encoding(addr):
"""
Translates an address entry in the /proc/net/* contents to a human readable
- form, for instance:
- "0500000A:0016" -> ("10.0.0.5", 22)
+ form (`reference <http://linuxdevcenter.com/pub/a/linux/2000/11/16/LinuxAdmin.html>`_,
+ for instance:
+
+ ::
- Reference:
- http://linuxdevcenter.com/pub/a/linux/2000/11/16/LinuxAdmin.html
+ "0500000A:0016" -> ("10.0.0.5", 22)
- Arguments:
- addr (str) - proc address entry to be decoded
+ :param str addr: proc address entry to be decoded
- Returns:
- tuple of the form (addr, port), with addr as a string and port an int
+ :returns: tuple of the form ``(addr, port)``, with addr as a string and port an int
"""
ip, port = addr.split(':')
@@ -405,16 +382,13 @@ def _get_lines(file_path, line_prefixes, parameter):
Fetches lines with the given prefixes from a file. This only provides back
the first instance of each prefix.
- Arguments:
- file_path (str) - path of the file to read
- line_prefixes (tuple) - string prefixes of the lines to return
- parameter (str) - description of the proc attribute being fetch
+ :param str file_path: path of the file to read
+ :param tuple line_prefixes: string prefixes of the lines to return
+ :param str parameter: description of the proc attribute being fetch
- Returns:
- mapping of prefixes to the matching line
+ :returns: mapping of prefixes to the matching line
- Raises:
- IOError if unable to read the file or can't find all of the prefixes
+ :raises: IOError if unable to read the file or can't find all of the prefixes
"""
try:
@@ -449,10 +423,9 @@ def _log_runtime(parameter, proc_location, start_time):
"""
Logs a message indicating a successful proc query.
- Arguments:
- parameter (str) - description of the proc attribute being fetch
- proc_location (str) - proc files we were querying
- start_time (int) - unix time for when this query was started
+ :param str parameter: description of the proc attribute being fetch
+ :param str proc_location: proc files we were querying
+ :param int start_time: unix time for when this query was started
"""
runtime = time.time() - start_time
@@ -462,9 +435,8 @@ def _log_failure(parameter, exc):
"""
Logs a message indicating that the proc query failed.
- Arguments:
- parameter (str) - description of the proc attribute being fetch
- exc (Exception) - exception that we're raising
+ :param str parameter: description of the proc attribute being fetch
+ :param Exception exc: exception that we're raising
"""
log.debug("proc call failed (%s): %s" % (parameter, exc))
More information about the tor-commits
mailing list