Repository: zeppelin Updated Branches: refs/heads/master cc39f85a7 -> c854fda93
[DOCS] Separate "interpreter exec hooks (experimental)" from interpreter overview page ### What is this PR for? After #1470 merged, "(Experimental) Interpreter Execution Hooks" is added under https://zeppelin.apache.org/docs/0.7.0-SNAPSHOT/manual/interpreters.html page. But i think we need to keep this page as simple as possible since it's explaining the basic concept of Zeppelin interpreters. So I separated "(Experimental) Interpreter Execution Hooks" section from `interpreters.md` and created new page `interpreterexechooks.md`. And also fixed some markdown rendering issues. ### What type of PR is it? Documentation ### What is the Jira issue? N/A ### How should this be tested? Please see below screenshots :) ### Screenshots (if appropriate) - Before (under [manual/interpreter.md](https://zeppelin.apache.org/docs/0.7.0-SNAPSHOT/manual/interpreters.html#experimental-interpreter-execution-hooks) <img width="437" alt="screen shot 2016-12-15 at 5 05 49 pm]" src="https://cloud.githubusercontent.com/assets/10060731/21216362/a3bb89f0-c2e9-11e6-9678-8e6d8749229b.png";> - After <img width="300" alt="dropdown" src="https://cloud.githubusercontent.com/assets/10060731/21216570/dcca63f0-c2ea-11e6-90a9-969d363b423a.png";> <img width="437" alt="screen shot 2016-12-15 at 5 05 58 pm" src="https://cloud.githubusercontent.com/assets/10060731/21216363/a6c2d82e-c2e9-11e6-920c-a603e25e1699.png";> ### Questions: * Does the licenses files need update? no * Is there breaking changes for older versions? no * Does this needs documentation? no Author: AhyoungRyu <[email protected]> Closes #1768 from AhyoungRyu/separate-eventhook-section and squashes the following commits: ce19491 [AhyoungRyu] Separate 'interpreter exec hooks' from intp overview Project: http://git-wip-us.apache.org/repos/asf/zeppelin/repo Commit: http://git-wip-us.apache.org/repos/asf/zeppelin/commit/c854fda9 Tree: http://git-wip-us.apache.org/repos/asf/zeppelin/tree/c854fda9 Diff: http://git-wip-us.apache.org/repos/asf/zeppelin/diff/c854fda9 Branch: refs/heads/master Commit: c854fda9361d8c31b29cdaa45b69b7237ac34272 Parents: cc39f85 Author: AhyoungRyu <[email protected]> Authored: Thu Dec 15 17:09:40 2016 +0900 Committer: ahyoungryu <[email protected]> Committed: Sat Dec 17 21:50:39 2016 +0900 ---------------------------------------------------------------------- docs/_includes/themes/zeppelin/_navigation.html | 1 + docs/index.md | 1 + docs/manual/interpreterexechooks.md | 81 ++++++++++++++++++++ docs/manual/interpreters.md | 46 ----------- 4 files changed, 83 insertions(+), 46 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zeppelin/blob/c854fda9/docs/_includes/themes/zeppelin/_navigation.html ---------------------------------------------------------------------- diff --git a/docs/_includes/themes/zeppelin/_navigation.html b/docs/_includes/themes/zeppelin/_navigation.html index 6ed8d5a..0c66f3f 100644 --- a/docs/_includes/themes/zeppelin/_navigation.html +++ b/docs/_includes/themes/zeppelin/_navigation.html @@ -47,6 +47,7 @@ <!--<li><a href="{{BASE_PATH}}/manual/dynamicinterpreterload.html">Dynamic Interpreter Loading</a></li>--> <li><a href="{{BASE_PATH}}/manual/dependencymanagement.html">Interpreter Dependency Management</a></li> <li><a href="{{BASE_PATH}}/manual/userimpersonation.html">Interpreter User Impersonation</a></li> + <li><a href="{{BASE_PATH}}/manual/interpreterexechooks.html">Interpreter Execution Hooks (Experimental)</a></li> <li role="separator" class="divider"></li> <li class="title"><span><b>Available Interpreters</b><span></li> <li><a href="{{BASE_PATH}}/interpreter/alluxio.html">Alluxio</a></li> http://git-wip-us.apache.org/repos/asf/zeppelin/blob/c854fda9/docs/index.md ---------------------------------------------------------------------- diff --git a/docs/index.md b/docs/index.md index db5931e..5d964a1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -143,6 +143,7 @@ Join to our [Mailing list](https://zeppelin.apache.org/community.html) and repor * [Interpreter Installation](./manual/interpreterinstallation.html): Install not only community managed interpreters but also 3rd party interpreters * [Interpreter Dependency Management](./manual/dependencymanagement.html) when you include external libraries to interpreter * [Interpreter User Impersonation](./manual/userimpersonation.html) when you want to run interpreter as end user + * [Interpreter Execution Hooks](./manual/interpreterexechooks.html) to specify additional code to be executed by an interpreter at pre and post-paragraph code execution * Available Interpreters: currently, about 20 interpreters are available in Apache Zeppelin. ####Display System http://git-wip-us.apache.org/repos/asf/zeppelin/blob/c854fda9/docs/manual/interpreterexechooks.md ---------------------------------------------------------------------- diff --git a/docs/manual/interpreterexechooks.md b/docs/manual/interpreterexechooks.md new file mode 100644 index 0000000..d2411aa --- /dev/null +++ b/docs/manual/interpreterexechooks.md @@ -0,0 +1,81 @@ +--- +layout: page +title: "Interpreter Execution Hooks (Experimental)" +description: "Apache Zeppelin allows for users to specify additional code to be executed by an interpreter at pre and post-paragraph code execution." +group: manual +--- +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +{% include JB/setup %} + +# Interpreter Execution Hooks (Experimental) + +<div id="toc"></div> + +## Overview + +Apache Zeppelin allows for users to specify additional code to be executed by an interpreter at pre and post-paragraph code execution. +This is primarily useful if you need to run the same set of code for all of the paragraphs within your notebook at specific times. +Currently, this feature is only available for the spark and pyspark interpreters. +To specify your hook code, you may use `z.registerHook()`. +For example, enter the following into one paragraph: + +```python +%pyspark +z.registerHook("post_exec", "print 'This code should be executed before the parapgraph code!'") +z.registerHook("pre_exec", "print 'This code should be executed after the paragraph code!'") +``` + +These calls will not take into effect until the next time you run a paragraph. + + +In another paragraph, enter + +```python +%pyspark +print "This code should be entered into the paragraph by the user!" +``` + +The output should be: + +``` +This code should be executed before the paragraph code! +This code should be entered into the paragraph by the user! +This code should be executed after the paragraph code! +``` + +If you ever need to know the hook code, use `z.getHook()`: + +```python +%pyspark +print z.getHook("post_exec") + +print 'This code should be executed after the paragraph code!' +``` +Any call to `z.registerHook()` will automatically overwrite what was previously registered. +To completely unregister a hook event, use `z.unregisterHook(eventCode)`. +Currently only `"post_exec"` and `"pre_exec"` are valid event codes for the Zeppelin Hook Registry system. + +Finally, the hook registry is internally shared by other interpreters in the same group. +This would allow for hook code for one interpreter REPL to be set by another as follows: + +```scala +%spark +z.unregisterHook("post_exec", "pyspark") +``` + +The API is identical for both the spark (scala) and pyspark (python) implementations. + +### Caveats +Calls to `z.registerHook("pre_exec", ...)` should be made with care. If there are errors in your specified hook code, this will cause the interpreter REPL to become unable to execute any code pass the pre-execute stage making it impossible for direct calls to `z.unregisterHook()` to take into effect. Current workarounds include calling `z.unregisterHook()` from a different interpreter REPL in the same interpreter group (see above) or manually restarting the interpreter group in the UI. http://git-wip-us.apache.org/repos/asf/zeppelin/blob/c854fda9/docs/manual/interpreters.md ---------------------------------------------------------------------- diff --git a/docs/manual/interpreters.md b/docs/manual/interpreters.md index 4844f95..70b94d4 100644 --- a/docs/manual/interpreters.md +++ b/docs/manual/interpreters.md @@ -82,49 +82,3 @@ interpreter.start() The above code will start interpreter thread inside your process. Once the interpreter is started you can configure zeppelin to connect to RemoteInterpreter by checking **Connect to existing process** checkbox and then provide **Host** and **Port** on which interpreter process is listening as shown in the image below: <img src="../assets/themes/zeppelin/img/screenshots/existing_interpreter.png" width="450px"> - - -## (Experimental) Interpreter Execution Hooks - -Zeppelin allows for users to specify additional code to be executed by an interpreter at pre and post-paragraph code execution. This is primarily useful if you need to run the same set of code for all of the paragraphs within your notebook at specific times. Currently, this feature is only available for the spark and pyspark interpreters. To specify your hook code, you may use '`z.registerHook()`. For example, enter the following into one paragraph: - -```python -%pyspark -z.registerHook("post_exec", "print 'This code should be executed before the parapgraph code!'") -z.registerHook("pre_exec", "print 'This code should be executed after the paragraph code!'") -``` - -These calls will not take into effect until the next time you run a paragraph. In another paragraph, enter -```python -%pyspark -print "This code should be entered into the paragraph by the user!" -``` - -The output should be: -``` -This code should be executed before the paragraph code! -This code should be entered into the paragraph by the user! -This code should be executed after the paragraph code! -``` - -If you ever need to know the hook code, use `z.getHook()`: -```python -%pyspark -print z.getHook("post_exec") -``` -``` -print 'This code should be executed after the paragraph code!' -``` -Any call to `z.registerHook()` will automatically overwrite what was previously registered. To completely unregister a hook event, use `z.unregisterHook(eventCode)`. Currently only `"post_exec"` and `"pre_exec"` are valid event codes for the Zeppelin Hook Registry system. - -Finally, the hook registry is internally shared by other interpreters in the same group. This would allow for hook code for one interpreter REPL to be set by another as follows: - -```scala -%spark -z.unregisterHook("post_exec", "pyspark") -``` -The API is identical for both the spark (scala) and pyspark (python) implementations. - -### Caveats -Calls to `z.registerHook("pre_exec", ...)` should be made with care. If there are errors in your specified hook code, this will cause the interpreter REPL to become unable to execute any code pass the pre-execute stage making it impossible for direct calls to `z.unregisterHook()` to take into effect. Current workarounds include calling `z.unregisterHook()` from a different interpreter REPL in the same interpreter group (see above) or manually restarting the interpreter group in the UI. -
![https://cloud.githubusercontent.com/assets/10060731/21216362/a3bb89f0-c2e9-11e6-9678-8e6d8749229b.png"](https://cloud.githubusercontent.com/assets/10060731/21216362/a3bb89f0-c2e9-11e6-9678-8e6d8749229b.png"){kind=link}
![https://cloud.githubusercontent.com/assets/10060731/21216570/dcca63f0-c2ea-11e6-90a9-969d363b423a.png"](https://cloud.githubusercontent.com/assets/10060731/21216570/dcca63f0-c2ea-11e6-90a9-969d363b423a.png"){kind=link}
![https://cloud.githubusercontent.com/assets/10060731/21216363/a6c2d82e-c2e9-11e6-920c-a603e25e1699.png"](https://cloud.githubusercontent.com/assets/10060731/21216363/a6c2d82e-c2e9-11e6-920c-a603e25e1699.png"){kind=link}