|
14 | 14 | "cell_type": "markdown", |
15 | 15 | "metadata": {}, |
16 | 16 | "source": [ |
17 | | - "# fastscript\n", |
| 17 | + "# Script - command line interfaces\n", |
18 | 18 | "\n", |
19 | 19 | "> A fast way to turn your python function into a script." |
20 | 20 | ] |
|
26 | 26 | "Part of [fast.ai](https://www.fast.ai)'s toolkit for delightful developer experiences." |
27 | 27 | ] |
28 | 28 | }, |
29 | | - { |
30 | | - "cell_type": "markdown", |
31 | | - "metadata": {}, |
32 | | - "source": [ |
33 | | - "## Install" |
34 | | - ] |
35 | | - }, |
36 | | - { |
37 | | - "cell_type": "markdown", |
38 | | - "metadata": {}, |
39 | | - "source": [ |
40 | | - "Either `pip install fastscript` or `conda install -c fastai fastscript`" |
41 | | - ] |
42 | | - }, |
43 | 29 | { |
44 | 30 | "cell_type": "markdown", |
45 | 31 | "metadata": {}, |
|
53 | 39 | "source": [ |
54 | 40 | "Sometimes, you want to create a quick script, either for yourself, or for others. But in Python, that involves a whole lot of boilerplate and ceremony, especially if you want to support command line arguments, provide help, and other niceties. You can use [argparse](https://docs.python.org/3/library/argparse.html) for this purpose, which comes with Python, but it's complex and verbose.\n", |
55 | 41 | "\n", |
56 | | - "`fastscript` makes life easier. There are much fancier modules to help you write scripts (we recommend [Python Fire](https://github.com/google/python-fire), and [Click](https://click.palletsprojects.com/en/7.x/) is also popular), but fastscript is very fast and very simple. In fact, it's <50 lines of code! Basically, it's just a little wrapper around `argparse` that uses modern Python features and some thoughtful defaults to get rid of the boilerplate.\n", |
| 42 | + "`fastcore.script` makes life easier. There are much fancier modules to help you write scripts (we recommend [Python Fire](https://github.com/google/python-fire), and [Click](https://click.palletsprojects.com/en/7.x/) is also popular), but fastcore.script is very fast and very simple. In fact, it's <50 lines of code! Basically, it's just a little wrapper around `argparse` that uses modern Python features and some thoughtful defaults to get rid of the boilerplate.\n", |
57 | 43 | "\n", |
58 | | - "For full details, see the [docs](https://fastscript.fast.ai) for `core`." |
| 44 | + "For full details, see the [docs](https://fastcore.script.fast.ai) for `core`." |
59 | 45 | ] |
60 | 46 | }, |
61 | 47 | { |
|
72 | 58 | "Here's a complete example:\n", |
73 | 59 | "\n", |
74 | 60 | "```python\n", |
75 | | - "from fastscript import *\n", |
| 61 | + "from fastcore.script import *\n", |
76 | 62 | "@call_parse\n", |
77 | 63 | "def main(msg:Param(\"The message\", str),\n", |
78 | 64 | " upper:Param(\"Convert to uppercase?\", bool_arg)=False):\n", |
|
82 | 68 | "If you copy that info a file and run it, you'll see:\n", |
83 | 69 | "\n", |
84 | 70 | "```\n", |
85 | | - "$ python examples/test_fastscript.py\n", |
86 | | - "usage: test_fastscript.py [-h] [--upper UPPER] msg\n", |
87 | | - "test_fastscript.py: error: the following arguments are required: msg\n", |
| 71 | + "$ python test_fastcore.script.py\n", |
| 72 | + "usage: test_fastcore.script.py [-h] [--upper UPPER] msg\n", |
| 73 | + "test_fastcore.script.py: error: the following arguments are required: msg\n", |
88 | 74 | "```\n", |
89 | 75 | "\n", |
90 | 76 | "As you see, we didn't need any `if __name__ == \"__main__\"`, we didn't have to parse arguments, we just wrote a function, added a decorator to it, and added some annotations to our function's parameters. As a bonus, we can also use this function directly from a REPL such as Jupyter Notebook - it's not just for command line scripts!" |
|
101 | 87 | "cell_type": "markdown", |
102 | 88 | "metadata": {}, |
103 | 89 | "source": [ |
104 | | - "Each parameter in your function should have an annotation `Param(...)` (as in the example above). You can pass the following when calling `Param`: `help`,`type`,`opt`,`action`,`nargs`,`const`,`choices`,`required` . Except for `opt`, all of these are just passed directly to `argparse`, so you have all the power of that module at your disposal. Generally you'll want to pass at least `help` (since this is provided as the help string for that parameter) and `type` (to ensure that you get the type of data you expect). `opt` is a bool that defines whether a param is optional or required (positional) - but you'll generally not need to set this manually, because fastscript will set it for you automatically based on *default* values.\n", |
| 90 | + "Each parameter in your function should have an annotation `Param(...)` (as in the example above). You can pass the following when calling `Param`: `help`,`type`,`opt`,`action`,`nargs`,`const`,`choices`,`required` . Except for `opt`, all of these are just passed directly to `argparse`, so you have all the power of that module at your disposal. Generally you'll want to pass at least `help` (since this is provided as the help string for that parameter) and `type` (to ensure that you get the type of data you expect). `opt` is a bool that defines whether a param is optional or required (positional) - but you'll generally not need to set this manually, because fastcore.script will set it for you automatically based on *default* values.\n", |
105 | 91 | "\n", |
106 | 92 | "You should provide a default (after the `=`) for any *optional* parameters. If you don't provide a default for a parameter, then it will be a *positional* parameter." |
107 | 93 | ] |
|
117 | 103 | "cell_type": "markdown", |
118 | 104 | "metadata": {}, |
119 | 105 | "source": [ |
120 | | - "There's a really nice feature of pip/setuptools that lets you create commandline scripts directly from functions, makes them available in the `PATH`, and even makes your scripts cross-platform (e.g. in Windows it creates an exe). fastscript supports this feature too. To use it, follow [this example](fastscript/test_cli.py) from `fastscript/test_cli.py` in the repo. As you see, it's basically identical to the script example above, except that we can treat it as a module. The trick to making this available as a script is to add a `console_scripts` section to your setup file, of the form: `script_name=module:function_name`. E.g. in this case we use: `test_fastscript=fastscript.test_cli:main`. With this, you can then just type `test_fastscript` at any time, from any directory, and your script will be called (once it's installed using one of the methods below).\n", |
| 106 | + "There's a really nice feature of pip/setuptools that lets you create commandline scripts directly from functions, makes them available in the `PATH`, and even makes your scripts cross-platform (e.g. in Windows it creates an exe). fastcore.script supports this feature too. The trick to making a function available as a script is to add a `console_scripts` section to your setup file, of the form: `script_name=module:function_name`. E.g. in this case we use: `test_fastcore.script=fastcore.script.test_cli:main`. With this, you can then just type `test_fastcore.script` at any time, from any directory, and your script will be called (once it's installed using one of the methods below).\n", |
121 | 107 | "\n", |
122 | 108 | "You don't actually have to write a `setup.py` yourself. Instead, just use [nbdev](https://nbdev.fast.ai). Then modify `settings.ini` as appropriate for your module/script. To install your script directly, you can type `pip install -e .`. Your script, when installed this way (it's called an [editable install](http://codumentary.blogspot.com/2014/11/python-tip-of-year-pip-install-editable.html), will automatically be up to date even if you edit it - there's no need to reinstall it after editing. With nbdev you can even make your module and script available for installation directly from pip and conda by running `make release`." |
123 | 109 | ] |
|
182 | 168 | "source": [ |
183 | 169 | "Each parameter in your function should have an annotation `Param(...)`. You can pass the following when calling `Param`: `help`,`type`,`opt`,`action`,`nargs`,`const`,`choices`,`required` (i.e. it takes the same parameters as `argparse.ArgumentParser.add_argument`, plus `opt`). Except for `opt`, all of these are just passed directly to `argparse`, so you have all the power of that module at your disposal. Generally you'll want to pass at least `help` (since this is provided as the help string for that parameter) and `type` (to ensure that you get the type of data you expect).\n", |
184 | 170 | "\n", |
185 | | - "`opt` is a bool that defines whether a param is optional or required (positional) - but you'll generally not need to set this manually, because fastscript will set it for you automatically based on *default* values. You should provide a default (after the `=`) for any *optional* parameters. If you don't provide a default for a parameter, then it will be a *positional* parameter." |
| 171 | + "`opt` is a bool that defines whether a param is optional or required (positional) - but you'll generally not need to set this manually, because fastcore.script will set it for you automatically based on *default* values. You should provide a default (after the `=`) for any *optional* parameters. If you don't provide a default for a parameter, then it will be a *positional* parameter." |
186 | 172 | ] |
187 | 173 | }, |
188 | 174 | { |
|
380 | 366 | "metadata": {}, |
381 | 367 | "outputs": [], |
382 | 368 | "source": [ |
383 | | - "test_eq(os.system('test_fastscript \"Test if this still works\"'), 0)\n", |
| 369 | + "test_eq(os.system('test_fastcore.script \"Test if this still works\"'), 0)\n", |
384 | 370 | "test_eq(test_add(1,2), 3)" |
385 | 371 | ] |
386 | 372 | }, |
387 | 373 | { |
388 | 374 | "cell_type": "markdown", |
389 | 375 | "metadata": {}, |
390 | 376 | "source": [ |
391 | | - "This is the main way to use `fastscript`; decorate your function with `call_parse`, add `Param` annotations as shown above, and it can then be used as a script." |
| 377 | + "This is the main way to use `fastcore.script`; decorate your function with `call_parse`, add `Param` annotations as shown above, and it can then be used as a script." |
392 | 378 | ] |
393 | 379 | }, |
394 | 380 | { |
|
0 commit comments