DiamondLightSource / DiamondLightSource/httomo

Document method wrappers which transform the `auto` value for a parameter

Open Beginner friendly
#547 0 comments 0 reactions 0 assignees View on GitHub
documentation
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.