debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-25 20:38:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

rename module to just 'notmuch'

Browse source 
So you need to do e.g. 'from notmuch import Database' rather than the
previous from cnotmuch.notmuch import Database.

Alse recreate our fake python 'notmuch' binary in the docs directory for now

--HG--
rename : notmuch/notmuch.py => notmuch/__init__.py
This commit is contained in:
Sebastian Spaeth 2010-04-19 21:21:38 +02:00
parent 3c6321cdb2
commit d0b00bc4b1
3 changed files with 708 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

647
docs/notmuch Executable file
View file

@ -0,0 +1,647 @@
#!/usr/bin/env python
"""This is a notmuch implementation in python.
It's goal is to allow running the test suite on the cnotmuch python bindings.
This "binary" honors the NOTMUCH_CONFIG environmen variable for reading a user's
notmuch configuration (e.g. the database path).
(c) 2010 by Sebastian Spaeth <Sebastian@SSpaeth.de>
Jesse Rosenthal <jrosenthal@jhu.edu>
This code is licensed under the GNU GPL v3+.
"""
import sys
import os
import re
import stat
import email
from notmuch import Database, Query, NotmuchError, STATUS
from ConfigParser import SafeConfigParser
from cStringIO import StringIO
PREFIX = re.compile('(\w+):(.*$)')
HELPTEXT = """The notmuch mail system.
Usage: notmuch <command> [args...]
Where <command> and [args...] are as follows:
setup Interactively setup notmuch for first use.
new [--verbose]
Find and import new messages to the notmuch database.
search [options...] <search-terms> [...]
Search for messages matching the given search terms.
show <search-terms> [...]
Show all messages matching the search terms.
count <search-terms> [...]
Count messages matching the search terms.
reply [options...] <search-terms> [...]
Construct a reply template for a set of messages.
tag +<tag>|-<tag> [...] [--] <search-terms> [...]
Add/remove tags for all messages matching the search terms.
dump [<filename>]
Create a plain-text dump of the tags for each message.
restore <filename>
Restore the tags from the given dump file (see 'dump').
search-tags [<search-terms> [...] ]
List all tags found in the database or matching messages.
help [<command>]
This message, or more detailed help for the named command.
Use "notmuch help <command>" for more details on each command.
And "notmuch help search-terms" for the common search-terms syntax.
"""
USAGE = """Notmuch is configured and appears to have a database. Excellent!
At this point you can start exploring the functionality of notmuch by
using commands such as:
notmuch search tag:inbox
notmuch search to:"%(fullname)s"
notmuch search from:"%(mailaddress)s"
notmuch search subject:"my favorite things"
See "notmuch help search" for more details.
You can also use "notmuch show" with any of the thread IDs resulting
from a search. Finally, you may want to explore using a more sophisticated
interface to notmuch such as the emacs interface implemented in notmuch.el
or any other interface described at http://notmuchmail.org
And don't forget to run "notmuch new" whenever new mail arrives.
Have fun, and may your inbox never have much mail.
"""
#-------------------------------------------------------------------------
def quote_query_line(argv):
# mangle arguments wrapping terms with spaces in quotes
for (num, item) in enumerate(argv):
if item.find(' ') >= 0:
# if we use prefix:termWithSpaces, put quotes around term
match = PREFIX.match(item)
if match:
argv[num] = '%s:"%s"' %(match.group(1), match.group(2))
else:
argv[num] = '"%s"' % item
return ' '.join(argv)
#-------------------------------------------------------------------------
class Notmuch(object):
def __init__(self, configpath="~/.notmuch-config)"):
self._config = None
self._configpath = os.getenv('NOTMUCH_CONFIG',
os.path.expanduser(configpath))
def cmd_usage(self):
"""Print the usage text and exits"""
data={}
names = self.get_user_email_addresses()
data['fullname'] = names[0] if names[0] else 'My Name'
data['mailaddress'] = names[1] if names[1] else 'My@email.address'
print USAGE % data
def cmd_new(self):
"""Run 'notmuch new'"""
#get the database directory
db = Database(mode=Database.MODE.READ_WRITE)
path = db.get_path()
print self._add_new_files_recursively(path, db)
def cmd_help(self, subcmd=None):
"""Print help text for 'notmuch help'"""
if len(subcmd) > 1:
print "Help for specific commands not implemented"
return
print HELPTEXT
def _get_user_notmuch_config(self):
"""Returns the ConfigParser of the user's notmuch-config"""
# return the cached config parser if we read it already
if self._config:
return self._config
config = SafeConfigParser()
config.read(self._configpath)
self._config = config
return config
def _add_new_files_recursively(self, path, db):
""":returns: (added, moved, removed)"""
print "Enter add new files with path %s" % path
try:
#get the Directory() object for this path
db_dir = db.get_directory(path)
added = moved = removed = 0
except NotmuchError:
# Occurs if we have wrong absolute paths in the db, for example
return (0,0,0)
# for folder in subdirs:
# TODO, retrieve dir mtime here and store it later
# as long as Filenames() does not allow multiple iteration, we need to
# use this kludgy way to get a sorted list of filenames
# db_files is a list of subdirectories and filenames in this folder
db_files = set()
db_folders = set()
for subdir in db_dir.get_child_directories():
db_folders.add(subdir)
# file is a keyword (remove this ;))
for mail in db_dir.get_child_files():
db_files.add(mail)
fs_files = set(os.listdir(db_dir.path))
# list of files (and folders) on the fs, but not the db
for fs_file in ((fs_files - db_files) - db_folders):
absfile = os.path.normpath(os.path.join(db_dir.path, fs_file))
statinfo = os.stat(absfile)
if stat.S_ISDIR(statinfo.st_mode):
# This is a directory
if fs_file in ['.notmuch','tmp','.']:
continue
print "%s %s" % (fs_file, db_folders)
print "Directory not in db yet. Descending into %s" % absfile
new = self._add_new_files_recursively(absfile, db)
added += new[0]
moved += new[1]
removed += new[2]
elif stat.S_ISLNK(statinfo.st_mode):
print ("%s is a symbolic link (%d). FIXME!!!" %
(absfile, statinfo.st_mode))
exit(1)
else:
# This is a regular file, not in the db yet. Add it.
print "This file needs to be added %s" % (absfile)
(msg, status) = db.add_message(absfile)
# We increases 'added', even on dupe messages. If it is a moved
# message, we will deduct it later and increase 'moved' instead
added += 1
if status == STATUS.DUPLICATE_MESSAGE_ID:
print "Added msg was in the db"
else:
print "New message."
# Finally a list of files (not folders) in the database,
# but not the filesystem
for db_file in (db_files - fs_files):
absfile = os.path.normpath(os.path.join(db_dir.path, db_file))
# remove a mail message from the db
print ("%s is not on the fs anymore. Delete" % absfile)
status = db.remove_message(absfile)
if status == STATUS.SUCCESS:
# we just deleted the last reference, so this was a remove
removed += 1
sys.stderr.write("SUCCESS %d %s %s.\n" %
(status, STATUS.status2str(status), absfile))
elif status == STATUS.DUPLICATE_MESSAGE_ID:
# The filename exists already somewhere else, so this is a move
moved += 1
added -= 1
sys.stderr.write("DUPE %d %s %s.\n" %
(status, STATUS.status2str(status), absfile))
else:
# This should not occur
sys.stderr.write("This should not occur %d %s %s.\n" %
(status, STATUS.status2str(status), absfile))
# list of folders in the filesystem. Just descend into dirs
for fs_file in fs_files:
absfile = os.path.normpath(os.path.join(db_dir.path, fs_file))
if os.path.isdir(absfile):
# This is a directory. Remove it from the db_folder list.
# All remaining db_folders at the end will be not present
# on the file system.
db_folders.remove(fs_file)
if fs_file in ['.notmuch','tmp','.']:
continue
new = self._add_new_files_recursively(absfile, db)
added += new[0]
moved += new[0]
removed += new[0]
# we are not interested in anything but directories here
#TODO: All remaining elements of db_folders are not in the filesystem
#delete those
return added, moved, removed
#Read the mtime of a directory from the filesystem
#
#* Call :meth:`Database.add_message` for all mail files in
# the directory
#* Call notmuch_directory_set_mtime with the mtime read from the
# filesystem. Then, when wanting to check for updates to the
# directory in the future, the client can call :meth:`get_mtime`
# and know that it only needs to add files if the mtime of the
# directory and files are newer than the stored timestamp.
def get_user_email_addresses(self):
""" Reads a user's notmuch config and returns his email addresses as
list (name, primary_address, other_address1,...)"""
#read the config file
config = self._get_user_notmuch_config()
conf = {'name': '', 'primary_email': ''}
for entry in conf:
if config.has_option('user', entry):
conf[entry] = config.get('user', entry)
if config.has_option('user','other_email'):
other = config.get('user','other_email')
other = [mail.strip() for mail in other.split(';') if mail]
else:
other = []
# for being compatible. It would be nicer to return a dict.
return conf.keys() + other
def quote_msg_body(self, oldbody ,date, from_address):
"""Transform a mail body into a quoted text,
starting with On foo, bar wrote:
:param body: a str with a mail body
:returns: The new payload of the email.message()
"""
# we get handed a string, wrap it in a file-like object
oldbody = StringIO(oldbody)
newbody = StringIO()
newbody.write("On %s, %s wrote:\n" % (date, from_address))
for line in oldbody:
newbody.write("> " + line)
return newbody.getvalue()
def format_reply(self, msgs):
"""Gets handed Messages() and displays the reply to them
This is pretty ugly and hacky. It tries to mimic the "real"
notmuch output as much as it can to pass the test suite. It
could deserve a healthy bit of love. It is also buggy because
it returns after the first message it has handled."""
for msg in msgs:
f = open(msg.get_filename(), "r")
reply = email.message_from_file(f)
# handle the easy non-multipart case:
if not reply.is_multipart():
reply.set_payload(self.quote_msg_body(reply.get_payload(),
reply['date'], reply['from']))
else:
# handle the tricky multipart case
deleted = ""
"""A string describing which nontext attachements
that have been deleted"""
delpayloads = []
"""A list of payload indices to be deleted"""
payloads = reply.get_payload()
for (num, part) in enumerate(payloads):
mime_main = part.get_content_maintype()
if mime_main not in ['multipart', 'message', 'text']:
deleted += "Non-text part: %s\n" % (part.get_content_type())
payloads[num].set_payload("Non-text part: %s" %
(part.get_content_type()))
payloads[num].set_type('text/plain')
delpayloads.append(num)
elif mime_main == 'text':
payloads[num].set_payload(self.quote_msg_body(
payloads[num].get_payload(),
reply['date'], reply['from']))
else:
# TODO handle deeply nested multipart messages
sys.stderr.write ("FIXME: Ignoring multipart part. Handle me\n")
# Delete those payloads that we don't need anymore
for item in reversed(sorted(delpayloads)):
del payloads[item]
# Back to single- and multipart handling
my_addresses = self.get_user_email_addresses()
used_address = None
# filter our email addresses from all to: cc: and bcc: fields
# if we find one of "my" addresses being used,
# it is stored in used_address
for header in ['To', 'CC', 'Bcc']:
if not header in reply:
#only handle fields that exist
continue
addresses = email.utils.getaddresses(reply.get_all(header, []))
purged_addr = []
for (name, mail) in addresses:
if mail in my_addresses[1:]:
used_address = email.utils.formataddr(
(my_addresses[0], mail))
else:
purged_addr.append(email.utils.formataddr((name, mail)))
if purged_addr:
reply.replace_header(header, ", ".join(purged_addr))
else:
# we deleted all addresses, delete the header
del reply[header]
# Use our primary email address to the From
# (save original from line, we still need it)
new_to = reply['From']
if used_address:
reply['From'] = used_address
else:
email.utils.formataddr((my_addresses[0], my_addresses[1]))
reply['Subject'] = 'Re: ' + reply['Subject']
# Calculate our new To: field
# add all remaining original 'To' addresses
if 'To' in reply:
new_to += ", " + reply['To']
reply.add_header('To', new_to)
# Add our primary email address to the BCC
new_bcc = my_addresses[1]
if 'Bcc' in reply:
new_bcc += ', ' + reply['Bcc']
reply['Bcc'] = new_bcc
# Set replies 'In-Reply-To' header to original's Message-ID
if 'Message-ID' in reply:
reply['In-Reply-To'] = reply['Message-ID']
#Add original's Message-ID to replies 'References' header.
if 'References' in reply:
reply['References'] = ' '.join([reply['References'], reply['Message-ID']])
else:
reply['References'] = reply['Message-ID']
# Delete the original Message-ID.
del(reply['Message-ID'])
# filter all existing headers but a few and delete them from 'reply'
delheaders = filter(lambda x: x not in ['From', 'To', 'Subject', 'CC',
'Bcc', 'In-Reply-To',
'References', 'Content-Type'],
reply.keys())
map(reply.__delitem__, delheaders)
# TODO: OUCH, we return after the first msg we have handled rather than
# handle all of them
# return resulting message without Unixfrom
return reply.as_string(False)
def main():
# Handle command line options
#------------------------------------
# No option given, print USAGE and exit
if len(sys.argv) == 1:
Notmuch().cmd_usage()
#------------------------------------
elif sys.argv[1] == 'setup':
"""Interactively setup notmuch for first use."""
exit("Not implemented.")
#-------------------------------------
elif sys.argv[1] == 'new':
"""Check for new and removed messages."""
Notmuch().cmd_new()
#-------------------------------------
elif sys.argv[1] == 'help':
"""Print the help text"""
Notmuch().cmd_help(sys.argv[1:])
#-------------------------------------
elif sys.argv[1] == 'part':
part()
#-------------------------------------
elif sys.argv[1] == 'search':
search()
#-------------------------------------
elif sys.argv[1] == 'show':
show()
#-------------------------------------
elif sys.argv[1] == 'reply':
db = Database()
if len(sys.argv) == 2:
# no search term. abort
exit("Error: notmuch reply requires at least one search term.")
# mangle arguments wrapping terms with spaces in quotes
querystr = quote_query_line(sys.argv[2:])
msgs = Query(db, querystr).search_messages()
print Notmuch().format_reply(msgs)
#-------------------------------------
elif sys.argv[1] == 'count':
if len(sys.argv) == 2:
# no further search term, count all
querystr = ''
else:
# mangle arguments wrapping terms with spaces in quotes
querystr = quote_query_line(sys.argv[2:])
print Database().create_query(querystr).count_messages()
#-------------------------------------
elif sys.argv[1] == 'tag':
# build lists of tags to be added and removed
add = []
remove = []
while not sys.argv[2] == '--' and \
(sys.argv[2].startswith('+') or sys.argv[2].startswith('-')):
if sys.argv[2].startswith('+'):
# append to add list without initial +
add.append(sys.argv.pop(2)[1:])
else:
# append to remove list without initial -
remove.append(sys.argv.pop(2)[1:])
# skip eventual '--'
if sys.argv[2] == '--': sys.argv.pop(2)
# the rest is search terms
querystr = quote_query_line(sys.argv[2:])
db = Database(mode=Database.MODE.READ_WRITE)
msgs = Query(db, querystr).search_messages()
for msg in msgs:
# actually add and remove all tags
map(msg.add_tag, add)
map(msg.remove_tag, remove)
#-------------------------------------
elif sys.argv[1] == 'search-tags':
if len(sys.argv) == 2:
# no further search term
print "\n".join(Database().get_all_tags())
else:
# mangle arguments wrapping terms with spaces in quotes
querystr = quote_query_line(sys.argv[2:])
db = Database()
msgs = Query(db, querystr).search_messages()
print "\n".join([t for t in msgs.collect_tags()])
#-------------------------------------
elif sys.argv[1] == 'dump':
# TODO: implement "dump <filename>"
if len(sys.argv) == 2:
f = sys.stdout
else:
f = open(sys.argv[2], "w")
db = Database()
query = Query(db, '')
query.set_sort(Query.SORT.MESSAGE_ID)
msgs = query.search_messages()
for msg in msgs:
f.write("%s (%s)\n" % (msg.get_message_id(), msg.get_tags()))
#-------------------------------------
elif sys.argv[1] == 'restore':
if len(sys.argv) == 2:
print("No filename given. Reading dump from stdin.")
f = sys.stdin
else:
f = open(sys.argv[2], "r")
# split the msg id and the tags
MSGID_TAGS = re.compile("(\S+)\s\((.*)\)$")
db = Database(mode=Database.MODE.READ_WRITE)
#read each line of the dump file
for line in f:
msgs = MSGID_TAGS.match(line)
if not msgs:
sys.stderr.write("Warning: Ignoring invalid input line: %s" %
line)
continue
# split line in components and fetch message
msg_id = msgs.group(1)
new_tags = set(msgs.group(2).split())
msg = db.find_message(msg_id)
if msg == None:
sys.stderr.write(
"Warning: Cannot apply tags to missing message: %s\n" % msg_id)
continue
# do nothing if the old set of tags is the same as the new one
old_tags = set(msg.get_tags())
if old_tags == new_tags: continue
# set the new tags
msg.freeze()
# only remove tags if the new ones are not a superset anyway
if not (new_tags > old_tags): msg.remove_all_tags()
for tag in new_tags: msg.add_tag(tag)
msg.thaw()
#-------------------------------------
else:
# unknown command
exit("Error: Unknown command '%s' (see \"notmuch help\")" % sys.argv[1])
def part():
db = Database()
query_string = ''
part_num = 0
first_search_term = 0
for (num, arg) in enumerate(sys.argv[1:]):
if arg.startswith('--part='):
part_num_str = arg.split("=")[1]
try:
part_num = int(part_num_str)
except ValueError:
# just emulating behavior
exit(1)
elif not arg.startswith('--'):
# save the position of the first sys.argv
# that is a search term
first_search_term = num + 1
if first_search_term:
# mangle arguments wrapping terms with spaces in quotes
querystr = quote_query_line(sys.argv[first_search_term:])
qry = Query(db,querystr)
msgs = [msg for msg in qry.search_messages()]
if not msgs:
sys.exit(1)
elif len(msgs) > 1:
raise Exception("search term did not match precisely one message")
else:
msg = msgs[0]
print msg.get_part(part_num)
def search():
db = Database()
query_string = ''
sort_order = "newest-first"
first_search_term = 0
for (num, arg) in enumerate(sys.argv[1:]):
if arg.startswith('--sort='):
sort_order=arg.split("=")[1]
if not sort_order in ("oldest-first", "newest-first"):
raise Exception("unknown sort order")
elif not arg.startswith('--'):
# save the position of the first sys.argv that is a search term
first_search_term = num + 1
if first_search_term:
# mangle arguments wrapping terms with spaces in quotes
querystr = quote_query_line(sys.argv[first_search_term:])
qry = Query(db, querystr)
if sort_order == "oldest-first":
qry.set_sort(Query.SORT.OLDEST_FIRST)
else:
qry.set_sort(Query.SORT.NEWEST_FIRST)
threads = qry.search_threads()
for thread in threads:
print thread
def show():
entire_thread = False
db = Database()
out_format = "text"
querystr = ''
first_search_term = None
# ugly homegrown option parsing
# TODO: use OptionParser
for (num, arg) in enumerate(sys.argv[1:]):
if arg == '--entire-thread':
entire_thread = True
elif arg.startswith("--format="):
out_format = arg.split("=")[1]
if out_format == 'json':
# for compatibility use --entire-thread for json
entire_thread = True
if not out_format in ("json", "text"):
raise Exception("unknown format")
elif not arg.startswith('--'):
# save the position of the first sys.argv that is a search term
first_search_term = num + 1
if first_search_term:
# mangle arguments wrapping terms with spaces in quotes
querystr = quote_query_line(sys.argv[first_search_term:])
threads = Query(db, querystr).search_threads()
first_toplevel = True
if out_format == "json":
sys.stdout.write("[")
for thread in threads:
msgs = thread.get_toplevel_messages()
if not first_toplevel:
if out_format == "json":
sys.stdout.write(", ")
first_toplevel = False
msgs.print_messages(out_format, 0, entire_thread)
if out_format == "json":
sys.stdout.write("]")
sys.stdout.write("\n")
if __name__ == '__main__':
main()

61
notmuch/__init__.py
View file

@ -0,0 +1,61 @@
"""The :mod:`notmuch` module provides most of the functionality that a user is likely to need.
.. note:: The underlying notmuch library is build on a hierarchical
memory allocator called talloc. All objects derive from a
top-level :class:`Database` object.
This means that as soon as an object is deleted, all underlying
derived objects such as Queries, Messages, Message, and Tags will
be freed by the underlying library as well. Accessing these
objects will then lead to segfaults and other unexpected behavior.
We implement reference counting, so that parent objects can be
automatically freed when they are not needed anymore. For
example::
db = Database('path',create=True)
msgs = Query(db,'from:myself').search_messages()
This returns a :class:`Messages` which internally contains a
reference to its parent :class:`Query` object. Otherwise the
Query() would be immediately freed, taking our *msgs* down with
it.
In this case, the above Query() object will be automatically freed
whenever we delete all derived objects, ie in our case:
`del(msgs)` would also delete the parent Query. It would not
delete the parent Database() though, as that is still referenced
from the variable *db* in which it is stored.
Pretty much the same is valid for all other objects in the
hierarchy, such as :class:`Query`, :class:`Messages`,
:class:`Message`, and :class:`Tags`.
"""
"""
This file is part of notmuch.
Notmuch is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.
Notmuch is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with notmuch. If not, see <http://www.gnu.org/licenses/>.
Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
"""
from database import Database, Query
from message import Messages, Message
from thread import Threads, Thread
from tag import Tags
from cnotmuch.globals import nmlib, STATUS, NotmuchError
__LICENSE__="GPL v3+"
__VERSION__='0.2.2'
__AUTHOR__ ='Sebastian Spaeth <Sebastian@SSpaeth.de>'

