|
|
# Creating Your Own Console Line Interface Functionality
|
|
|
# How to Add a Custom Command-Line Interface Command
|
|
|
|
|
|
To add a new command to the NES CLI, follow these steps:
|
|
|
Follow the steps below to add a new command to the NES CLI:
|
|
|
|
|
|
### 1. Create the script with the desired functionality
|
|
|
## Command Summary Table
|
|
|
|
|
|
Create a new Python script in the `nes/entrypoints/` directory, for example, `my_function.py`.
|
|
|
This script should define the function that implements your command's logic.
|
|
|
| Command | Description |
|
|
|
|-----------|-------------------------------------------------|
|
|
|
| `check` | Check for NaN and Inf values in a NetCDF file |
|
|
|
| `reorder` | Convert longitudes from [0, 360] to [-180, 180] |
|
|
|
|
|
|
```python
|
|
|
# nes/entrypoints/my_function.py
|
|
|
### 1. Create a Script for Your Command
|
|
|
|
|
|
def my_function(args):
|
|
|
"""
|
|
|
Implement the functionality of your command here.
|
|
|
Args:
|
|
|
args: Parsed command-line arguments.
|
|
|
"""
|
|
|
print("Executing my_function with arguments:", args)
|
|
|
```
|
|
|
Create a new Python script in the `nes/entrypoints/` directory, such as `my_function.py`.
|
|
|
This script should define the function that implements the logic for your command.
|
|
|
|
|
|
### 2. Expose the function in `__init__.py`
|
|
|
```python
|
|
|
# nes/entrypoints/my_function.py
|
|
|
|
|
|
Import and expose your function in the `nes/entrypoints/__init__.py` file to make it available for CLI registration.
|
|
|
def my_function(args):
|
|
|
"""
|
|
|
Implement the logic for your command here.
|
|
|
Args:
|
|
|
args: Parsed command-line arguments.
|
|
|
"""
|
|
|
print("Executing my_function with arguments:", args)
|
|
|
```
|
|
|
|
|
|
### 2. Expose the Function in `__init__.py`
|
|
|
|
|
|
To make your function available for CLI registration, import and expose it in `nes/entrypoints/__init__.py`.
|
|
|
|
|
|
```python
|
|
|
# nes/entrypoints/__init__.py
|
|
|
|
|
|
from .my_function import my_function
|
|
|
|
|
|
__all__ = [..., 'my_function']
|
|
|
```
|
|
|
|
|
|
### 3. Register the Command in `cli.py`
|
|
|
|
|
|
Add a helper function in `nes/entrypoints/cli.py` to register your command's subparser.
|
|
|
This function should add the subparser and specify the handler function.
|
|
|
|
|
|
```python
|
|
|
# nes/entrypoints/__init__.py
|
|
|
```python
|
|
|
# nes/entrypoints/cli.py
|
|
|
|
|
|
from .my_function import my_function
|
|
|
|
|
|
__all__ = [..., 'my_function']
|
|
|
```
|
|
|
def _add_my_function_subparser(subparsers):
|
|
|
from nes.entrypoints import my_function
|
|
|
|
|
|
### 3. Register the command in `cli.py`
|
|
|
parser = subparsers.add_parser('my_function', help='Description of the my_function command')
|
|
|
# Add any command-line arguments here
|
|
|
parser.add_argument('--option', type=str, help='An example option')
|
|
|
parser.set_defaults(func=my_function)
|
|
|
```
|
|
|
|
|
|
### 4. Register the Subparser in `main()`
|
|
|
|
|
|
Add a helper function to register your command's subparser in `nes/entrypoints/cli.py`.
|
|
|
This function should add the subparser and specify the handler function.
|
|
|
Within the `main()` function in `cli.py`, call `_add_my_function_subparser()` to register your command with the CLI.
|
|
|
|
|
|
```python
|
|
|
# nes/entrypoints/cli.py
|
|
|
```python
|
|
|
# nes/entrypoints/cli.py
|
|
|
|
|
|
def _add_my_function_subparser(subparsers):
|
|
|
from nes.entrypoints import my_function
|
|
|
|
|
|
parser = subparsers.add_parser('my_function', help='Description of my_function command')
|
|
|
# Add any command-line arguments here
|
|
|
parser.add_argument('--option', type=str, help='An example option')
|
|
|
parser.set_defaults(func=my_function)
|
|
|
```
|
|
|
def main():
|
|
|
...
|
|
|
# Add subcommands
|
|
|
_add_check_subparser(subparsers)
|
|
|
_add_reorder_subparser(subparsers)
|
|
|
# Register your custom command here
|
|
|
_add_my_function_subparser(subparsers)
|
|
|
...
|
|
|
```
|
|
|
|
|
|
### 4. Call the subparser registration in `main()`
|
|
|
### 5. Update Documentation
|
|
|
|
|
|
Inside the `main()` function of `cli.py`, call `_add_my_function()` to register your command with the CLI.
|
|
|
Update the [wiki User Guide](UserGuide) with instructions on how to use your new command.
|
|
|
|
|
|
```python
|
|
|
# nes/entrypoints/cli.py
|
|
|
### 6. Release
|
|
|
|
|
|
def main():
|
|
|
...
|
|
|
# Add subcommands
|
|
|
_add_check_subparser(subparsers)
|
|
|
_add_reorder_subparser(subparsers)
|
|
|
# Register your command here
|
|
|
_add_my_function_subparser(subparsers)
|
|
|
...
|
|
|
```
|
|
|
After testing and documenting your command, submit a merge request to the master branch.
|
|
|
|
|
|
## Usage Example
|
|
|
|
|
|
After completing these steps, you can run your new command from the terminal:
|
|
|
After completing the steps above, you can run your new command from the terminal:
|
|
|
|
|
|
```bash
|
|
|
nes my_function --option example_value
|
... | ... | @@ -79,4 +94,4 @@ or |
|
|
python -m nes.entrypoints.cli my_function --option example_value
|
|
|
```
|
|
|
|
|
|
This will execute the `my_function` command with the provided option. |
|
|
\ No newline at end of file |
|
|
This will execute the `my_function` command with the specified option. |
|
|
\ No newline at end of file |