Skip to content

Commit a3b89f3

Browse files
cburgdorfcburgdorf
committed
Improve API docs of plugin support
1 parent 62971cd commit a3b89f3

File tree

10 files changed

+294
-87
lines changed

10 files changed

+294
-87
lines changed

‎docs/api/trinity/api.cli.rst

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
Command Line Interface (CLI)
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
.. code-block:: shell
5+
6+
usage: trinity [-h] [--version] [--trinity-root-dir TRINITY_ROOT_DIR]
7+
[-l {debug,info}] [--network-id NETWORK_ID | --ropsten]
8+
[--sync-mode {full,light} | --light] [--data-dir DATA_DIR]
9+
[--nodekey NODEKEY] [--nodekey-path NODEKEY_PATH]
10+
{console,attach} ...
11+
12+
positional arguments:
13+
{console,attach}
14+
console run the chain and start the trinity REPL
15+
attach open an REPL attached to a currently running chain
16+
17+
optional arguments:
18+
-h, --help show this help message and exit
19+
20+
sync mode:
21+
--version show program's version number and exit
22+
--trinity-root-dir TRINITY_ROOT_DIR
23+
The filesystem path to the base directory that trinity
24+
will store it's information. Default:
25+
$XDG_DATA_HOME/.local/share/trinity
26+
27+
logging:
28+
-l {debug,info}, --log-level {debug,info}
29+
Sets the logging level
30+
31+
network:
32+
--network-id NETWORK_ID
33+
Network identifier (1=Mainnet, 3=Ropsten)
34+
--ropsten Ropsten network: pre configured proof-of-work test
35+
network. Shortcut for `--networkid=3`
36+
37+
sync mode:
38+
--sync-mode {full,light}
39+
--light Shortcut for `--sync-mode=light`
40+
41+
chain:
42+
--data-dir DATA_DIR The directory where chain data is stored
43+
--nodekey NODEKEY Hexadecimal encoded private key to use for the nodekey
44+
--nodekey-path NODEKEY_PATH
45+
The filesystem path to the file which contains the
46+
nodekey

‎docs/api/trinity/extensibility/api.extensibility.events.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Events
2+
======
3+
4+
.. autoclass:: trinity.extensibility.events.PluginStartedEvent
5+
:members:
6+
7+
.. autoclass:: trinity.extensibility.events.ResourceAvailableEvent
8+
:members:

‎docs/api/trinity/extensibility/api.extensibility.exceptions.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Exceptions
2+
==========
3+
4+
.. autoclass:: trinity.extensibility.exceptions.EventBusNotReady
5+
:members:
6+
7+
.. autoclass:: trinity.extensibility.exceptions.UnsuitableShutdownError
8+
:members:
9+

‎docs/api/trinity/extensibility/api.extensibility.plugin.rst

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
Plugin
2+
======
3+
4+
5+
PluginContext
6+
-------------
7+
8+
.. autoclass:: trinity.extensibility.plugin.PluginContext
9+
:members:
10+
11+
BasePlugin
12+
----------
13+
14+
.. autoclass:: trinity.extensibility.plugin.BasePlugin
15+
:members:
16+
17+
BaseSyncStopPlugin
18+
------------------
19+
20+
.. autoclass:: trinity.extensibility.plugin.BaseSyncStopPlugin
21+
:members:
22+
23+
BaseAsyncStopPlugin
24+
-------------------
25+
26+
.. autoclass:: trinity.extensibility.plugin.BaseAsyncStopPlugin
27+
:members:
28+
29+
BaseMainProcessPlugin
30+
---------------------
31+
32+
.. autoclass:: trinity.extensibility.plugin.BaseMainProcessPlugin
33+
:members:
34+
35+
BaseIsolatedPlugin
36+
------------------
37+
38+
.. autoclass:: trinity.extensibility.plugin.BaseIsolatedPlugin
39+
:members:

‎docs/api/trinity/extensibility/api.extensibility.plugin_manager.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
PluginManager
2+
=============
3+
4+
BaseManagerProcessScope
5+
-----------------------
6+
7+
.. autoclass:: trinity.extensibility.plugin_manager.BaseManagerProcessScope
8+
:members:
9+
10+
MainAndIsolatedProcessScope
11+
---------------------------
12+
13+
.. autoclass:: trinity.extensibility.plugin_manager.MainAndIsolatedProcessScope
14+
:members:
15+
16+
SharedProcessScope
17+
------------------
18+
19+
.. autoclass:: trinity.extensibility.plugin_manager.SharedProcessScope
20+
:members:
21+
22+
PluginManager
23+
-------------
24+
25+
.. autoclass:: trinity.extensibility.plugin_manager.PluginManager
26+
:members:
27+

