[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[tor-commits] [stem/master] Revised API docs for stem.util.system
commit d2a3acff92383ea95602acd4382cf648b5693da4
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
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:
_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits