Added hscommon repo as a subtree

hscommon/docs/build.rst

@@ -0,0 +1,25 @@
+==========================================
+:mod:`build` - Build utilities for HS apps
+==========================================
+
+This module is a collection of function to help in HS apps build process.
+
+.. function:: print_and_do(cmd)
+
+    Prints ``cmd`` and executes it in the shell.
+
+.. function:: build_all_qt_ui(base_dir='.')
+
+    Calls Qt's ``pyuic4`` for each file in ``base_dir`` with a ".ui" extension. The resulting file is saved under ``{base_name}_ui.py``.
+
+.. function:: build_dmg(app_path, dest_path)
+
+    Builds a DMG volume with application at ``app_path`` and puts it in ``dest_path``. The name of the resulting DMG volume is determined by the app's name and version.
+
+.. function:: add_to_pythonpath(path)
+
+    Adds ``path`` to both ``PYTHONPATH`` env variable and ``sys.path``.
+
+.. function:: copy_packages(packages_names, dest)
+
+    Copy python packages ``packages_names`` to ``dest``, but without tests, testdata, mercurial data or C extension module source with it. ``py2app`` include and exclude rules are **quite** funky, and doing this is the only reliable way to make sure we don;t end up with useless stuff in our app.

hscommon/docs/conf.py

@@ -0,0 +1,194 @@
+# -*- coding: utf-8 -*-
+#
+# hscommon documentation build configuration file, created by
+# sphinx-quickstart on Fri Mar 12 16:00:37 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'hscommon'
+copyright = '2011, Hardcoded Software'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.0.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'hscommondoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'hscommon.tex', 'hscommon Documentation',
+   'Hardcoded Software', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True

hscommon/docs/conflict.rst

@@ -0,0 +1,27 @@
+===================================================
+:mod:`conflict` - Detect and resolve name conflicts
+===================================================
+
+.. module:: conflict
+
+When you have to deal with names that have to be unique and can conflict together, you can use this module that deals with conflicts by prepending unique numbers in ``[]`` brackets to the name.
+
+.. function:: get_conflicted_name(other_names, name)
+
+    Returns a name based on ``name`` that is guaranteed not to be in ``other_names``. Name conflicts are resolved by prepending numbers in ``[]`` brackets to the name.
+
+.. function:: get_unconflicted_name(name)
+
+    Returns ``name`` without ``[]`` brackets.
+
+.. function:: is_conflicted(name)
+
+    Returns whether ``name`` is prepended with a bracketed number.
+
+.. function:: smart_copy(source_path, dest_path)
+
+    Copies ``source_path`` to ``dest_path``, recursively. However, it does conflict resolution using functions in this module.
+
+.. function:: smart_move(source_path, dest_path)
+
+    Same as :func:`smart_copy`, but it moves files instead.

hscommon/docs/currency.rst

@@ -0,0 +1,62 @@
+===================================
+:mod:`currency` - Manage currencies
+===================================
+
+This module facilitates currencies management. It exposes :class:`Currency` which lets you easily figure out their exchange value.
+
+The ``Currency`` class
+======================
+
+.. class:: Currency(code=None, name=None)
+
+    A ``Currency`` instance is created with either a 3-letter ISO code or with a full name. If it's present in the database, an instance will be returned. If not, ``ValueError`` is raised. The easiest way to access a currency instance, however, if by using module-level constants. For example::
+
+        >>> from hscommon.currency import USD, EUR
+        >>> from datetime import date
+        >>> USD.value_in(EUR, date.today())
+        0.6339119851386843
+
+    Unless a :class:`currency.RatesDB` global instance is set through :meth:`Currency.set_rate_db` however, only fallback values will be used as exchange rates.
+
+    .. staticmethod:: Currency.register(code, name, exponent=2, fallback_rate=1)
+
+        Register a new currency in the currency list.
+
+    .. staticmethod:: Currency.set_rates_db(db)
+
+        Sets a new currency ``RatesDB`` instance to be used with all ``Currency`` instances.
+
+    .. staticmethod:: Currency.set_rates_db()
+
+        Returns the current ``RatesDB`` instance.
+
+    .. method:: Currency.rates_date_range()
+
+        Returns the range of date for which rates are available for this currency.
+
+    .. method:: Currency.value_in(currency, date)
+
+        Returns the value of this currency in terms of the other currency on the given date.
+
+    .. method:: Currency.set_CAD_value(value, date)
+
+        Sets currency's value in CAD on the given date.
+
+The ``RatesDB`` class
+=====================
+
+.. class:: RatesDB(db_or_path=':memory:')
+
+    A sqlite database that stores currency/date/value pairs, "value" being the value of the currency in CAD at the given date. Currencies are referenced by their 3-letter ISO code in the database and it its arguments (so ``currency_code`` arguments must be 3-letter strings).
+    
+    .. method:: RatesDB.date_range(currency_code)
+
+        Returns a tuple ``(start_date, end_date)`` representing dates covered in the database for currency ``currency_code``. If there are gaps, they are not accounted for (subclasses that automatically update themselves are not supposed to introduce gaps in the db).
+
+    .. method:: RatesDB.get_rate(date, currency1_code, currency2_code)
+
+        Returns the exchange rate between currency1 and currency2 for date. The rate returned means '1 unit of currency1 is worth X units of currency2'. The rate of the nearest date that is smaller than 'date' is returned. If there is none, a seek for a rate with a higher date will be made.
+
+    .. method:: RatesDB.set_CAD_value(date, currency_code, value)
+
+        Sets the CAD value of ``currency_code`` at ``date`` to ``value`` in the database.

