Linux source install: Install a calibre environment module to ease the integration of calibre into other python projects

setup/install.py

@@ -137,8 +137,20 @@ class Develop(Command):
         self.setup_mount_helper()
         self.install_files()
         self.run_postinstall()
+        self.install_env_module()
         self.success()
 
+    def install_env_module(self):
+        import distutils.sysconfig as s
+        libdir = s.get_python_lib(prefix=self.opts.staging_root)
+        if os.path.exists(libdir):
+            path = os.path.join(libdir, 'init_calibre.py')
+            self.info('Installing calibre environment module: '+path)
+            with open(path, 'wb') as f:
+                f.write(HEADER.format(**self.template_args()))
+        else:
+            self.warn('Cannot install calibre environment module to: '+libdir)
+
     def setup_mount_helper(self):
         def warn():
             self.warn('Failed to compile mount helper. Auto mounting of',
@@ -180,13 +192,20 @@ class Develop(Command):
                     functions[typ]):
                 self.write_template(name, mod, func)
 
+    def template_args(self):
+        return {
+            'path':self.libdir,
+            'resources':self.sharedir,
+            'executables':self.bindir,
+            'extensions':self.j(self.libdir, 'calibre', 'plugins')
+            }
+
     def write_template(self, name, mod, func):
         template = COMPLETE_TEMPLATE if name == 'calibre-complete' else TEMPLATE
-        script = template.format(
-                module=mod, func=func,
-                path=self.libdir, resources=self.sharedir,
-                executables=self.bindir,
-                extensions=self.j(self.libdir, 'calibre', 'plugins'))
+        args = self.template_args()
+        args['module'] = mod
+        args['func'] = func
+        script = template.format(**args)
         path = self.j(self.staging_bindir, name)
         if not os.path.exists(self.staging_bindir):
             os.makedirs(self.staging_bindir)

src/calibre/manual/develop.rst

@@ -219,3 +219,30 @@ is great for testing a little snippet of code on the command line. It works in t
 can be used to execute your own python script. It works in the same way as passing the script to the python interpreter, except
 that the calibre environment is fully initialized, so you can use all the calibre code in your script.
 
+
+Using calibre in your projects
+----------------------------------------
+
+It is possible to directly use calibre functions/code in your python project. Two ways exist to do this:
+
+Binary install of calibre
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have a binary install of calibre, you can use the python interpreter bundled with calibre, like this::
+
+    calibre-debug -e /path/to/your/python/script.py
+
+Source install on linux
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In addition to using the above technique, if you do a source install on linux,
+you can also directly import calibre, as follows::
+
+    import init_calibre
+    import calibre
+
+    print calibre.__version__
+
+It is essential that you import the init_calibre module before any other calibre modules/packages as
+it sets up the interpreter to run calibre code.
+