Recording how to call super.init().

Author: cnuernber

docs/libpython-clj2.python.class.html

@@ -10,7 +10,12 @@
 will be presented as instance methods.
 Things in the cls hashmap had better be either atoms or already converted
 python objects.  You may get surprised otherwise; you have been warned.
-See the classes-test file in test/libpython-clj</p>
+See the classes-test file in test/libpython-clj.</p>
+<p>Calling <code>super.init()</code> may be done in a non-obvious way:</p>
+<pre><code class="language-clojure">(py. (py/get-item (py.. self -__class__ -__mro__) 1) __init__ self)
+</code></pre>
+<p>More feedback/research in this area is needed to integrated deeper into
+the python class hierarchies.</p>
 </div></div><div class="src-link"><a href="https://github.com/clj-python/libpython-clj/blob/master/src/libpython_clj2/python/class.clj#L70">view source</a></div></div><div class="public anchor" id="var-make-kw-instance-fn"><h3>make-kw-instance-fn</h3><div class="usage"><code>(make-kw-instance-fn clj-fn &amp; [{:keys [arg-converter result-converter], :or {arg-converter py-base/as-jvm}, :as options}])</code></div><div class="doc"><div class="markdown"><p>Make an instance function - a function which will be passed the 'this' object as
 it's first argument.  In this case the default behavior is to
 pass as-jvm bridged python object ptr args and kw dict args to the clojure function without

docs/libpython-clj2.python.html

@@ -123,7 +123,7 @@
 <p>A :pre-initialize-fn could for example shell out and setup a python
 virtual enviornment.</p>
 <p>The :post-initialize-fn can use all functions from ns <code>libpython-clj2.python</code>
-as libpython-clj is initialised alreday andc ould for example be used to validate
+as libpython-clj is initialised alreday and could for example be used to validate
 that later needed libraries can be loaded via calling <code>import-module</code>.</p>
 <p>The file MUST be named <code>python.edn</code> and be in the root of the classpath.
 With a <code>python.edn</code> file in place, the <code>initialize!</code> function may be called

docs/libpython-clj2.require.html

@@ -8,7 +8,7 @@
 scanning the module for metadata and dynamically building the Clojure namespace.</p>
 </div></div><div class="public anchor" id="var-import-python"><h3>import-python</h3><div class="usage"><code>(import-python)</code></div><div class="doc"><div class="markdown"><p>Loads python, python.list, python.dict, python.set, python.tuple,
 and python.frozenset.</p>
-</div></div><div class="src-link"><a href="https://github.com/clj-python/libpython-clj/blob/master/src/libpython_clj2/require.clj#L284">view source</a></div></div><div class="public anchor" id="var-require-python"><h3>require-python</h3><div class="usage"><code>(require-python req)</code><code>(require-python req &amp; reqs)</code></div><div class="doc"><div class="markdown"><h2>Basic usage</h2>
+</div></div><div class="src-link"><a href="https://github.com/clj-python/libpython-clj/blob/master/src/libpython_clj2/require.clj#L371">view source</a></div></div><div class="public anchor" id="var-require-python"><h3>require-python</h3><div class="usage"><code>(require-python req)</code><code>(require-python req &amp; reqs)</code></div><div class="doc"><div class="markdown"><h2>Basic usage</h2>
 <p>(require-python 'math)
 (math/sin 1.0) ;;=&gt; 0.8414709848078965</p>
 <p>(require-python '<a href="math :as maaaath">math :as maaaath</a>)</p>
@@ -40,8 +40,53 @@ <h2>Use with custom modules</h2>
 ..: the behavior mimics importlib.reload</p>
 <h2>Setting up classpath for custom modules</h2>
 <p>Note: you may need to setup your PYTHONPATH correctly.
-One technique to do this is, if your foo.py lives at
-/path/to/foodir/foo.py:</p>
+<strong>WARNING</strong>: This is very handy for local REPL development,
+..: if you are going to AOT classes,
+..: refer to the documentation on codegen
+..: or your AOT compilation will fail.
+If your foo.py lives at /path/to/foodir/foo.py, the easiest
+way to do it is:</p>
+<p>(require-python :from "/path/to/foodir"
+'foo) ;; or
+(require-python "/path/to/foodir"
+'foo) ;; or
+(require-python {:from "/path/to/foodir"}
+'foo)</p>
+<p>as you prefer.</p>
+<p>Additionally, if you want to keep the namespacing as you have
+it in Python, you may prefer to use a relative import
+starting from a location of your choosing. If your
+os.getcwd() =&gt; /some/path/foo,
+and your directory structure looks something like:</p>
+<p>/some $ tree
+.
+└── path
+├── baz
+│   └── quux.py
+└── foo
+└── bar.py</p>
+<p>(require-python :from "path"
+'<a href="baz.quux :as quux">baz.quux :as quux</a>
+:from "path/foo"
+'bar)</p>
+<p>is perfectly acceptable. It probably makes the most
+sense to keep you style consistent, but you can mix
+and match as you see fit between <path>, :from <path>,
+and {:from <path>}.  <path> can either be a file or a
+directory.  If it is a file, the Python path will be
+set to the directory containing that file.</path></path></path></path></p>
+<p>You may also stack several require-pythons under one path:</p>
+<p>(require-python {:from "dir-a"}
+'a
+'b
+'c
+{:from "dir-b"}
+'e.f
+'g
+{:from "dir-c}
+'hi.there)</p>
+<p>Other options more in keeping with traditional PYTHONPATH
+management include:</p>
 <p>(require-python 'sys)
 (py/call-attr (py/get-attr sys "path")
 "append"
@@ -68,4 +113,4 @@ <h2>For library developers</h2>
 those things designated by the module under the <strong>all</strong> attribute,
 you can do</p>
 <p>(require-python '<a href="operators :refer :*">operators :refer :*</a>)</p>
-</div></div><div class="src-link"><a href="https://github.com/clj-python/libpython-clj/blob/master/src/libpython_clj2/require.clj#L173">view source</a></div></div></div></body></html>
+</div></div><div class="src-link"><a href="https://github.com/clj-python/libpython-clj/blob/master/src/libpython_clj2/require.clj#L182">view source</a></div></div></div></body></html>

src/libpython_clj2/python/class.clj

@@ -72,7 +72,16 @@
   will be presented as instance methods.
   Things in the cls hashmap had better be either atoms or already converted
   python objects.  You may get surprised otherwise; you have been warned.
-  See the classes-test file in test/libpython-clj"
+  See the classes-test file in test/libpython-clj.
+
+
+  Calling `super.init()` may be done in a non-obvious way:
+
+```clojure
+(py. (py/get-item (py.. self -__class__ -__mro__) 1) __init__ self)
+```
+  More feedback/research in this area is needed to integrated deeper into
+  the python class hierarchies."
   [name bases cls-hashmap]
   (py-ffi/with-gil
     (py-ffi/with-decref