From e0320e0765ebcdb621f0e2d3c6fb3035855c2404 Mon Sep 17 00:00:00 2001
From: Kovid Goyal <kovid@kovidgoyal.net>
Date: Wed, 10 Feb 2010 22:12:22 -0700
Subject: [PATCH] Linux source install: Install a calibre environment module to
 ease the integration of calibre into other python projects

---
 setup/install.py               | 29 ++++++++++++++++++++++++-----
 src/calibre/manual/develop.rst | 27 +++++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 5 deletions(-)

diff --git a/setup/install.py b/setup/install.py
index 56546cd7d4..8424280e95 100644
--- a/setup/install.py
+++ b/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)
diff --git a/src/calibre/manual/develop.rst b/src/calibre/manual/develop.rst
index b9cebcab3d..5f359ad713 100644
--- a/src/calibre/manual/develop.rst
+++ b/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.
+