beginning wikitools core development with a few skeleton classes and one (nearly) working function, tools.get_site() (doesn't return a Site object yet)

wiki/tools/__init__.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8  -*-
+
+"""
+EarwigBot's Wiki Toolset
+
+This is a collection of classes and functions to read from and write to
+Wikipedia and other wiki sites. No connection whatsoever to python-wikitools
+written by Mr.Z-man, other than a similar purpose. We share no code.
+
+Import the toolset with `from wiki import tools`.
+"""
+
+from wiki.tools.exceptions import *
+from wiki.tools.functions import *
+
+from wiki.tools.category import Category
+from wiki.tools.page import Page
+from wiki.tools.site import Site
+from wiki.tools.user import User

wiki/tools/category.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8  -*-
+
+class Category(object):
+    """
+    EarwigBot's Wiki Toolset: Category Class
+    """
+
+    def __init__(self):
+        pass

wiki/tools/exceptions.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8  -*-
+
+"""
+EarwigBot's Wiki Toolset: Exceptions
+
+This module contains all exceptions used by the wiki.tools package.
+"""
+
+class WikiToolsetError(Exception):
+    """Base exception class for errors in the Wiki Toolset."""
+
+class ConfigError(WikiToolsetError):
+    """An error occured when trying to do something involving our config
+    file. Maybe it hasn't been loaded?"""
+
+class SiteNotFoundError(WikiToolsetError):
+    """A site matching the args given to get_site() could not be found in the
+    config file."""

wiki/tools/functions.py

@@ -0,0 +1,75 @@
+# -*- coding: utf-8  -*-
+
+"""
+EarwigBot's Wiki Toolset: Misc Functions
+
+This module, a component of the wiki.tools package, contains miscellaneous
+functions that are not methods of any class, like get_site().
+
+There's no need to import this module explicitly. All functions here are
+automatically available from wiki.tools.
+"""
+
+from core import config
+from wiki.tools.exceptions import ConfigError, SiteNotFoundError
+from wiki.tools.site import Site
+
+__all__ = ["get_site"]
+
+def get_site(name=None, project=None, lang=None):
+    """Returns a Site instance based on information from our config file.
+
+    With no arguments, returns the default site as specified by our config
+    file. This is default = config.wiki["defaultSite"];
+    config.wiki["sites"][default].
+
+    With `name` specified, returns the site specified by
+    config.wiki["sites"][name].
+
+    With `project` and `lang` specified, returns the site specified by the
+    member of config.wiki["sites"], `s`, for which s["project"] == project and
+    s["lang"] == lang.
+
+    Specifying a project without a lang or a lang without a project will raise
+    TypeError. If all three args are specified, `name` will be first tried,
+    then `project` and `lang`. If, with any number of args, a site cannot be
+    found in the config, SiteNotFoundError is raised.
+    """
+    if config._config is None:
+        e = "Config file has not been loaded: use config.verify_config() and then config.parse_config() to do so."
+        raise ConfigError(e)
+
+    if (project is None and lang is not None) or (project is not None and lang is None):
+        e = "Keyword arguments 'lang' and 'project' must be specified together."
+        raise TypeError(e)
+
+    if name is None and project is None:  # no args given (project is None implies lang is None)
+        try:  # ...so use the default site
+            default = config.wiki["defaultSite"]
+        except KeyError:
+            e = "Default site is not specified in config."
+            raise SiteNotFoundError(e)
+        try:
+            return config.wiki["sites"][default]
+        except KeyError:
+            e = "Default site specified by config is not in the config's sites list."
+            raise SiteNotFoundError(e)
+
+    if name is not None:  # name arg given, but don't look at others yet
+        try:
+            return config.wiki["sites"][name]
+        except KeyError:
+            if project is None:  # implies lang is None, i.e., only name was given
+                e = "Site '{0}' not found in config.".format(name)
+                raise SiteNotFoundError(e)
+            for site in config.wiki["sites"].values():
+                if site["project"] == project and site["lang"] == lang:
+                    return site
+            e = "Neither site '{0}' nor site '{1}:{2}' found in config.".format(name, project, lang)
+            raise SiteNotFoundError(e)
+
+    for site in config.wiki["sites"].values():  # implied lang and proj are not None
+        if site["project"] == project and site["lang"] == lang:
+            return site
+    e = "Site '{0}:{1}' not found in config.".format(project, lang)
+    raise SiteNotFoundError(e)

wiki/tools/page.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8  -*-
+
+class Page(object):
+    """
+    EarwigBot's Wiki Toolset: Page Class
+    """
+
+    def __init__(self):
+        pass

wiki/tools/site.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8  -*-
+
+class Site(object):
+    """
+    EarwigBot's Wiki Toolset: Site Class
+    """
+
+    def __init__(self):
+        pass

wiki/tools/user.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8  -*-
+
+class User(object):
+    """
+    EarwigBot's Wiki Toolset: User Class
+    """
+
+    def __init__(self):
+        pass