61
notmuch/notmuch.py
View file

@ -1,61 +0,0 @@
"""The :mod:`notmuch` module provides most of the functionality that a user is likely to need.
.. note:: The underlying notmuch library is build on a hierarchical
memory allocator called talloc. All objects derive from a
top-level :class:`Database` object.
This means that as soon as an object is deleted, all underlying
derived objects such as Queries, Messages, Message, and Tags will
be freed by the underlying library as well. Accessing these
objects will then lead to segfaults and other unexpected behavior.
We implement reference counting, so that parent objects can be
automatically freed when they are not needed anymore. For
example::
db = Database('path',create=True)
msgs = Query(db,'from:myself').search_messages()
This returns a :class:`Messages` which internally contains a
reference to its parent :class:`Query` object. Otherwise the
Query() would be immediately freed, taking our *msgs* down with
it.
In this case, the above Query() object will be automatically freed
whenever we delete all derived objects, ie in our case:
`del(msgs)` would also delete the parent Query. It would not
delete the parent Database() though, as that is still referenced
from the variable *db* in which it is stored.
Pretty much the same is valid for all other objects in the
hierarchy, such as :class:`Query`, :class:`Messages`,
:class:`Message`, and :class:`Tags`.
"""
"""
This file is part of notmuch.
Notmuch is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.
Notmuch is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with notmuch. If not, see <http://www.gnu.org/licenses/>.
Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
"""
from database import Database, Query
from message import Messages, Message
from thread import Threads, Thread
from tag import Tags
from cnotmuch.globals import nmlib, STATUS, NotmuchError
__LICENSE__="GPL v3+"
__VERSION__='0.2.2'
__AUTHOR__ ='Sebastian Spaeth <Sebastian@SSpaeth.de>'