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:
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
| ├── storage/ <- Storage commands
| ├── dataload/ <- Data loading commands
| ├── unit/ <- Unit commands
| ├── entitlements/ <- Entitlements commands
| ├── version/ <- Version command
| ├── file/ <- File commands
| └── workflow/ <- Workflow commands
| ├── legal/ <- Legal commands
├── util <- Utility / helper functions
| ├── list/ <- List information
| ├── exceptions.py <- CLI specific exceptions
| ├── schema/ <- Schema commands
| ├── file.py <- File helper functions
| ├── search/ <- Search commands
| └── prompt.py <- Prompting for information
| ├── status/ <- Status commands
├── __init__.py <- Contains the CLI version number
| ├── storage/ <- Storage commands
├── __main__.py <- Main entry point and command loading
| ├── unit/ <- Unit commands
├── click_cli.py <- Click helpers including state and command decorators
| ├── version/ <- Version command
├── cliclient.py <- Http client for working against OSDU API's
| ├── wellbore-ddms/ <- Wellbore ddms commands
├── config.py <- For working with CLI configuration
| └── workflow/ <- Workflow commands
├── log.py <- Logging functionality
├── util <- Utility / helper functions
└── state.py <- For working with CLI state
| ├── exceptions.py <- CLI specific exceptions
```
| ├── file.py <- File helper functions
| ├── prompt.py <- Prompting for information
## Commands
| ├── pypi.py <- Get latest version from pypi
| └── service_info.py <- Service information
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.
├── __init__.py <- Contains the CLI version number
├── __main__.py <- Main entry point and command loading
__click_command_ functions (commands) should be decorated with the following:
├── click_cli.py <- Click helpers including state and command decorators
├── cliclient.py <- Http client for working against OSDU API's
- _@handle_cli_exceptions_ - this provides common exception handling.
├── config.py <- For working with CLI configuration
- One of:
├── log.py <- Logging functionality
- _@global_params_ - this provides --debug and --config parameters and would typically be used if you have a command that doesn't return any output.
└── state.py <- For working with CLI state
- _@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
## Commands
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.
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.
## Testing
__click_command_ functions (commands) should be decorated with the following:
Test cases are provided for certain functionality and are located under the _tests_ folder. Extending test coverage is an identified improvement area.
- _@handle_cli_exceptions_ - this provides common exception handling.
- One of:
### Testing of commands
- _@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_
Testing of commands should include test cases for:
- _CLI Interface_ - check that cli commands call the backend functions correctly.
## Calling OSDU API's
- _test_cli_[xxx_]required_params()_ - for testing required parameters
- _test_cli_[xxx_]optional_params()_ - for testing default (optional) parameters
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.
- _test_cli_xxx()_ - for testing specific combinations of parameters
- _Function Tests_ - for testing specific functions.
## 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.
Not all tests adhere to the above convention yet. See _tests\commands\legal\*_ for examples.