hscommon/docs/index.rst

@@ -0,0 +1,32 @@
+==============================================
+hscommon - Common code used throughout HS apps
+==============================================
+
+:Author: `Hardcoded Software <http://www.hardcoded.net>`_
+:Dev website: http://hg.hardcoded.net/hscommon
+:License: BSD License
+
+Introduction
+============
+
+``hscommon`` is a collection of tools used throughout HS apps.
+
+Dependencies
+============
+
+Python 3.1 is required. `py.test <http://pytest.org/>`_ is required to run the tests.
+
+API Documentation
+=================
+
+.. toctree::
+   :maxdepth: 2
+   
+   build
+   conflict
+   currency
+   notify
+   path
+   reg
+   sqlite
+   util

hscommon/docs/notify.rst

@@ -0,0 +1,26 @@
+==========================================
+:mod:`notify` - Simple notification system
+==========================================
+
+.. module:: notify
+
+This module is a brain-dead simple notification system involving a :class:`Broadcaster` and a :class:`Listener`. A listener can only listen to one broadcaster. A broadcaster can have multiple listeners. If the listener is connected, whenever the broadcaster calls :meth:`~Broadcaster.notify`, the method with the same name as the broadcasted message is called on the listener.
+
+.. class:: Broadcaster
+
+    .. method:: notify(msg)
+    
+        Notify all connected listeners of ``msg``. That means that each listeners will have their method with the same name as ``msg`` called.
+
+.. class:: Listener(broadcaster)
+
+    A listener is initialized with the broadcaster it's going to listen to. Initially, it is not connected.
+    
+    .. method:: connect()
+    
+        Connects the listener to its broadcaster.
+    
+    .. method:: disconnect()
+        
+        Disconnects the listener from its broadcaster.
+    

hscommon/docs/path.rst

@@ -0,0 +1,13 @@
+========================================
+:mod:`path` - Work with paths
+========================================
+
+.. module:: path
+
+.. class:: Path(value, separator=None)
+
+    ``Path`` instances can be created from strings, other ``Path`` instances or tuples. If ``separator`` is not specified, the one from the OS is used. Once created, paths can be manipulated like a tuple, each element being an element of the path. It makes a few common operations easy, such as getting the filename (``path[-1]``) or the directory name or parent (``path[:-1]``).
+    
+    HS apps pretty much always refer to ``Path`` instances when a variable name ends with ``path``. If a variable is of another type, that type is usually explicited in the name.
+    
+    To make common operations (from ``os.path``, ``os`` and ``shutil``) convenient, the :mod:`io` module wraps these functions and converts paths to strings.

hscommon/docs/reg.rst

@@ -0,0 +1,25 @@
+========================================
+:mod:`reg` - Manage app registration
+========================================
+
+.. module:: reg
+
+.. class:: RegistrableApplication
+
+    HS main application classes subclass this. It provides an easy interface for managing whether the app should be in demo mode or not.
+    
+    .. method:: _setup_as_registered()
+    
+        Virtual. This is called whenever the app is unlocked. This is the one place to put code that changes to UI to indicate that the app is unlocked.
+    
+    .. method:: validate_code(code, email)
+    
+        Validates ``code`` with email. If it's valid, it does nothing. Otherwise, it raises ``InvalidCodeError`` with a message indicating why it's invalid (wrong product, wrong code format, fields swapped).
+    
+    .. method:: set_registration(code, email)
+    
+        If ``code`` and ``email`` are valid, sets ``registered`` to True as well as ``registration_code`` and ``registration_email`` and then calls :meth:`_setup_as_registered`.
+
+.. exception:: InvalidCodeError
+
+    Raised during :meth:`RegistrableApplication.validate_code`.

hscommon/docs/sqlite.rst

@@ -0,0 +1,9 @@
+==========================================
+:mod:`sqlite` - Threaded sqlite connection
+==========================================
+
+.. module:: sqlite
+
+.. class:: ThreadedConn(dbname, autocommit)
+
+    ``sqlite`` connections can't be used across threads. ``TheadedConn`` opens a sqlite connection in its own thread and sends it queries through a queue, making it suitable in multi-threaded environment.

hscommon/docs/util.rst

@@ -0,0 +1,88 @@
+========================================
+:mod:`util` - Miscellaneous utilities
+========================================
+
+.. module:: misc
+
+.. function:: nonone(value, replace_value)
+    
+    Returns ``value`` if value is not None. Returns ``replace_value`` otherwise.
+
+.. function:: dedupe(iterable)
+    
+    Returns a list of elements in ``iterable`` with all dupes removed. The order of the elements is preserved.
+
+.. function:: flatten(iterables, start_with=None)
+    
+    Takes the list of iterable ``iterables`` and returns a list containing elements of every iterable.
+    
+    If ``start_with`` is not None, the result will start with ``start_with`` items, exactly as if ``start_with`` would be the first item of lists.
+
+.. function:: first(iterable)
+    
+    Returns the first item of ``iterable`` or ``None`` if empty.
+
+.. function:: tryint(value, default=0)
+    
+    Tries to convert ``value`` to in ``int`` and returns ``default`` if it fails.
+
+.. function:: escape(s, to_escape, escape_with='\\')
+    
+    Returns ``s`` with characters in ``to_escape`` all prepended with ``escape_with``.
+
+.. function:: format_size(size, decimal=0, forcepower=-1, showdesc=True)
+    
+    Transform a byte count ``size`` in a formatted string (KB, MB etc..). ``decimal`` is the number digits after the dot. ``forcepower`` is the desired suffix. 0 is B, 1 is KB, 2 is MB etc.. if kept at -1, the suffix will be automatically chosen (so the resulting number is always below 1024). If ``showdesc`` is True, the suffix will be shown after the number. Usage example::
+    
+        >>> format_size(1234, decimal=2, showdesc=True)
+        '1.21 KB'
+
+.. function:: format_time(seconds, with_hours=True)
+    
+    Transforms seconds in a hh:mm:ss string.
+    
+    If `with_hours` if false, the format is mm:ss.
+
+.. function:: format_time_decimal(seconds)
+
+    Transforms seconds in a strings like '3.4 minutes'.
+
+.. function:: get_file_ext(filename)
+    
+    Returns the lowercase extension part of ``filename``, without the dot.
+
+.. function:: pluralize(number, word, decimals=0, plural_word=None)
+    
+    Returns a string with ``number`` in front of ``word``, and adds a 's' to ``word`` if ``number`` > 1. If ``plural_word`` is defined, it will replace ``word`` in plural cases instead of appending a 's'.
+
+.. function:: rem_file_ext(filename)
+    
+    Returns ``filename`` without extension.
+
+.. function:: multi_replace(s, replace_from, replace_to='')
+    
+    A function like str.replace() with multiple replacements. ``replace_from`` is a list of things you want to replace (Ex: ``['a','bc','d']``). ``replace_to`` is a list of what you want to replace to. If ``replace_to`` is a list and has the same length as ``replace_from``, ``replace_from`` items will be translated to corresponding ``replace_to``. A ``replace_to`` list must have the same length as ``replace_from``. If ``replace_to`` is a string, all ``replace_from`` occurences will be replaced by that string. ``replace_from`` can also be a string. If it is, every char in it will be translated as if ``replace_from`` would be a list of chars. If ``replace_to`` is a string and has the same length as ``replace_from``, it will be transformed into a list.
+    
+.. function:: open_if_filename(infile, mode='rb')
+
+    If ``infile`` is a string, it opens and returns it. If it's already a file object, it simply returns it. This function returns ``(file, should_close_flag)``. The should_close_flag is True is a file has effectively been opened (if we already pass a file object, we assume that the responsibility for closing the file has already been taken). Example usage::
+    
+        fp, shouldclose = open_if_filename(infile)
+        dostuff()
+        if shouldclose:
+            fp.close()
+    
+.. class:: FileOrPath(file_or_path, mode='rb')
+
+    Does the same as :func:`open_if_filename`, but it can be used with a ``with`` statement. Example::
+    
+        with FileOrPath(infile):
+            dostuff()
+
+.. function:: delete_if_empty(path, files_to_delete=[])
+
+    Same as with :func:`clean_empty_dirs`, but not recursive.
+
+.. function:: modified_after(first_path, second_path)
+
+    Returns True if ``first_path``'s mtime is higher than ``second_path``'s mtime.