|
| 1 | +=================================== |
| 2 | +General advices and troubleshooting |
| 3 | +=================================== |
| 4 | + |
| 5 | +.. contents:: |
| 6 | + :local: |
| 7 | + |
| 8 | + |
| 9 | +Getting code samples |
| 10 | +-------------------- |
| 11 | + |
| 12 | +Yapsy is used enough for your favorite search provider to have good |
| 13 | +chances of finding some examples of yapsy being used in the wild. |
| 14 | + |
| 15 | +However if you wonder how a specific functionality can be used, you |
| 16 | +can also look at the corresponding unit test (in the test folder |
| 17 | +packaged with yapsy's sources). |
| 18 | + |
| 19 | + |
| 20 | +Use the logging system |
| 21 | +---------------------- |
| 22 | + |
| 23 | +Yapsy uses Python's standard ``logging`` module to record most |
| 24 | +important events and especially plugin loading failures. |
| 25 | + |
| 26 | +When developping an application based on yapsy, you'll benefit from |
| 27 | +looking at the 'debug' level logs, which can easily be done from your |
| 28 | +application code with the following snippet:: |
| 29 | + |
| 30 | + import logging |
| 31 | + logging.basicConfig(level=logging.DEBUG) |
| 32 | + |
| 33 | +Also, please note that yapsy uses a named logger for all its logs, so |
| 34 | +that you can selectively activage debug logs for yapsy with the |
| 35 | +following snippet:: |
| 36 | + |
| 37 | + import logging |
| 38 | + logging.getLogger('yapsy').setLevel(logging.DEBUG) |
| 39 | + |
| 40 | + |
| 41 | +Categorization and inheritance caveat |
| 42 | +------------------------------------- |
| 43 | + |
| 44 | +If your application defines various categories of plugins with the yapsy's built-in mechanism for that, please keep in mind the following facts: |
| 45 | + |
| 46 | + - a plugin instance is attributed to a given category by looking if |
| 47 | + it is an instance, *even via a subclass*, of the class associated |
| 48 | + to this category; |
| 49 | + - a plugin may be attributed to several categories. |
| 50 | + |
| 51 | +Considering this, and if you consider using several categories, you |
| 52 | +should consider the following tips: |
| 53 | + |
| 54 | + - **don't associate any category to ``IPlugin``** (unless you want |
| 55 | + all plugins to be attributed to the corresponding category) |
| 56 | + - **design a specific subclass** of ``IPlugin`` for each category |
| 57 | + - if you want to regroup plugins of some categories into a common |
| 58 | + category: do this by attributing a subclass of ``IPlugin`` to the |
| 59 | + common category and attribute to the other categories specific |
| 60 | + subclasses to this intermediate mother class so that **the plugin |
| 61 | + class inheritance hierarchy reflects the hierarchy between |
| 62 | + categories** (and if you want something more complex that a |
| 63 | + hierarchy, you can consider using mixins). |
| 64 | + |
| 65 | + |
| 66 | +Plugin packaging |
| 67 | +---------------- |
| 68 | + |
| 69 | +When packaging plugins in a distutils installer or as parts of an |
| 70 | +application (like for instance with `py2exe`), you may want to take |
| 71 | +care about the following points: |
| 72 | + |
| 73 | +- when you set specific directories where to look for plugins with a |
| 74 | + hardcoded path, be very carefully about the way you write these |
| 75 | + paths because depending on the cases **using ``__file__`` or |
| 76 | + relative paths may be unreliable**. For instance with py2exe, you |
| 77 | + may want to follow the tips from the `Where Am I FAQ`_. |
| 78 | + |
| 79 | +- you'd should either **package the plugins as plain Python modules or |
| 80 | + data files** (if you want to consider you application as the only |
| 81 | + module), either using the dedicated `setup` argument for `py2exe` or |
| 82 | + using distutils' `MANIFEST.in` |
| 83 | + |
| 84 | +- if you do package the plugins as data files, **make sure that their |
| 85 | + dependencies are correctly indicated as dependencies of your |
| 86 | + package** (or packaged with you application if you use `py2exe`). |
| 87 | + |
| 88 | +See also a more detailed example for py2exe on `Simon on Tech's Using python plugin scripts with py2exe`_. |
| 89 | + |
| 90 | +.. _`Where Am I FAQ`: http://www.py2exe.org/index.cgi/WhereAmI |
| 91 | +.. _`Simon on Tech's Using python plugin scripts with py2exe`: http://notinthestars.blogspot.com.es/2011/04/using-python-plugin-scripts-with-py2exe.html |
| 92 | + |
| 93 | + |
| 94 | +Code conventions |
| 95 | +---------------- |
| 96 | + |
| 97 | +If you intend to modify yapsy's sources and to contribute patches |
| 98 | +back, please respect the following conventions: |
| 99 | + |
| 100 | +- CamelCase (upper camel case) for class names and functions |
| 101 | +- camelCase (lower camel case) for methods |
| 102 | +- UPPERCASE for global variables (with a few exceptions) |
| 103 | +- tabulations are used for indentation (and not spaces !) |
| 104 | +- unit-test each new functionality |
| 105 | + |
0 commit comments