DiamondLightSource / DiamondLightSource/httomo
Document method wrappers which transform the `auto` value for a parameter
- Dominant language
- Python
- Stars
- 10
- Forks
- 5
- Avg merge
- 5d 17h
- Merged PRs (30d)
- 1
Description
The `auto` value can be used for a few different parameters of different methods, such as:
- `axis` of a dezinger method wrapped by `DezingingWrapper`
https://github.com/DiamondLightSource/httomo/blob/74b94c9140945211657617c00b7ff9694455d60d/httomo/method_wrappers/dezinging.py#L51-L58
- `axis` of an image saver method (though doesn't appear in the image saver wrapper, but in the generic wrapper)
https://github.com/DiamondLightSource/httomo/blob/74b94c9140945211657617c00b7ff9694455d60d/httomo/method_wrappers/generic.py#L264-L269
The underlying methods from their respective libraries have the `axis` parameter which don't have `auto` as a possible value, but in httomo YAML pipeline config files we have introduced the ability to override the value of this `axis` parameter and have the associated wrapper transform the `"auto"` into something else on behalf of the users.
This results in the YAML config file for a method using the `auto` value presenting a different public API compared to the public API of the method function in its respective library (ie, its type signature): in httomo, the value of `axis` is presented to be able to be `auto`, but in the method function itself, the value of `axis` is an `int`. These will have different types:
- allowing `axis` to have a value of `auto` in addition to integers will have the type `Union[Literal["auto"], int]`
- allowing `axis` to only have an integer value will have type `int`
The method wrappers doing this transformation from `auto` to an `int` (which form the perspective of types is a conversion from a `Union[Literal["auto"], int]` to an `int`) aren't documented as doing so.
Documenting the method wrappers to at least have some information about the transformation being done can help mitigate confusion regarding the two conflicting public API's that are exposed by httomo's YAML config files vs. the method function's documentation.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading httomo/method_wrappers/dezinging.py around lines 51–58 and httomo/method_wrappers/generic.py around lines 264–269. Identify the wrappers that accept auto for axis and document how each transforms it before calling the underlying method. Done means the wrapper documentation clearly explains the YAML value and the resulting method parameter type.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100