Debian Codegraph @

doc/external_import_en.html

raw
1 <?xml version="1.0" ?>
2 <!DOCTYPE html
3 PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
4 "DTD/xhtml1-strict.dtd">
5
6 <html xmlns="http://www.w3.org/1999/xhtml">
7 <head>
8 <link href="css/style.css" rel="stylesheet" type="text/css"/>
9 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
10 <title>Creating custom templates</title>
11 </head>
12 <body>
13 <h2>How to run BKChem from outside</h2>
14
15 <p>Starting from version <b>0.9.0-pre1</b> it is possible to import bkchem from
16 a script and operate it from outside. This short article should help you getting started.</p>
17
18 <h3>Word of warning</h3>
19 <p>The possibility to run bkchem from a script adds the used a really powerful tool.
20 However, keep in mind that the API is not yet very stable, badly documented and many convenience
21 features are missing. Therefore you should be warned that it might be very
22 frustrating to write such scripts and they may even not work with further versions on BKChem.</p>
23
24
25 <h3>Creating the simple script</h3>
26
27 <p>I will demonstrate the process in calling bkchem from outside on a simple script.
28 It will take a filename of a bkchem file from the command line, open it, recolor all
29 double bonds to red, save the result and quit. You can find the script
30 <a href="scripts/script1.py">here</a>.</p>
31
32 <p>At the very beginning of the script we just check for the filename to process:</p>
33
34 <pre>
35 import sys
36
37 # at first we check the command line
38 if len( sys.argv) &lt;= 1:
39 print "you have to supply a filename"
40 sys.exit()
41 </pre>
42
43 <p>The most important part comes now - it shows the general approach
44 to the problem of calling bkchem from another application:</p>
45
46 <pre>
47 # then we import bkchem and threading
48 from bkchem.bkchem import bkchem
49 import threading
50
51 # bkchem.myapp is the application instance
52 app = bkchem.myapp
53
54 # we need to set batch mode = 1 if we want to suppress some interactive warnings,
55 # questions and mouse events
56 app.in_batch_mode = 1
57
58 # now we start the application in a separate thread to be able to manipulate it
59 t = threading.Thread( target=app.mainloop, name='app')
60 t.setDaemon( 1)
61 t.start()
62 </pre>
63
64 <p>The initial import depends on how you have installed BKChem. You can either make a symlink
65 or copy of the entire bkchem tree to the directory where this script is saved or you
66 can do a source code installation (on linux) and the package will be found by python automatically.
67 In the former case the import shown above applies, in the latter the import statement is only
68 <i>from bkchem import bkchem</i> (because only part of the directory tree is saved under
69 the python site-packages directory).</p>
70
71 <p>Because bkchem is a Tkinter application it has its own mainloop that runs all the
72 time the application exists. Therefor you have to run it in another thread in order to
73 be able to use it. Some other remarks are in the comments.</p>
74
75 <p>The code that does the actual work is pretty simple and straightforward:</p>
76
77 <pre>
78 # here comes the actual code
79
80 # we load the file
81 app.load_CDML( sys.argv[1])
82
83 # we take all molecules from the current paper, find all the double bonds,
84 # change their color to red and
85 for mol in app.paper.molecules:
86 for bond in mol.bonds:
87 if bond.order == 2:
88 bond.line_color = "#aa0000"
89 bond.redraw()
90
91 # finally we save the result and quit
92 app.save_CDML()
93 app.destroy()
94 </pre>
95
96 <p>We load the file, do the transformation, save the file and quit.</p>
97
98 <h3>Last word</h3>
99
100 <p>In the directory <i>doc</i> you can find an automatically generated documentation
101 of the BKChem API. It is not yet very stable, certainly not nice and polished, however
102 its the only one I can offer at this time :).</p>
103
104 <p>In any case you can simply ask me. The only limitation is that I will not answer
105 questions in the direction "What is python and how to make it print "hello world"?".
106 Also please use the bkchem mailing list for such questions so that everybody interested
107 can benefit from the discussion.</p>
108
109 </body>
110 </html>