Skip to content

Improved rendering of python function params and docstrings in IDEs#10331

Merged
spacether merged 1 commit intoOpenAPITools:masterfrom
bflaton:python-client-docstring
Sep 6, 2021
Merged

Improved rendering of python function params and docstrings in IDEs#10331
spacether merged 1 commit intoOpenAPITools:masterfrom
bflaton:python-client-docstring

Conversation

@bflaton
Copy link
Contributor

@bflaton bflaton commented Sep 6, 2021 •
edited
Loading

Rationale: IDEs like pycharm don't render the docstrings from the generated code well because of the Endpoint indirection that currently exists in the code. The proposed change put the actual functions on the api, which enables the IDE to both give parameter hints as well as render proper documentation.

Endpoints are still accessible in generated code, mainly to satisfy some test cases. Maybe a cleaner way to go about testing settings on endpoints would be to inject something like an Endpoint factory into the api classes, which test cases can use to assert stuff. But in order to make the PR as small as possible, I left that change out.

The only changes that I needed to make to the test cases was to still have them refer the endpoints, since their old names are now used by the newly introduced functions.

PR checklist

  • Read the contribution guidelines.
  • Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
  • Run the following to build the project and update samples: 
    ./mvnw clean package 
./bin/generate-samples.sh
./bin/utils/export_docs_generators.sh
    Commit all changed files.
    This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
    These must match the expectations made by your contribution.
    You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
    For Windows users, please run the script in Git BASH.
  • File the PR against the correct branch: master (5.3.0), 6.0.x
  • If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

@bflaton
Updated template so that generated code now renders docstrings and fu…
2f8fc46 
…nction parameters nicely in IDE.

Endpoints are still accessible in generated code, mainly to satisfy some test cases.
@bflaton
Copy link
Contributor Author

bflaton commented Sep 6, 2021

As indicated by the PR checklist, mentioning the technical committee.. sorry if i misunderstood and now spam you all ;-)

@taxpon @frol @mbohlool @cbornet @kenjones-cisco @tomplus @Jyhess @arun-nalla @spacether

@spacether spacether added this to the 5.3.0 milestone Sep 6, 2021
spacether
spacether approved these changes Sep 6, 2021
View reviewed changes
Copy link
Contributor

@spacether spacether left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great; thank you for your PR!

@spacether spacether merged commit ae88cf1 into OpenAPITools:master Sep 6, 2021
@wing328
Copy link
Member

wing328 commented Sep 7, 2021

Travis CI failed with the following errors:

tests_manual/test_number_with_validations.py .                           [ 96%]
tests_manual/test_object_model_with_ref_props.py .                       [ 97%]
tests_manual/test_parent_pet.py .                                        [ 97%]
tests_manual/test_quadrilateral.py .                                     [ 97%]
tests_manual/test_shape.py ..                                            [ 98%]
tests_manual/test_string_enum.py .                                       [ 99%]
tests_manual/test_tag.py .                                               [ 99%]
tests_manual/test_triangle.py .                                          [100%]

=================================== FAILURES ===================================
_________________________ TestFakeApi.test_array_model _________________________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_array_model>

    def test_array_model(self):
        """Test case for array_model
    
        """
        from petstore_api.model import animal_farm, animal
        endpoint = self.api.array_model
>       assert endpoint.openapi_types['body'] == (animal_farm.AnimalFarm,)
E       AttributeError: 'function' object has no attribute 'openapi_types'

tests_manual/test_fake_api.py:95: AttributeError
_______________________ TestFakeApi.test_array_of_enums ________________________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_array_of_enums>

    def test_array_of_enums(self):
        """Test case for array_of_enums
    
        Array of Enums  # noqa: E501
        """
        from petstore_api.model import array_of_enums, string_enum
        endpoint = self.api.array_of_enums
>       assert endpoint.openapi_types['array_of_enums'] == (array_of_enums.ArrayOfEnums,)
E       AttributeError: 'function' object has no attribute 'openapi_types'

tests_manual/test_fake_api.py:202: AttributeError
___________________________ TestFakeApi.test_boolean ___________________________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_boolean>

    def test_boolean(self):
        """Test case for boolean
    
        """
        endpoint = self.api.boolean
>       assert endpoint.openapi_types['body'] == (bool,)
E       AttributeError: 'function' object has no attribute 'openapi_types'

tests_manual/test_fake_api.py:120: AttributeError
___________ TestFakeApi.test_composed_one_of_number_with_validations ___________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_composed_one_of_number_with_validations>

    def test_composed_one_of_number_with_validations(self):
        """Test case for composed_one_of_number_with_validations
    
        """
        from petstore_api.model import animal, composed_one_of_number_with_validations, number_with_validations
        endpoint = self.api.composed_one_of_number_with_validations
>       assert endpoint.openapi_types['composed_one_of_number_with_validations'] == (
            composed_one_of_number_with_validations.ComposedOneOfNumberWithValidations,)
