The API endpoints are auto-generated attributes attached to a civis.APIClient instance. Since dynamically generated objects don’t play nice with static type checkers (such as those embedded in an IDE as well as tools like mypy), writing code to hit the Civis API via a civis.APIClient instance has been somewhat prone to errors due to the lack of IDE support. This pull request adds a stub filesrc/civis/client.pyi for the API endpoints as attributes attached to civis.APIClient, so that our IDE can now help us catch potential coding errors -- see the screen captures below for PyCharm and VS Code.
Related changes:
Given the relatively large file size of the stub file, we can somewhat mitigate the increase in package size by adopting the repo structure of src/ and tests/ at the repo root level, so that the test suite isn’t included in the distributed package.
The module civis.py with a less descriptive name, where the APIClient class is defined, has been renamed client.py. This is why the corresponding stub file needs to be named client.pyi.
Having the stub file for the API endpoints has made it much easier to fix several minor long-standing API doc issues, mostly about docstring formatting.
PyCharm:
VS Code:
[x] (For Civis employees only) Reference to a relevant ticket in the pull request title
[x] Changelog entry added to CHANGELOG.md at the repo's root level
[x] Description of change in the pull request description
[x] If applicable, unit tests have been added and/or updated
The API endpoints are auto-generated attributes attached to a
civis.APIClientinstance. Since dynamically generated objects don’t play nice with static type checkers (such as those embedded in an IDE as well as tools like mypy), writing code to hit the Civis API via acivis.APIClientinstance has been somewhat prone to errors due to the lack of IDE support. This pull request adds a stub filesrc/civis/client.pyifor the API endpoints as attributes attached tocivis.APIClient, so that our IDE can now help us catch potential coding errors -- see the screen captures below for PyCharm and VS Code.Related changes:
src/andtests/at the repo root level, so that the test suite isn’t included in the distributed package.civis.pywith a less descriptive name, where theAPIClientclass is defined, has been renamedclient.py. This is why the corresponding stub file needs to be namedclient.pyi.PyCharm:
VS Code:
CHANGELOG.mdat the repo's root level