~jaap.karssenberg/zim/pyzim-0.43-backports

# -*- coding: utf-8 -*-

# Copyright 2008 Jaap Karssenberg <pardus@cpan.org>

'''

This package contains the main Notebook class and related classes.

This package defines the public interface towards the

noetbook.  As a backend it uses one of more packages from

the 'stores' namespace.

'''

from __future__ import with_statement

import os

import weakref

import logging

import gobject

import zim.fs

from zim.fs import *

from zim.errors import Error, SignalExceptionContext, SignalRaiseExceptionContext

from zim.config import ConfigDict, ConfigDictFile, TextConfigFile, HierarchicDict, \

	config_file, data_dir, user_dirs

from zim.parsing import Re, is_url_re, is_email_re, is_win32_path_re, link_type, url_encode

import zim.stores

logger = logging.getLogger('zim.notebook')

class NotebookList(TextConfigFile):

	'''This class keeps a list of paths for notebook locations

	plus a attribute 'default' for the default notebook.

	All values are assumed to be (file://) urls.

	'''

	def read(self):

		TextConfigFile.read(self)

		if len(self) > 0:

			if self[0] == '[NotebookList]\n':

				self.parse()

			else:

				self.parse_old_format()

	@staticmethod

	def _filter(line):

		return line and not line.isspace() and not line.startswith('#')

	def parse(self):

		'''Parses the notebook list format after reading it'''

		assert self.pop(0) == '[NotebookList]\n'

		# Parse key for default

		if self[0].startswith('Default='):

			k, v = self.pop(0).strip().split('=', 1)

			self.default = v

		else:

			self.default = None

		# Parse rest of list - assumed to be urls, but we check to be sure

		def map_to_uri(line):

			uri = line.strip()

			if not uri.startswith('file://'):

				uri = File(uri).uri

			return uri

		self[:] = map(map_to_uri, filter(self._filter, self))

	def parse_old_format(self):

		'''Method for backward compatibility'''

		# Old format is name, value pair, separated by whitespace

		# with all other whitespace escaped by a \

		# Default was _default_ which could refer a notebook name..

		import re

		fields_re = re.compile(r'(?:\\.|\S)+') # match escaped char or non-whitespace

		escaped_re = re.compile(r'\\(.)') # match single escaped char

		default = None

		locations = []

		lines = [line.strip() for line in filter(self._filter, self)]

		for line in lines:

			cols = fields_re.findall(line)

			if len(cols) == 2:

				name = escaped_re.sub(r'\1', cols[0])

				path = escaped_re.sub(r'\1', cols[1])

				if name == '_default_':

					default = path

				else:

					path = Dir(path).uri

					locations.append(path)

					if name == default:

						self.default = path

		if not self.default and default:

			self.default = Dir(default).uri

		self[:] = locations

	def write(self):

		lines = self[:] # copy

		lines.insert(0, '[NotebookList]')

		lines.insert(1, 'Default=%s' % (self.default or ''))

		lines = [line + '\n' for line in lines]

		self.file.writelines(lines)

	def get_names(self):

		'''Generator function that yield tuples with the notebook

		name and the notebook path.

		'''

		for path in self:

			name = self.get_name(path)

			if name:

				yield (name, path)

	def get_name(self, uri):

		# TODO support for paths that turn out to be files

		file = Dir(uri).file('notebook.zim')

		if file.exists():

			config = ConfigDictFile(file)

			if 'name' in config['Notebook']:

				return config['Notebook']['name']

		return None

	def get_by_name(self, name):

		for n, path in self.get_names():

			if n.lower() == name.lower():

				return path

		else:

			return None

def get_notebook_list():

	'''Returns a list of known notebooks'''

	# TODO use weakref here

	return config_file('notebooks.list', klass=NotebookList)

def resolve_notebook(string):

	'''Takes either a notebook name or a file or dir path. For a name

	it resolves the path by looking for a notebook of that name in the

	notebook list. For a path it checks if this path points to a

	notebook or to a file in a notebook.

	It returns two values, a path to the notebook directory and an

	optional page path for a file inside a notebook. If the notebook

	was not found both values are None.

	'''

	assert isinstance(string, basestring)

	page = None

	if is_url_re.match(string):

		assert string.startswith('file://')

		if '?' in string:

			filepath, page = string.split('?', 1)

		else:

			filepath = string

	elif os.path.sep in string:

		filepath = string

	else:

		nblist = get_notebook_list()

		filepath = nblist.get_by_name(string)

		if filepath is None:

			return None, None # not found

	file = File(filepath) # Fixme need generic FS Path object here

	if filepath.endswith('notebook.zim'):

		return File(filepath).dir, page

	elif file.exists(): # file exists and really is a file

		parents = list(file)

		parents.reverse()

		for parent in parents:

			if File((parent, 'notebook.zim')).exists():

				page = file.relpath(parent)

				if '.' in page:

					page, _ = page.rsplit('.', 1) # remove extension

				page = Path(page.replace('/', ':'))

				return Dir(parent), page

		else:

			return None, None

	else:

		return Dir(file.path), page

	return notebook, path

def resolve_default_notebook():

	'''Returns a File or Dir object for the default notebook,

	or for the only notebook if there is only a single notebook

	in the list.

	'''

	default = None

	list = get_notebook_list()

	if list.default:

		default = list.default

	elif len(list) == 1:

		default = list[0]

	if default:

		if os.path.isfile(default):

			return File(default)

		else:

			return Dir(default)

	else:

		return None

def get_notebook(path):

	'''Convenience method that constructs a notebook from either a

	File or a Dir object.

	'''

	# TODO this is where the hook goes to automount etc.

	assert isinstance(path, (File, Dir))

	if path.exists():

		if isinstance(path, File):

			return Notebook(file=path)

		else:

			return Notebook(dir=path)

	else:

		return None

def get_default_notebook():

	'''Returns a Notebook object for the default notebook or None'''

	path = resolve_default_notebook()

	if path:

		return get_notebook(path)

	else:

		return None

def init_notebook(path, name=None):

	'''Initialize a new notebook in a directory'''

	assert isinstance(path, Dir)

	path.touch()

	config = ConfigDictFile(path.file('notebook.zim'))

	config['Notebook']['name'] = name or path.basename

	# TODO auto detect if we should enable the slow_fs option

	config.write()

def interwiki_link(link):

	'''Convert an interwiki link into an url'''

	assert isinstance(link, basestring) and '?' in link

	key, page = link.split('?', 1)

	url = None

	for line in config_file('urls.list'):

		if line.startswith(key+' ') or line.startswith(key+'\t'):

			url = line[len(key):].strip()

			break

	else:

		list = get_notebook_list()

		for name, path in list.get_names():

			if name.lower() == key.lower():

				url = path + '?{NAME}'

				break

	if url and is_url_re.match(url):

		if not ('{NAME}' in url or '{URL}' in url):

			url += '{URL}'

		url = url.replace('{NAME}', page)

		url = url.replace('{URL}', url_encode(page))

		return url

	else:

		return None

class PageNameError(Error):

	description = _('''\

The given page name is not valid.

''') # T: error description

	# TODO add to explanation what are validcharacters

	def __init__(self, name):

		self.msg = _('Invalid page name "%s"') % name # T: error message

class LookupError(Error):

	description = '''\

Failed to lookup this page in the notebook storage.

This is likely a glitch in the application.

'''

class IndexBusyError(Error):

	description = '''\

Index is still busy updating while we try to do an

operation that needs the index.

'''

class PageExistsError(Error):

	pass

	# TODO verbose description

class PageReadOnlyError(Error):

	# TODO verbose description

	def __init__(self, page):

		self.msg = _('Can not modify page: %s') % page.name

			# T: error message for read-only pages

