Summary

Add stubs for API resources and implement root stubs for existing subclasses.

Review Request #14257 — Created Dec. 4, 2024 and submitted Feb. 10, 2025, 8:15 a.m.

Information

Owner

david

Repository

RBTools

Branch

master

Bugs

Depends On

Reviewers

Groups

rbtools

People

Description

This change adds a new @api_stub decorator that we can use to define
stubs within resource implementations. These stubs provide type hints
and documentation for any methods which will be dynamically generated.

We have only a subset of subclasses for resources. For the ones we do
currently have, this adds stubs to the root resource for the methods
that are automatically generated from URI-templates. With this, if one's
editor is so configured, a developer can write
api_root.get_review_request( and the editor will auto-complete the
review_request_id parameter and indicate that the resulting value is a
ReviewRequestItemResource.

Testing Done


Ran unit tests.
Verified that stub methods were correctly replaced, and that doing

  things like help(api_root.get_review_request) showed the correct

  documentation and annotations.

Commits

Summary	ID
Add stubs for API resources and implement root stubs for existing subclasses. This change adds a new `@api_stub` decorator that we can use to define stubs within resource implementations. These stubs provide type hints and documentation for any methods which will be dynamically generated. We have only a subset of subclasses for resources. For the ones we do currently have, this adds stubs to the root resource for the methods that are automatically generated from URI-templates. With this, if one's editor is so configured, a developer can write `api_root.get_review_request(` and the editor will auto-complete the `review_request_id` parameter and indicate that the resulting value is a `ReviewRequestItemResource`. Testing Done: - Ran unit tests. - Verified that stub methods were correctly replaced, and that doing things like `help(api_root.get_review_request)` showed the correct documentation and annotations.	a0fae2d0e384e6ac5209aaebc2380a504cdde153

Summary

Add stubs for API resources and implement root stubs for existing subclasses.

This change adds a new `@api_stub` decorator that we can use to define stubs within resource implementations. These stubs provide type hints and documentation for any methods which will be dynamically generated. We have only a subset of subclasses for resources. For the ones we do currently have, this adds stubs to the root resource for the methods that are automatically generated from URI-templates. With this, if one's editor is so configured, a developer can write `api_root.get_review_request(` and the editor will auto-complete the `review_request_id` parameter and indicate that the resulting value is a `ReviewRequestItemResource`. Testing Done: - Ran unit tests. - Verified that stub methods were correctly replaced, and that doing things like `help(api_root.get_review_request)` showed the correct documentation and annotations.

a0fae2d0e384e6ac5209aaebc2380a504cdde153

Issues

Description	From	Last Updated
Where are the function definitions for is_api_stub() and replace_api_stub()?	maubin	Dec. 20, 2024, 10:45 a.m.
I think there's an extra space before the ending apostrophe?	maubin	Dec. 20, 2024, 10:45 a.m.
Missing Returns.	chipx86	Jan. 23, 2025, 8:34 p.m.
This and the other new methods and globls are missing Version Added.	chipx86	Jan. 23, 2025, 8:36 p.m.

flake8 passed.

JSHint passed.

rbtools/api/resource/base.py (Diff revision 1)

The issue has been resolved. Show all issues

Where are the function definitions for is_api_stub() and replace_api_stub()?

david Dec. 20, 2024, 10:45 a.m.

Huh, for some reason the posted diff was... not for this change. Fixed it.

rbtools/api/resource/base.py (Diff revision 1)
The issue has been resolved. Show all issues
```
I think there's an extra space before the ending apostrophe?
```

Commits:

	Summary	ID
	Add stub functionality for base resources and implement review request. This change adds support for `@api_stub` for the base resource class, used for "special" links (create/update/delete/etc) as well as for any resource-specific links. This also adds a new decorator, `@request_method_returns`, which works like `@request_method`, but can plumb through a specific return type. This has been used to make `ResourceLinkField` generic, so that calls to a `ResourceLinkField.get()` method can specify their return type as a specific resource subclass. Stubs for common special methods have been added to Resource, ItemResource, and ListResource. This change also adds resource-specific stubs to ReviewRequestItemResource, for those links where we have existing resource classes to reference. I've also added type hints for the review request attributes. Testing Done: - Ran unit tests. - Smoke tested rbt commands. - Ran a test script with debug logging to see that the stub debug info looked as expected.	ef110b6cafd99df95b5a1e76c378ab2f7debad28
	Add stubs for API resources and implement root stubs for existing subclasses. This change adds a new `@api_stub` decorator that we can use to define stubs within resource implementations. These stubs provide type hints and documentation for any methods which will be dynamically generated. We have only a subset of subclasses for resources. For the ones we do currently have, this adds stubs to the root resource for the methods that are automatically generated from URI-templates. With this, if one's editor is so configured, a developer can write `api_root.get_review_request(` and the editor will auto-complete the `review_request_id` parameter and indicate that the resulting value is a `ReviewRequestItemResource`. Testing Done: - Ran unit tests. - Verified that stub methods were correctly replaced, and that doing things like `help(api_root.get_review_request)` showed the correct documentation and annotations.	ba14a7a69e50537935904a89b0b564dea9cb337b

Diff:

Revision 2 (+1692 -14)

Show changes

	rbtools/api/resource/base.py
	rbtools/api/resource/root.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

rbtools/api/resource/base.py (Diff revision 2)
The issue has been resolved. Show all issues
```
Missing Returns.
```
rbtools/api/resource/base.py (Diff revision 2)
The issue has been resolved. Show all issues
```
This and the other new methods and globls are missing Version Added.
```

rbtools/api/resource/root.py (Diff revision 2)

I didn't even realize we could use the walrus operator now. Time has flown. I'm fine with this, but do we want to establish any code policy around when and where to use it?

david Jan. 23, 2025, 8:37 p.m.

I don't know that we need to? When it's useful it's pretty straightforward.

Commits:

	Summary	ID
	Add stubs for API resources and implement root stubs for existing subclasses. This change adds a new `@api_stub` decorator that we can use to define stubs within resource implementations. These stubs provide type hints and documentation for any methods which will be dynamically generated. We have only a subset of subclasses for resources. For the ones we do currently have, this adds stubs to the root resource for the methods that are automatically generated from URI-templates. With this, if one's editor is so configured, a developer can write `api_root.get_review_request(` and the editor will auto-complete the `review_request_id` parameter and indicate that the resulting value is a `ReviewRequestItemResource`. Testing Done: - Ran unit tests. - Verified that stub methods were correctly replaced, and that doing things like `help(api_root.get_review_request)` showed the correct documentation and annotations.	ba14a7a69e50537935904a89b0b564dea9cb337b
	Add stubs for API resources and implement root stubs for existing subclasses. This change adds a new `@api_stub` decorator that we can use to define stubs within resource implementations. These stubs provide type hints and documentation for any methods which will be dynamically generated. We have only a subset of subclasses for resources. For the ones we do currently have, this adds stubs to the root resource for the methods that are automatically generated from URI-templates. With this, if one's editor is so configured, a developer can write `api_root.get_review_request(` and the editor will auto-complete the `review_request_id` parameter and indicate that the resulting value is a `ReviewRequestItemResource`. Testing Done: - Ran unit tests. - Verified that stub methods were correctly replaced, and that doing things like `help(api_root.get_review_request)` showed the correct documentation and annotations.	16674105b3a07d6849337ee283113bbbedb61be6

Diff:

Revision 3 (+1728 -14)

Show changes

	rbtools/api/resource/base.py
	rbtools/api/resource/root.py

Checks run (1 timed out)

JSHint timed out.

Commits:

	Summary	ID
	Add stubs for API resources and implement root stubs for existing subclasses. This change adds a new `@api_stub` decorator that we can use to define stubs within resource implementations. These stubs provide type hints and documentation for any methods which will be dynamically generated. We have only a subset of subclasses for resources. For the ones we do currently have, this adds stubs to the root resource for the methods that are automatically generated from URI-templates. With this, if one's editor is so configured, a developer can write `api_root.get_review_request(` and the editor will auto-complete the `review_request_id` parameter and indicate that the resulting value is a `ReviewRequestItemResource`. Testing Done: - Ran unit tests. - Verified that stub methods were correctly replaced, and that doing things like `help(api_root.get_review_request)` showed the correct documentation and annotations.	16674105b3a07d6849337ee283113bbbedb61be6
	Add stubs for API resources and implement root stubs for existing subclasses. This change adds a new `@api_stub` decorator that we can use to define stubs within resource implementations. These stubs provide type hints and documentation for any methods which will be dynamically generated. We have only a subset of subclasses for resources. For the ones we do currently have, this adds stubs to the root resource for the methods that are automatically generated from URI-templates. With this, if one's editor is so configured, a developer can write `api_root.get_review_request(` and the editor will auto-complete the `review_request_id` parameter and indicate that the resulting value is a `ReviewRequestItemResource`. Testing Done: - Ran unit tests. - Verified that stub methods were correctly replaced, and that doing things like `help(api_root.get_review_request)` showed the correct documentation and annotations.	a0fae2d0e384e6ac5209aaebc2380a504cdde153

Diff:

Revision 4 (+1728 -14)

Show changes

	rbtools/api/resource/base.py
	rbtools/api/resource/root.py

Checks run (1 timed out)

JSHint timed out.

Ship it!

```
Ship It!
```

Status:: Completed
Change Summary:: Pushed to master (7c14ae7)