docs: add Advanced: PyOTA Commands page & refactoring
#275
Conversation
todofixthis
left a comment
todofixthis
left a comment
There was a problem hiding this comment.
Looks good! Added a few questions/suggestions.
docs/commands.rst
Outdated
|
|
||
| :py:class:`BaseCommand` is also decorated with a :py:class:`CommandMeta` | ||
| metaclass, that helps to register each command automatically in the API classes' | ||
| command registry at runtime. |
There was a problem hiding this comment.
💭 We could probably deprecate and remove this functionality; I don't think anybody uses the command registries.
Short version is, I wanted to make it so that developers didn't have to add methods to the Iota/StrictIota/MultisigIota/etc. classes explicitly. Instead, the registry would automatically load commands in the specified packages and attach them magically.
In exchange for being clever (i.e., no real benefits 😅), this approach had a number of drawbacks:
- Very difficult to understand which commands a particular API class can use via static analysis.
- Difficult to document how users should invoke each command, what parameters to provide, etc.
- IDEs couldn't support jumping from a command invocation to the corresponding class (e.g.,
self.commands['getNodeInfo']vs.core.GetNodeInfoCommand).
In #30 I laid the groundwork for making command registries redundant.
There was a problem hiding this comment.
I removed command registries and modified command test cases. take a look on dbb4de7 .
There was a problem hiding this comment.
Awesome! I added some comments to that commit.
lzpap
force-pushed
the
docs_advanced_pyota_commands
branch
2 times, most recently
from
c29fafb to
6bea33f
Compare
lzpap
force-pushed
the
docs_advanced_pyota_commands
branch
from
6bea33f to
a39c527
Compare
lzpap
changed the title
Advanced: PyOTA Commands pageAdvanced: PyOTA Commands page & refactoring
lzpap
force-pushed
the
docs_advanced_pyota_commands
branch
from
a39c527 to
0f2aa3b
Compare
- Removed auto command discovery in API class, as it was only used in tests. - Modified test cases. - Removed custom __getattr__() from API class.
Explain the inner workings of an API command for advanced users/developers of the the library.
lzpap
force-pushed
the
docs_advanced_pyota_commands
branch
from
0f2aa3b to
be39875
Compare
2 participants
Related issue #268
Changes
Remove
auto command discovery.api.getTrytes(..)for example). This feature turned out not to have real benefits, as a user would always call the API method, not the command directly (api.get_trytes(...)) and it also messes with the static analysis of the IDE (autocompletion, suggestion, type hints, etc...).Add
Advanced: PyOTA Commandspage to docs.Commandsare used within API methods.filters, add reference tofiltersdocumentation.The
Advancednature of the doc page points out that this part is intended for people who would like to know how PyOTA works under the hood (advanced users/developers of the lib).