Various docstring and type annotation updates #953
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
5 tasks
jnsgruk
approved these changes
Jun 30, 2023
jnsgruk
reviewed
Jun 30, 2023
Comment on lines
+927
to
+934
| """Set the name and UUID of the model that this is representing. | ||
|
|
||
| This cannot be called once begin() has been called. But it lets you set the value that | ||
| will be returned by Model.name and Model.uuid. | ||
| This cannot be called once :meth:`begin` has been called. But it lets | ||
| you set the value that will be returned by :attr:`Model.name <ops.Model.name>` | ||
| and :attr:`Model.uuid <ops.Model.uuid>`. | ||
|
|
||
| This is a convenience method to invoke both Harness.set_model_name | ||
| and Harness.set_model_uuid at once. | ||
| This is a convenience method to invoke both :meth:`set_model_name` | ||
| and :meth:`set_model_uuid` at once. |
There was a problem hiding this comment.
Nit that shouldn't block the merge, but applies in a few places and would be good to clean up over time...
I'd prefer to remove the "you" - and stick with the imperative style (similar to commit messages).
Something like:
"""Set the name and UUID of the model this represents.
Cannot be called once :meth:`begin` has been called. Enables the
value returned by `:attr:`Model.name <ops.Model.name>` and
:attr:`Model.uuid <ops.Model.uuid>` to be controlled.
Convenience method to invoke both :meth:`set_model_name`
and :meth:`set_model_uuid` at once.
"""Another approach might be s/you/the developer/g but I still think the above is cleaner.
There was a problem hiding this comment.
Good call. I'm going to leave it for another PR so this one can avoid too much sprawl. Opened issue #959 to track.
PietroPasotti
approved these changes
Jun 30, 2023
This was referenced Jul 4, 2023
benhoyt
added a commit
that referenced
this pull request
Jul 4, 2023
One more thing forgotten from #953. This is annoying because it means that charms that use ops.PebbleReadyEvent annotations when handling pebble-ready can't access any attributes of the workload, as it doesn't have a type.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The intent here is to sprinkle a bit of consistency over our reference docs. There's currently a fair bit of duplication, lack of type information on attributes, or just unclear docs, and so on. One of the biggest changes was giving instance attributes proper type annotations and separating out and enhancing their docstrings.
I've spent 30 minutes or so a day on this for the last couple of weeks, and got through all the docs (viewable version here). It's not perfect, but I think it's a definite improvement for #920.