cytomining / cytomining/CytoTable
Enhance documentation and typing for interface composability
- Dominant language
- Python
- Stars
- 21
- Forks
- 6
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 6
Description
> "Later on, while documenting the interface (both public and private) I think it'd be helpful for a reader to know how the methods within the library are composed or could be composed. You could do this by calling out methods that rely on the current method or vice versa in the docs (e.g., "called by X(), used as input to Y()"), to at least demonstrate one example of how they could be composed. If you wanted to take this idea further, you could define named types (https://docs.python.org/3/library/typing.html#type-aliases) that are returned or taken as arguments to the methods. For example, `to_parquet()` takes several arguments whose types are `Union[List[str], Tuple[str, ...]]`; if you were to instead distinguish each argument as a type of the thing you expect it to take, you could simply read the signatures of `to_parquet()` and other methods in the library to see how you'd chain them together.
> On that note, you could probably save yourself some typing (no pun intended) by aliasing `Union[List[str], Tuple[str, ...]]` as, say, `IterableCollection`. ..."
_Originally posted by @falquaddoomi in https://github.com/cytomining/pycytominer-transform/pull/22#discussion_r1082906340_
Contributor guide
Research direction
Start by reviewing the interface documentation and the signatures of methods such as to_parquet(), then inspect the typing guidance linked in the issue and the original pull-request discussion. Define the scope of composability examples and named aliases before changing anything; done means the relevant public and private methods document their relationships and their signatures consistently expose the intended types.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100