Skip to content

What is the policy regarding contributing type annotations? #243

@nathanjmcdougall

Description

@nathanjmcdougall

Hi,

What is the policy for contributing to type annotations? Are such contributions welcome?

My motivation for having high-quality type annotations is as follows:

  • When using pins-python, type annotations can improve the user experience for editors that use type-based syntax highlighting.
  • Type annotations can improve the user experience for users who are using type checking tools such as mypy.
  • When contributing to pins-python, type annotations serve as a form of documentation that make it easier to understand the codebase. I am currently trying to get my head around things 😄
     
    Some considerations:
  • Perhaps a pre-requisite is that a type checker is configured for the project (to ensure annotations are actually correct). Would you be open to this?
  • Some functions e.g. pins.versions.version_setup are currently unannotated but annotating them would introduce a cyclic dependency which could not be fixed without from future import __annotations__ or refactoring. Personally, I think refactoring in such cases can introduce clarity but there are definitely trade-offs. It would be good to know if this sort of refactoring is "off limits".
  • Some functions such as pins.boards.BaseBoard.pin_versions could have more narrowly scoped types using @overload to differentiate cases. You may find the complexity this introduces to be unacceptable, it would be good to know if this is the case.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions