The OSDU CLI uses the [Python Click](https://click.palletsprojects.com/en/8.0.x/) package to simplify the development experience. Code is located under the _src/osducli_ folder as follows:
```text
├── commands <- CLI Commands grouped by folder
| ├── config/ <- Configuration commands
| ├── dataload/ <- Data loading commands
| ├── entitlements/ <- Entitlements commands
| ├── legal/ <- Legal commands
| ├── list/ <- List information
| ├── schema/ <- Schema commands
| ├── search/ <- Search commands
| ├── status/ <- Status commands
| ├── storage/ <- Storage commands
| ├── unit/ <- Unit commands
| ├── version/ <- Version command
| └── workflow/ <- Workflow commands
├── util <- Utility / helper functions
| ├── exceptions.py <- CLI specific exceptions
| ├── file.py <- File helper functions
| └── prompt.py <- Prompting for information
├── __init__.py <- Contains the CLI version number
├── __main__.py <- Main entry point and command loading
├── click_cli.py <- Click helpers including state and command decorators
├── cliclient.py <- Http client for working against OSDU API's
├── config.py <- For working with CLI configuration
├── log.py <- Logging functionality
└── state.py <- For working with CLI state
```
## Commands
The commands displayed in the CLI are automatically loaded based upon the file / folder structure in the _src/osducli/comands_ folder. All modules that contain a __click_command_ function are added as commands with the function docstring being used as the command help text. Subfolders can be used to provide groups of commands. In this case the docstring in the module _\_\_init\_\_.py_ is used as the group help text.
__click_command_ functions (commands) should be decorated with the following:
- _@handle_cli_exceptions_ - this provides common exception handling.
- One of:
- _@global_params_ - this provides --debug and --config parameters and would typically be used if you have a command that doesn't return any output.
- _@command_with_output_ - should be used when you are returning information. This decorator provides the --output and --query parameters that allow for customising the output format and specifying a jmes query to filter output. It also includes _global_params_
## Calling OSDU API's
The cliclient.py module contains the _CliOsduClient _class that simplifies interacting with the OSDU backend. _CliOsduClient _currently uses the separate osdu-sdk package which contains backend code seperated out from the original CLI. Future updates might align with a future OSDU standard SDK. Using the _CliOsduClient_ you can make HTTP REST calls direclty agains the API's. Certain API's e.g. Search have wrapper classes that simplify the API usage.
## Testing
Test cases are provided for certain functionality and are located under the _tests_ folder. Extending test coverage is an identified improvement area.
### Testing of commands
Testing of commands should include test cases for:
- _CLI Interface_ - check that cli commands call the backend functions correctly.
- _test_cli_[xxx_]required_params()_ - for testing required parameters
- _test_cli_[xxx_]optional_params()_ - for testing default (optional) parameters
- _test_cli_xxx()_ - for testing specific combinations of parameters
- _Function Tests_ - for testing specific functions.
## Overview
The OSDU CLI uses the [Python Click](https://click.palletsprojects.com/en/8.0.x/) package to simplify the development experience. Code is located under the _src/osducli_ folder as follows:
| ├── crs/ <- Coordinate Reference System (CRS) service commands
| ├── dataload/ <- Data loading commands
| ├── entitlements/ <- Entitlements commands
| ├── file/ <- File commands
| ├── legal/ <- Legal commands
| ├── list/ <- List information
| ├── schema/ <- Schema commands
| ├── search/ <- Search commands
| ├── status/ <- Status commands
| ├── storage/ <- Storage commands
| ├── unit/ <- Unit commands
| ├── version/ <- Version command
| ├── wellbore-ddms/ <- Wellbore ddms commands
| └── workflow/ <- Workflow commands
├── util <- Utility / helper functions
| ├── exceptions.py <- CLI specific exceptions
| ├── file.py <- File helper functions
| ├── prompt.py <- Prompting for information
| ├── pypi.py <- Get latest version from pypi
| └── service_info.py <- Service information
├── __init__.py <- Contains the CLI version number
├── __main__.py <- Main entry point and command loading
├── click_cli.py <- Click helpers including state and command decorators
├── cliclient.py <- Http client for working against OSDU API's
├── config.py <- For working with CLI configuration
├── log.py <- Logging functionality
└── state.py <- For working with CLI state
```
## Commands
The commands displayed in the CLI are automatically loaded based upon the file / folder structure in the _src/osducli/comands_ folder. All modules that contain a __click_command_ function are added as commands with the function docstring being used as the command help text. Subfolders can be used to provide groups of commands. In this case the docstring in the module _\_\_init\_\_.py_ is used as the group help text.
__click_command_ functions (commands) should be decorated with the following:
- _@handle_cli_exceptions_ - this provides common exception handling.
- One of:
- _@global_params_ - this provides --debug and --config parameters and would typically be used if you have a command that doesn't return any output.
- _@command_with_output_ - should be used when you are returning information. This decorator provides the --output and --query parameters that allow for customising the output format and specifying a jmes query to filter output. It also includes _global_params_
## Calling OSDU API's
The cliclient.py module contains the _CliOsduClient _class that simplifies interacting with the OSDU backend. _CliOsduClient _currently uses the separate osdu_api package which is the OSDU forum maintained Python SDK. Using the _CliOsduClient_ you can make HTTP REST calls directly against the OSDU API's. Certain API's e.g. Search have wrapper classes that simplify the API usage.
## Testing
Test cases are provided for certain functionality and are located under the _tests_ folder. Extending test coverage is an identified improvement area.
### Testing of commands
Testing of commands should include test cases for:
- _CLI Interface_ - check that cli commands call the backend functions correctly.
- _test_cli_[xxx_]required_params()_ - for testing required parameters
- _test_cli_[xxx_]optional_params()_ - for testing default (optional) parameters
- _test_cli_xxx()_ - for testing specific combinations of parameters
- _Function Tests_ - for testing specific functions.
Not all tests adhere to the above convention yet. See _tests\commands\legal\*_ for examples.