‎docs/api/trinity/extensibility/index.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Extensibility
2+
=============
3+
4+
.. warning::
5+
6+
The extensibility API isn't stable yet. Expect breaking changes.
7+
8+
.. toctree::
9+
:maxdepth: 4
10+
:name: toc-eth-api-extensibility
11+
12+
api.extensibility.events.rst
13+
api.extensibility.exceptions.rst
14+
api.extensibility.plugin.rst
15+
api.extensibility.plugin_manager.rst
16+

‎docs/api/trinity/index.rst

Lines changed: 6 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -3,49 +3,12 @@ Trinity
33

44
This section aims to provide a detailed description of all APIs. If you are looking for something more hands-on or higher-level check out the existing :doc:`Trinity guides </guides/trinity/index>`.
55

6-
Command Line Interface (CLI)
7-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6+
.. toctree::
7+
:maxdepth: 4
8+
:name: toc-api-trinity
9+
:caption: API
810

9-
.. code-block:: shell
11+
api.cli
12+
extensibility/index
1013

11-
usage: trinity [-h] [--version] [--trinity-root-dir TRINITY_ROOT_DIR]
12-
[-l {debug,info}] [--network-id NETWORK_ID | --ropsten]
13-
[--sync-mode {full,light} | --light] [--data-dir DATA_DIR]
14-
[--nodekey NODEKEY] [--nodekey-path NODEKEY_PATH]
15-
{console,attach} ...
1614

17-
positional arguments:
18-
{console,attach}
19-
console run the chain and start the trinity REPL
20-
attach open an REPL attached to a currently running chain
21-
22-
optional arguments:
23-
-h, --help show this help message and exit
24-
25-
sync mode:
26-
--version show program's version number and exit
27-
--trinity-root-dir TRINITY_ROOT_DIR
28-
The filesystem path to the base directory that trinity
29-
will store it's information. Default:
30-
$XDG_DATA_HOME/.local/share/trinity
31-
32-
logging:
33-
-l {debug,info}, --log-level {debug,info}
34-
Sets the logging level
35-
36-
network:
37-
--network-id NETWORK_ID
38-
Network identifier (1=Mainnet, 3=Ropsten)
39-
--ropsten Ropsten network: pre configured proof-of-work test
40-
network. Shortcut for `--networkid=3`
41-
42-
sync mode:
43-
--sync-mode {full,light}
44-
--light Shortcut for `--sync-mode=light`
45-
46-
chain:
47-
--data-dir DATA_DIR The directory where chain data is stored
48-
--nodekey NODEKEY Hexadecimal encoded private key to use for the nodekey
49-
--nodekey-path NODEKEY_PATH
50-
The filesystem path to the file which contains the
51-
nodekey

‎trinity/extensibility/exceptions.py

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,21 @@
33
)
44

55

6-
class UnsuitableShutdownError(BaseTrinityError):
6+
class EventBusNotReady(BaseTrinityError):
77
"""
8-
Raised when `shutdown` was called on a ``PluginManager`` instance that operates
9-
in the ``MainAndIsolatedProcessScope`` or when ``shutdown_blocking`` was called on a
10-
``PluginManager`` instance that operates in the ``SharedProcessScope``.
8+
Raised when a plugin tried to access an :class:`~lahja.eventbus.EventBus` before the plugin
9+
had received its :meth:`~trinity.extensibility.plugin.BasePlugin.ready` call.
1110
"""
1211
pass
1312

1413

15-
class EventBusNotReady(BaseTrinityError):
14+
class UnsuitableShutdownError(BaseTrinityError):
1615
"""
17-
Raised when a plugin tried to access an EventBus before the plugin
18-
had received its ``ready`` call.
16+
Raised when :meth:`~trinity.extensibility.plugin_manager.PluginManager.shutdown` was called on
17+
a :class:`~trinity.extensibility.plugin_manager.PluginManager` instance that operates in the
18+
:class:`~trinity.extensibility.plugin_manager.MainAndIsolatedProcessScope` or when
19+
:meth:`~trinity.extensibility.plugin.PluginManager.shutdown_blocking` was called on a
20+
:class:`~trinity.extensibility.plugin_manager.PluginManager` instance that operates in the
21+
:class:`~trinity.extensibility.plugin_manager.SharedProcessScope`.
1922
"""
2023
pass

0 commit comments

Comments
 (0)