aboutsummaryrefslogtreecommitdiffstats
path: root/libbe/ui
diff options
context:
space:
mode:
authorW. Trevor King <wking@drexel.edu>2010-02-08 17:05:12 -0500
committerW. Trevor King <wking@drexel.edu>2010-02-08 17:05:12 -0500
commit37d61e9ecd8768b25ba4aff3c657ccc56f086dd0 (patch)
tree31214efb9536a319473277610534cf2f37215ed1 /libbe/ui
parent3f27c5c3bbc1ecd00db51c4894a9bf9651ae4fbb (diff)
parent960565a8cc80f98d0a8bfa77029fbc78692ea1a1 (diff)
downloadbugseverywhere-37d61e9ecd8768b25ba4aff3c657ccc56f086dd0.tar.gz
Merged initial Sphinx documentation structure.
There's still a long way to go in this direction, but the basic framework is now in place. Toss in numpydoc-style docstrings http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines when you have time, and things will gradually improve over time. I also punted our user ID creation/parsing in libbe.ui.util.user to the email module. This way IDs are handled in an RFC-compliant way (less suprising for users) and by someone else (less work for us :).
Diffstat (limited to 'libbe/ui')
-rw-r--r--libbe/ui/util/user.py89
1 files changed, 60 insertions, 29 deletions
diff --git a/libbe/ui/util/user.py b/libbe/ui/util/user.py
index 98f16a6..460a1dd 100644
--- a/libbe/ui/util/user.py
+++ b/libbe/ui/util/user.py
@@ -14,13 +14,21 @@
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-"""
-Tools for getting, setting, creating, and parsing the user's id. For
-example,
- 'John Doe <jdoe@example.com>'
-Note that the Arch VCS backend *enforces* ids with this format.
+"""Tools for getting, setting, creating, and parsing the user's ID.
+
+IDs will look like 'John Doe <jdoe@example.com>'. Note that the
+:mod:`libbe.storage.vcs.arch <Arch VCS backend>` *enforces* IDs with
+this format.
+
+Do not confuse the user IDs discussed in this module, which refer to
+humans, with the "user IDs" discussed in :mod:`libbe.util.id`, which
+are human-readable tags refering to objects.
"""
+try:
+ from email.utils import formataddr, parseaddr
+except ImportErrror: # adjust to old python < 2.5
+ from email.Utils import formataddr, parseaddr
import os
import re
from socket import gethostname
@@ -29,6 +37,8 @@ import libbe
import libbe.storage.util.config
def get_fallback_username():
+ """Return a username extracted from environmental variables.
+ """
name = None
for env in ["LOGNAME", "USERNAME"]:
if os.environ.has_key(env):
@@ -38,52 +48,69 @@ def get_fallback_username():
return name
def get_fallback_email():
+ """Return an email address extracted from environmental variables.
+ """
hostname = gethostname()
name = get_fallback_username()
return "%s@%s" % (name, hostname)
def create_user_id(name, email=None):
- """
+ """Create a user ID string from given `name` and `email` strings.
+
+ Examples
+ --------
+
>>> create_user_id("John Doe", "jdoe@example.com")
'John Doe <jdoe@example.com>'
>>> create_user_id("John Doe")
'John Doe'
+
+ See Also
+ --------
+ parse_user_id : inverse
"""
assert len(name) > 0
if email == None or len(email) == 0:
return name
else:
- return "%s <%s>" % (name, email)
+ return formataddr((name, email))
def parse_user_id(value):
- """
+ """Parse a user ID string into `name` and `email` strings.
+
+ Examples
+ --------
+
>>> parse_user_id("John Doe <jdoe@example.com>")
('John Doe', 'jdoe@example.com')
>>> parse_user_id("John Doe")
('John Doe', None)
- >>> try:
- ... parse_user_id("John Doe <jdoe@example.com><what?>")
- ... except AssertionError:
- ... print "Invalid match"
- Invalid match
+ >>> parse_user_id("John Doe <jdoe@example.com><what?>")
+ ('John Doe', 'jdoe@example.com')
+
+ See Also
+ --------
+ create_user_id : inverse
"""
- emailexp = re.compile("(.*) <([^>]*)>(.*)")
- match = emailexp.search(value)
- if match == None:
- email = None
- name = value
- else:
- assert len(match.groups()) == 3
- assert match.groups()[2] == "", match.groups()
- email = match.groups()[1]
- name = match.groups()[0]
- assert name != None
- assert len(name) > 0
- return (name, email)
+ if '<' not in value:
+ return (value, None)
+ return parseaddr(value)
def get_user_id(storage=None):
- """
- Sometimes the storage will also keep track of the user id (e.g. most VCSs).
+ """Return a user ID, checking a list of possible sources.
+
+ The source order is:
+
+ 1. Global BE configuration.
+ 2. `storage.get_user_id`, if that function is defined.
+ 3. :func:`get_fallback_username` and :func:`get_fallback_email`.
+
+ Notes
+ -----
+ Sometimes the storage will keep track of the user ID (e.g. most
+ VCSs, see :meth:`libbe.storage.vcs.base.VCS.get_user_id`). If so,
+ we prefer that ID to the fallback, since the user has likely
+ configured it directly.
"""
user = libbe.storage.util.config.get_val('user')
if user != None:
@@ -98,6 +125,10 @@ def get_user_id(storage=None):
return user
def set_user_id(user_id):
- """
+ """Set the user ID in a user's BE configuration.
+
+ See Also
+ --------
+ libbe.storage.util.config.set_val
"""
user = libbe.storage.util.config.set_val('user', user_id)