class Notebook(gobject.GObject):

	'''Main class to access a notebook. Proxies between backend Store

	and Index objects on the one hand and the gui application on the other

	This class has the following signals:

		* store-page (page)

		* move-page (oldpath, newpath, update_links)

		* delete-page (path)

		* properties-changed ()

	All signals are defined with the SIGNAL_RUN_LAST type, so any

	handler connected normally will run before the actual action.

	Use "connect_after()" to install handlers after storing, moving

	or deleting a page.

	'''

	# TODO add checks for read-only page in much more methods

	# define signals we want to use - (closure type, return type and arg types)

	__gsignals__ = {

		'store-page': (gobject.SIGNAL_RUN_LAST, None, (object,)),

		'move-page': (gobject.SIGNAL_RUN_LAST, None, (object, object, bool)),

		'delete-page': (gobject.SIGNAL_RUN_LAST, None, (object,)),

		'properties-changed': (gobject.SIGNAL_RUN_FIRST, None, ()),

	}

	properties = (

		('name', 'string', _('Name')), # T: label for properties dialog

		('home', 'page', _('Home Page')), # T: label for properties dialog

		('icon', 'image', _('Icon')), # T: label for properties dialog

		('document_root', 'dir', _('Document Root')), # T: label for properties dialog

		('slow_fs', 'bool', _('Slow file system')), # T: label for properties dialog

		#~ ('autosave', 'bool', _('Auto-version when closing the notebook')),

			# T: label for properties dialog

	)

	def __init__(self, dir=None, file=None, config=None, index=None):

		assert not (dir and file), 'BUG: can not provide both dir and file '

		gobject.GObject.__init__(self)

		self._namespaces = []	# list used to resolve stores

		self._stores = {}		# dict mapping namespaces to stores

		self.namespace_properties = HierarchicDict()

		self._page_cache = weakref.WeakValueDictionary()

		self.dir = None

		self.file = None

		self.cache_dir = None

		self.name = None

		self.icon = None

		self.config = config

		if dir:

			assert isinstance(dir, Dir)

			self.dir = dir

			self.readonly = not dir.iswritable()

			self.cache_dir = dir.subdir('.zim')

			if self.readonly or not self.cache_dir.iswritable():

				self.cache_dir = self._cache_dir(dir)

			logger.debug('Cache dir: %s', self.cache_dir)

			if self.config is None:

				self.config = ConfigDictFile(dir.file('notebook.zim'))

			# TODO check if config defined root namespace

			self.add_store(Path(':'), 'files') # set root

			# TODO add other namespaces from config

		elif file:

			assert isinstance(file, File)

			self.file = file

			self.readonly = not file.iswritable()

			assert False, 'TODO: support for single file notebooks'

		if index is None:

			import zim.index # circular import

			self.index = zim.index.Index(notebook=self)

		else:

			self.index = index

			self.index.set_notebook(self)

		if self.config is None:

			self.config = ConfigDict()

		self.config['Notebook'].setdefault('name', None, klass=basestring)

		self.config['Notebook'].setdefault('home', ':Home', klass=basestring)

		self.config['Notebook'].setdefault('icon', None, klass=basestring)

		self.config['Notebook'].setdefault('document_root', None, klass=basestring)

		self.config['Notebook'].setdefault('slow_fs', False)

		self.do_properties_changed()

	@property

	def uri(self):

		'''Returns a file:// uri for this notebook that can be opened by zim'''

		assert self.dir or self.file, 'Notebook does not have a dir or file'

		if self.dir:

			return self.dir.uri

		else:

			return self.file.uri

	def _cache_dir(self, dir):

		from zim.config import XDG_CACHE_HOME

		path = 'notebook-' + dir.path.replace('/', '_').strip('_')

		return XDG_CACHE_HOME.subdir(('zim', path))

	def save_properties(self, **properties):

		# Check if icon is relative

		if 'icon' in properties and properties['icon'] \

		and self.dir and properties['icon'].startswith(self.dir.path):

			i = len(self.dir.path)

			path = './' + properties['icon'][i:].lstrip('/\\')

			# TODO use proper fs routine(s) for this substitution

			properties['icon'] = path

		# Set home page as string

		if 'home' in properties and isinstance(properties['home'], Path):

			properties['home'] = properties['home'].name

		self.config['Notebook'].update(properties)

		self.config.write()

		self.emit('properties-changed')

	def do_properties_changed(self):

		#~ import pprint

		#~ pprint.pprint(self.config)

		config = self.config['Notebook']

		# Set a name for ourselves

		if config['name']: 	self.name = config['name']

		elif self.dir: self.name = self.dir.basename

		elif self.file: self.name = self.file.basename

		else: self.name = 'Unnamed Notebook'

		# We should always have a home

		config.setdefault('home', ':Home')

		# Resolve icon, can be relative

		# TODO proper FS routine to check abs path - also allowed without the "./" - so e.g. icon.png should be resolved as well

		if self.dir and config['icon'] and config['icon'].startswith('.'):

			self.icon = self.dir.file(config['icon']).path

		elif config['icon']:

			self.icon = File(config['icon']).path

		else:

			self.icon = None

		# Set FS property

		if config['slow_fs']: print 'TODO: hook slow_fs property'

	def add_store(self, path, store, **args):

		'''Add a store to the notebook to handle a specific path and all

		it's sub-pages. Needs a Path and a store name, all other args will

		be passed to the store. Alternatively you can pass a store object

		but in that case no arguments are allowed.

		Returns the store object.

		'''

		assert not path.name in self._stores, 'Store for "%s" exists' % path

		if isinstance(store, basestring):

			mod = zim.stores.get_store(store)

			mystore = mod.Store(notebook=self, path=path, **args)

		else:

			assert not args

			mystore = store

		self._stores[path.name] = mystore

		self._namespaces.append(path.name)

		# keep order correct for lookup

		self._namespaces.sort(reverse=True)

		return mystore

	def get_store(self, path):

		'''Returns the store object to handle a page or namespace.'''

		for namespace in self._namespaces:

			# longest match first because of reverse sorting

			if namespace == ''			\

			or page.name == namespace	\

			or page.name.startswith(namespace+':'):

				return self._stores[namespace]

		else:

			raise LookupError, 'Could not find store for: %s' % name

	def get_stores(self):

		return self._stores.values()

	def resolve_path(self, name, source=None, index=None):

		'''Returns a proper path name for page names given in links

		or from user input. The optional argument 'source' is the

		path for the refering page, if any, or the path of the "current"

		page in the user interface.

		The 'index' argument allows specifying an index object, if

		none is given the default index for this notebook is used.

		If no source path is given or if the page name starts with

		a ':' the name is considered an absolute name and only case is

		resolved. If the page does not exist the last part(s) of the

		name will remain in the case as given.

		If a source path is given and the page name starts with '+'

		it will be resolved as a direct child of the source.

		Else we first look for a match of the first part of the name in the

		source path. If that fails we do a search for the first part of

		the name through all namespaces in the source path, starting with

		pages below the namespace of the source. If no existing page was

		found in this search we default to a new page below this namespace.

		So if we for example look for "baz" with as source ":foo:bar:dus"

		the following pages will be checked in a case insensitive way:

			:foo:bar:baz

			:foo:baz

			:baz

		And if none exist we default to ":foo:bar:baz"

		However if for example we are looking for "bar:bud" with as source

		":foo:bar:baz:dus", we only try to resolve the case for ":foo:bar:bud"

		and default to the given case if it does not yet exist.

		This method will raise a PageNameError if the name resolves

		to an empty string. Since all trailing ":" characters are removed

		there is no way for the name to address the root path in this method -

		and typically user input should not need to able to address this path.

		'''

		assert name, 'BUG: name is empty string'

		startswith = name[0]

		if startswith == '.':

			startswith = '+' # backward compat

		if startswith == '+':

			name = name[1:]

		name = self.cleanup_pathname(name)

		if index is None:

			index = self.index

		if startswith == ':' or source == None:

			return index.resolve_case(name) or Path(name)

		elif startswith == '+':

			if not source:

				raise PageNameError, '+'+name

			return index.resolve_case(source.name+':'+name)  \

						or Path(source.name+':'+name)

			# FIXME use parent as argument

		else:

			# first check if we see an explicit match in the path

			assert isinstance(source, Path)

			anchor = name.split(':')[0].lower()

			path = source.namespace.lower().split(':')

			if anchor in path:

				# ok, so we can shortcut to an absolute path

				path.reverse() # why is there no rindex or rfind ?

				i = path.index(anchor) + 1

				path = path[i:]

				path.reverse()

				path.append( name.lstrip(':') )

				name = ':'.join(path)

				return index.resolve_case(name) or Path(name)

				# FIXME use parentt as argument

				# FIXME use short cut when the result is the parent

			else:

				# no luck, do a search through the whole path - including root

				source = index.lookup_path(source) or source

				for parent in source.parents():

					candidate = index.resolve_case(name, namespace=parent)

					if not candidate is None:

						return candidate

				else:

					# name not found, keep case as is

					return source.parent + name

	def relative_link(self, source, href):

		'''Returns a link for a path 'href' relative to path 'source'.

		More or less the opposite of resolve_path().

		'''

		if href == source:

			return href.basename

		elif href > source:

			return '+' + href.relname(source)

		else:

			parent = source.commonparent(href)

			if parent.isroot:

				return ':' + href.name

			else:

				return parent.basename + ':' + href.relname(parent)

	def register_hook(self, name, handler):

		'''Register a handler method for a specific hook'''

		register = '_register_%s' % name

		if not hasattr(self, register):

			setattr(self, register, [])

		getattr(self, register).append(handler)

	def unregister_hook(self, name, handler):

		'''Remove a handler method for a specific hook'''

		register = '_register_%s' % name

		if hasattr(self, register):

			getattr(self, register).remove(handler)

	def suggest_link(self, source, word):

		'''Suggest a link Path for 'word' or return None if no suggestion is

		found. By default we do not do any suggestion but plugins can

		register handlers to add suggestions. See 'register_hook()' to

		register a handler.

		'''

		if not  hasattr(self, '_register_suggest_link'):

			return None

		for handler in self._register_suggest_link:

			link = handler(source, word)

			if not link is None:

				return link

		else:

			return None

	@staticmethod

	def cleanup_pathname(name):

		'''Returns a safe version of name, used internally by functions like

		resolve_path() to parse user input.

		'''

		orig = name

		name = name.replace('_', ' ')

			# Avoid duplicates with and without '_' in index

		name = ':'.join( map(unicode.strip,

				filter(lambda n: len(n)>0, unicode(name).split(':')) ) )

		# Reserved characters are:

		# The ':' is reserrved as seperator

		# The '?' is reserved to encode url style options

		# The '#' is reserved as anchor separator

		# The '/' and '\' are reserved to distinquise file links & urls

		# First character of each part MUST be alphanumeric

		#		(including utf8 letters / numbers)

		# Zim version < 0.42 restricted all special charachters but

		# white listed ".", "-", "_", "(", ")", ":" and "%".

		# TODO check for illegal characters in the name

		if not name or name.isspace():

			raise PageNameError, orig

		return name

	def get_page(self, path):

		'''Returns a Page object. This method uses a weakref dictionary to

		ensure that an unique object is being used for each page that is

		given out.

		'''

		# As a special case, using an invalid page as the argument should

		# return a valid page object.

		assert isinstance(path, Path)

		if path.name in self._page_cache \

		and self._page_cache[path.name].valid:

			return self._page_cache[path.name]

		else:

			store = self.get_store(path)

			page = store.get_page(path)

			# TODO - set haschildren if page maps to a store namespace

			self._page_cache[path.name] = page

			return page

	def flush_page_cache(self, path):

		'''Remove a page from the page cache, calling get_page() after this

		will return a fresh page object. Be aware that the old object

		may still be around but will have its 'valid' attribute set to False.

		This function also removes all child pages of path from the cache.

		'''

		names = [path.name]

		ns = path.name + ':'

		names.extend(k for k in self._page_cache.keys() if k.startswith(ns))

		for name in names:

			if name in self._page_cache: