README
1GeanyPy
2=======
3
4Write Geany plugins in Python!
5
6Provides most of the standard Geany C API for Python.
7
8**Please note:** GeanyPy here in geany-plugins is based on the upstream
9at https://github.com/codebrainz/geanypy which is still under
10development, however it is useful as is. Parts of the existing API
11which mirror the Geany C API will probably not change unless the Geany API
12changes, however new API may be added. Also documentation is needed,
13contributions are welcome.
14
15.. warning::
16 The upstream Geanypy is being updated to use the new proxy plugins mechanism
17 which will allow Python plugins to be first class plugins. This also allows
18 them to have keybindings and all the features of C plugins. This change
19 causes some incompatibilities with current plugins, and existing Python plugins will
20 need to be upgraded. It is intended that the version of Geanypy with
21 Geany-Plugins 1.27 will contain the changes, and from that release existing
22 plugins may not work.
23
24How it works
25------------
26
27In the ``src/`` directory is a normal Geany plugin (``plugin.c``) which loads the
28Python interpreter. It then loads some C Python modules (``dialogs.c``,
29``documents.c``, etc.) that interface with Geany's C API. After that, it loads
30the ``geany`` Python module which is just glue/sugar-coating to make the C
31module more "Pythonic".
32
33To write a plugin, inherit from the ``geany.Plugin`` class and implmenent the
34required members (see ``geany/plugin.py`` documentation comments). Then put the
35plugin in a searched plugin path. Currently two locations are search for
36plugins. The first is ``PREFIX/lib/geany`` and the recommended
37location is under your personal Geany directory (usually
38``~/.config/geany/plugins``). To load or unload plugins, use Geany's regular Plugin
39+Manager. Python plugins appear there once GeanyPy is activated.
40
41When the Python Console plugin is enabled, it will add a new tab to the notebook in
42the message window area that contains an interactive Python shell with the `geany`
43Python shell with the ``geany`` module pre-imported. You can tinker
44around with API with this console, for example::
45
46
47 import geany
48
49 doc = geany.document.open_file("/some/file/here")
50
51 print(doc.file_name)
52 print(doc.file_type.display_name)
53
54 geany.dialogs.show_msgbox("Hello World")
55
56 geany.main_widgets.window.set_title("Hello Window")
57
58 def on_document_open(doc):
59 print("Document '%s' was opened" % doc.file_name)
60
61 geany.signals.connect('document-open', on_document_open)
62
63
64Dependencies
65------------
66
67To build GeanyPy you need the following dependencies:
68
69* Python 2.6 or 2.7 and development files.
70* Geany 1.24+ and development files
71* PyGTK 2.0 and development files
72
73Running on Windows
74------------------
75
76Not currently supported for the geany-plugins version, see upstream
77https://github.com/codebrainz/geanypy.
78
79Upstream developed by Matthew Brush.
80
81Geany-plugins version maintained by elextr@lists.geany.org
82
83Known Bugs
84----------
85
86* There is an issue with re-loading GeanyPy twice in the same session. If
87 you unload the GeanyPy plugin you should restart Geany to avoid a potential
88 crash.
89