1
# -*- coding: utf8 - *-
2 2
"""
3
Cihai Plugin System
4

5
Status: Experimental, API can change
6

7
As a pilot, the UNIHAN library, and an plugin for it, in #131 [1]_
8

9
You can bring any data layout / backend you like to cihai.
10

11
For convenience, you can use cihai's configuration namespace and SQLAlchemy settings.
12

13
You can also create plugins which extend another. So if Unihan doesn't have a lookup
14
for variant glyphs, this can be added.
15
"""
16 2
from __future__ import absolute_import, print_function, unicode_literals
17

18 2
from . import utils
19 2
from ._compat import string_types
20

21

22 2
class ConfigMixin(object):
23
    """
24
    This piggybacks cihai's global config state, as well as your datasets.
25

26
    Cihai will automatically manage the user's config, as well as your datasets,
27
    neatly in XDG.
28

29
    Raises
30
    ------
31
    Functions inside, and what you write relating to dataset config should return
32

33
    CihaiDatasetConfigException (CihaiDatasetException)
34

35
    config.cihai = links directly back to Cihai's configuration dictionary
36
    (todo note: make this non-mutable property)
37

38
    config : dict
39
        your local user's config
40

41
    check() : function, optional
42
        this is ran on start. it can raise DatasetConfigException
43

44
    default_config : your dataset's default configuration
45

46
    get_default_config : override function in case you'd like custom configs (for
47
        instnace if you want a platform to use a different db driver, or do version
48
        checks, etc.)
49

50
        internal functions use get_default_config()
51
    """
52

53

54 2
class SQLAlchemyMixin(object):
55
    """Your dataset can use any backend you'd like, we provide a backend for you, that
56
    automatically piggybacks on cihai's zero-config, XDG / SQLAchemy configuration. So
57
    it's preconfigured for the user.
58

59
    In addition, this mixin gives you access to any other of the user's sqlalchemy
60
    sql that use this mixin. So if you want a dataset that utilitizes UNIHAN, you can
61
    access that easily.
62

63
    This will provide the following instance-level properties in methods:
64

65
    When you have access, it's expected to keep your tables / databases namespaced so
66
    they don't clobber.
67
    """
68

69
    #: :class:`sqlalchemy.engine.Engine` instance.
70 2
    engine = None
71

72
    #: :class:`sqlalchemy.schema.MetaData` instance.
73 2
    metadata = None
74

75
    #: :class:`sqlalchemy.orm.session.Session` instance.
76 2
    session = None
77

78
    #: :class:`sqlalchemy.ext.automap.AutomapBase` instance.
79 2
    base = None
80

81

82 2
class Dataset(object):
83
    """
84
    Cihai dataset, e.g. UNIHAN.
85

86
    See Also
87
    --------
88
    cihai.data.unihan.dataset.Unihan : reference implementation
89
    """
90

91 2
    def bootstrap(self):
92 0
        pass
93

94 2
    def add_plugin(self, _cls, namespace, bootstrap=True):
95 2
        if isinstance(_cls, string_types):
96 2
            _cls = utils.import_string(_cls)
97 2
        setattr(self, namespace, _cls())
98 2
        plugin = getattr(self, namespace)
99

100 2
        if hasattr(self, 'sql') and isinstance(self, SQLAlchemyMixin):
101 2
            plugin.sql = self.sql
102

103 2
        if bootstrap and hasattr(plugin, 'bootstrap') and callable(plugin.bootstrap):
104 2
            plugin.bootstrap()
105

106

107 2
class DatasetPlugin(object):
108
    """
109
    Extend the functionality of datasets with custom methods, actions, etc.
110

111
    See Also
112
    --------
113
    cihai.data.unihan.dataset.UnihanVariants : reference implementation
114
    """

Read our documentation on viewing source code .

Loading