E       AttributeError: 'function' object has no attribute 'openapi_types'

tests_manual/test_fake_api.py:297: AttributeError
__________________________ TestFakeApi.test_enum_test __________________________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_enum_test>

    def test_enum_test(self):
        """Test case for enum_test
    
        Object contains enum properties and array properties containing enums
        """
        from petstore_api.model.enum_test import EnumTest
        from petstore_api.model.string_enum import StringEnum
        from petstore_api.model.array_of_enums import ArrayOfEnums
    
        endpoint = self.api.enum_test
>       assert endpoint.openapi_types['enum_test'] == (EnumTest,)
E       AttributeError: 'function' object has no attribute 'openapi_types'

tests_manual/test_fake_api.py:153: AttributeError
___________________ TestFakeApi.test_number_with_validations ___________________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_number_with_validations>

    def test_number_with_validations(self):
        """Test case for number_with_validations
    
        """
        from petstore_api.model import number_with_validations
        endpoint = self.api.number_with_validations
>       assert endpoint.openapi_types['body'] == (number_with_validations.NumberWithValidations,)
E       AttributeError: 'function' object has no attribute 'openapi_types'

tests_manual/test_fake_api.py:228: AttributeError
_________________ TestFakeApi.test_object_model_with_ref_props _________________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_object_model_with_ref_props>

    def test_object_model_with_ref_props(self):
        """Test case for object_model_with_ref_props
    
        """
        from petstore_api.model.object_model_with_ref_props import ObjectModelWithRefProps
        from petstore_api.model.number_with_validations import NumberWithValidations
        endpoint = self.api.object_model_with_ref_props
>       assert endpoint.openapi_types['body'] == (ObjectModelWithRefProps,)
E       AttributeError: 'function' object has no attribute 'openapi_types'

tests_manual/test_fake_api.py:254: AttributeError
__________ TestFakeApi.test_post_inline_additional_properties_payload __________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_post_inline_additional_properties_payload>

    def test_post_inline_additional_properties_payload(self):
        """Test case for postInlineAdditionlPropertiesPayload
        """
        from petstore_api.model.inline_object6 import InlineObject6
        from petstore_api.model.fake_post_inline_additional_properties_payload_array_data import FakePostInlineAdditionalPropertiesPayloadArrayData
        endpoint = self.api.post_inline_additional_properties_payload
>       assert endpoint.openapi_types['inline_object6'] == (InlineObject6,)
E       AttributeError: 'function' object has no attribute 'openapi_types'

tests_manual/test_fake_api.py:684: AttributeError
________ TestFakeApi.test_post_inline_additional_properties_ref_payload ________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_post_inline_additional_properties_ref_payload>

    def test_post_inline_additional_properties_ref_payload(self):
        """Test case for postInlineAdditionlPropertiesRefPayload
        """
        from petstore_api.model.inline_additional_properties_ref_payload import InlineAdditionalPropertiesRefPayload
        from petstore_api.model.fake_post_inline_additional_properties_payload_array_data import FakePostInlineAdditionalPropertiesPayloadArrayData
        endpoint = self.api.post_inline_additional_properties_ref_payload
>       assert endpoint.openapi_types['inline_additional_properties_ref_payload'] == (InlineAdditionalPropertiesRefPayload,)
E       AttributeError: 'function' object has no attribute 'openapi_types'

tests_manual/test_fake_api.py:645: AttributeError
___________________________ TestFakeApi.test_string ____________________________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_string>

    def test_string(self):
        """Test case for string
    
        """
        endpoint = self.api.string
>       assert endpoint.openapi_types['body'] == (str,)
E       AttributeError: 'function' object has no attribute 'openapi_types'

tests_manual/test_fake_api.py:334: AttributeError
_________________________ TestFakeApi.test_string_enum _________________________

self = <tests_manual.test_fake_api.TestFakeApi testMethod=test_string_enum>

    def test_string_enum(self):
        """Test case for string_enum
    
        """
        from petstore_api.model import string_enum

Please take a look when you've time.

Ref: https://app.travis-ci.com/github/OpenAPITools/openapi-generator/builds/237050559

spacether added a commit that referenced this pull request Sep 7, 2021
@spacether
Revert "Updated template so that generated code now renders docstring…
9352973 
…s and function parameters nicely in IDE. (#10331)"

This reverts commit ae88cf1.
@spacether spacether mentioned this pull request Sep 7, 2021
Merged
spacether added a commit that referenced this pull request Sep 7, 2021
@spacether
Revert "Updated template so that generated code now renders docstring…
b258bba 
…s and function parameters nicely in IDE. (#10331)" (#10338)

This reverts commit ae88cf1.
@bflaton bflaton mentioned this pull request Sep 7, 2021
Merged
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@spacether spacether spacether approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

Client: Python Enhancement: Feature Feature: Documentation

Projects

None yet

Milestone

5.3.0

Development

Successfully merging this pull request may close these issues.

3 participants

@bflaton @wing328 @spacether