Skip to content

Latest commit

 

History

History
134 lines (92 loc) · 9.6 KB

python-fire.md

File metadata and controls

134 lines (92 loc) · 9.6 KB

Python Fire

  • Python Fire 用來寫給開發人員用的 CLI 是夠用的，但如果要開發 CLI 給其他人用，就不是那麼合適，從 -- --help 可以略知一二。

參考資料：

新手上路 ?? {: #getting-started }

Help, Usage

  • --help: Getting help - Using a CLI - Python Fire #ril

    • Let say you have a command line tool named widget that was made with Fire. How do you use this Fire CLI? The simplest way to get started is to run widget -- --help. This will give you usage information for your CLI. You can always append -- --help to any Fire command in order to get usage information for that command and any SUBCOMMANDS. 無法自訂參數 (即 function argument) 的說明? ==> 可以針對 command，但不能針對個別參數。
    • Additionally, help will be displayed if you hit an error using Fire. For example, if you try to pass too many or too few arguments to a function, then help will be displayed. Similarly, if you try to access a member that does not exist, or if you index into a list with too high an index, then help will be displayed.
    • The displayed help shows information about which PYTHON COMPONENT (這是 Fire 定義的東西) your command corresponds to, as well as usage information for how to extend that command.

  • Using Fire Flags - The Python Fire Guide - Python Fire #ril

    • You can add the help flag to any command to see help and usage information. Fire incorporates your DOCSTRINGS into the help and usage information that it generates. Fire will try to provide help even if you omit the isolated -- separating the flags from the Fire command, but may not always be able to, since help is a valid argument name (--help 會被當做參數傳入 function??). Use this feature like this: python example.py -- --help.

      以 examples/widget/widget.py 為例：

      $ python examples/widget/widget.py -- --help
Type:        Widget
String form: <__main__.Widget object at 0x106688f10>
File:        ~/work/_clone/python-fire/examples/widget/widget.py
<-- 因為 Widget class 本身沒有 docstring，所以沒有顯示

Usage:       widget
             widget bang
             widget whack <-- 可惜的是，就算 subcommand 有寫 docstring，這時候並不會印出來

$ python examples/widget/widget.py whack -- --help
Type:        instancemethod
String form: <bound method Widget.whack of <__main__.Widget object at 0x104ffff10>>
File:        ~/work/_clone/python-fire/examples/widget/widget.py
Line:        22
Docstring:   Prints "whack!" n times.

Usage:       widget whack [N]
             widget whack [--n N]

Sub-command ??

  • Grouping Commands - The Python Fire Guide - Python Fire

    Here's an example of how you might make a command line interface with GROUPED COMMANDS. 雖然這裡稱做 grouped commands，但 --help: Getting help - Using a CLI - Python Fire 也提到 "subcommand" 的說法。

    class IngestionStage(object):

  def run(self):
    return 'Ingesting! Nom nom nom...'

class DigestionStage(object):

  def run(self, volume=1):
    return ' '.join(['Burp!'] * volume)

  def status(self):
    return 'Satiated.'

class Pipeline(object):

  def __init__(self):
    self.ingestion = IngestionStage() <-- 用 attribute 表現 sub command!!
    self.digestion = DigestionStage()

  def run(self):
    self.ingestion.run()
    self.digestion.run()

if __name__ == '__main__':
  fire.Fire(Pipeline)

    Here's how this looks at the command line:

    $ python example.py run
Ingesting! Nom nom nom...
Burp!
$ python example.py ingestion run
Ingesting! Nom nom nom...
$ python example.py digestion run
Burp!
$ python example.py digestion status
Satiated.

REPL, Interactive Mode

  • Explore code in a Python REPL - Benefits - Python Fire

    • When you use the --interactive flag to enter an IPython REPL, it starts with variables and modules already defined for you. You don't need to waste time importing the modules you care about or defining the variables you're going to use, since Fire has already done so for you.

      實驗發現，會自動採用 IPyton，但環境內沒有 IPython 時還是可以進入 interactive mode，只是用起來沒那麼方便而已 (尤其是 auto-completion)。例如 python caculator.py -- --interactive

  • --interactive: Interactive mode - Using a CLI - Python Fire

    • Call widget -- --interactive or widget -- -i to enter interactive mode. This will put you in an IPython REPL, with the variable widget already defined. You can then explore the Python object that widget corresponds to interactively using Python.

      其中 widget 應該就是 python-fire/widget.py at master · google/python-fire，只是若要像 $ widget 這樣直接呼叫 (而非 $ python widget.py)，應該要加上 shebang (#!/usr/bin/env python) 並設定 executable bit 才行，不過這些在官方文件裡完全沒提到就是了。

      另外 interactive mode 下有 variable widget 可以調用? 試過 examples/widget/widget.py 真的可以：

      $ python examples/widget/widget.py -- --interactive
In [1]: widget
Out[1]: <__main__.Widget at 0x10b565f10>

      為什麼 widget 是個 Widget instance? 因為它用 fire.Fire(Widget(), name='widget') 的寫法，而非 fire.Fire(Widget, name='widget') (component 給 instance 而非 type)。

Testing ??

安裝設置 {: #setup }

參考資料 {: #reference }