3.0.ipv8.loader
===============

.. py:module:: 3.0.ipv8.loader

.. autoapi-nested-parse::

   For most types of Community loading, you can use the ConfigBuilder.
   These classes present an alternative way to load Community objects into IPv8, itself loaded into another object.
   Use if you have a IPv8 manager (a "session") that needs fine-grained control over the loading of each community.



Classes
-------

.. autoapisummary::

   3.0.ipv8.loader.CommunityLauncher
   3.0.ipv8.loader.CommunityLoader
   3.0.ipv8.loader.IPv8CommunityLoader


Functions
---------

.. autoapisummary::

   3.0.ipv8.loader.name
   3.0.ipv8.loader.after
   3.0.ipv8.loader.precondition
   3.0.ipv8.loader._get_class
   3.0.ipv8.loader.overlay
   3.0.ipv8.loader.walk_strategy
   3.0.ipv8.loader.bootstrapper
   3.0.ipv8.loader.set_in_session
   3.0.ipv8.loader.kwargs


Module Contents
---------------

.. py:class:: CommunityLauncher

   Object in charge of preparing a Community for loading in IPv8.


   .. py:attribute:: community_args
      :type:  list
      :value: []



   .. py:attribute:: community_kwargs
      :type:  dict


   .. py:method:: get_name() -> str

      Get the launcher name, for pre-launch organisation.



   .. py:method:: not_before() -> list[str]

      Should not launch this before some other launcher has completed.

      :return: The list of launcher names to complete before this is launched



   .. py:method:: should_launch(session: object) -> bool

      Check whether this launcher should launch.

      For example:

          return session.config.get_tunnel_community_enabled()



   .. py:method:: prepare(overlay_provider: 3.0.ipv8.types.IPv8, session: object) -> None

      Perform setup tasks before the community is loaded.



   .. py:method:: finalize(ipv8: 3.0.ipv8.types.IPv8, session: object, community: 3.0.ipv8.types.Community) -> None

      Perform cleanup tasks after the community has been loaded.



   .. py:method:: get_kwargs(session: object) -> dict

      Get the kwargs to load the community with.



   .. py:method:: get_overlay_class() -> type[3.0.ipv8.types.Community]
      :abstractmethod:


      Get the overlay class this launcher wants to load.

      This raises a RuntimeError if it was not overwritten at runtime, to appease Pylint.



   .. py:method:: get_walk_strategies() -> list[tuple[type[3.0.ipv8.peerdiscovery.discovery.DiscoveryStrategy], dict, int]]

      Get walk strategies for this class.
      It should be provided as a list of tuples with the class, kwargs and maximum number of peers.



   .. py:method:: get_bootstrappers(session: object) -> list[tuple[type[3.0.ipv8.bootstrapping.bootstrapper_interface.Bootstrapper], dict]]

      Get the bootstrappers for this class.
      It should be provided as a list of tuples with the class and kwargs.



   .. py:method:: get_my_peer(ipv8: 3.0.ipv8.types.IPv8, session: object) -> 3.0.ipv8.peer.Peer

      Create a new Peer object that represents our own peer for the overlay.



.. py:class:: CommunityLoader

   Object in charge of loading communities into IPv8.


   .. py:attribute:: community_launchers
      :type:  dict[str, tuple[CommunityLauncher, bool]]


   .. py:attribute:: _logger


   .. py:method:: get_launcher(name: str) -> CommunityLauncher

      Get the launcher belonging to the given name.



   .. py:method:: has_launched(name: str) -> bool

      Check if the launcher with the given name has already been launched.



   .. py:method:: set_launcher(launcher: CommunityLauncher) -> None

      Register a launcher to be launched by name.

      If a launcher for the same name already existed, it is overwritten.



   .. py:method:: del_launcher(launcher: CommunityLauncher) -> None

      Unregister a launcher.



   .. py:method:: load(overlay_provider: 3.0.ipv8.types.IPv8, session: object) -> None

      Load all of the communities specified by the registered launchers into IPv8.



   .. py:method:: _launch(launcher: CommunityLauncher, ipv8: 3.0.ipv8.types.IPv8, session: object) -> None
      :abstractmethod:


      This method should be overridden.



.. py:class:: IPv8CommunityLoader

   Bases: :py:obj:`CommunityLoader`


   Loader for IPv8 communities.


   .. py:method:: _launch(launcher: CommunityLauncher, ipv8: 3.0.ipv8.types.IPv8, session: object) -> None

      Launch a launcher: register the overlay with IPv8.



.. py:function:: name(str_name: str) -> Callable[[type[CommunityLauncher]], type[CommunityLauncher]]

   Specify a custom name for this launcher.

   For example:

    .. code-block :: Python

       @name('Community1')
       class A(CommunityLauncher):
          ...

   :param str_name: the new name to give this launcher.


.. py:function:: after(*launcher_name: str) -> Callable[[type[CommunityLauncher]], type[CommunityLauncher]]

   Specify one or more Community classes which should be loaded before the CommunityLauncher is invoked.
   You may call this multiple times and/or with multiple arguments.

   For example:

    .. code-block :: Python

       @after('CommunityLauncher1', 'CommunityLauncher2')
       class A(CommunityLauncher):
          ...

       @after('CommunityLauncher1')
       @after('CommunityLauncher2')
       class A(CommunityLauncher):
          ...

   :param launcher_name: the launcher name(s) that need to be loaded beforehand.


.. py:function:: precondition(str_condition: str) -> Callable[[type[CommunityLauncher]], type[CommunityLauncher]]

   Specify a string to be evaluated and interpreted as a condition for this CommunityLauncher to start.
   A ``session`` object is provided to pull a state from.
   You may call this multiple times.

   For example:

    .. code-block :: Python

       @precondition('session.some_condition')
       class A(CommunityLauncher):
          ...

       @precondition('session.some_condition')
       @precondition('not session.some_condition_method()')
       class A(CommunityLauncher):
          ...

   :param str_condition: the string to be evaluated as a launch condition.


.. py:function:: _get_class(class_or_function: type[3.0.ipv8.types.Community] | Callable[[Any], type[3.0.ipv8.types.Community]]) -> type[3.0.ipv8.types.Community]

   Return the class by processing incoming argument either as a function or as
   a class.

   :param class_or_function: the class, or the function that represents this class.


.. py:function:: overlay(str_module_or_class: str | type[3.0.ipv8.types.Community] | Callable[[], type[3.0.ipv8.types.Community]], str_definition: str | None = None) -> Callable[[type[CommunityLauncher]], type[CommunityLauncher]]

   Specify, as strings, a module and Community class object defined therein to lazy-load.
   Otherwise, give an actual Community class to load.

   For example:

    .. code-block :: Python

       @overlay('my_module.some_submodule', 'MyCommunityClass')
       class A(CommunityLauncher):
          ...

       from my_module.some_submodule import MyCommunityClass
       @overlay(MyCommunityClass)
       class A(CommunityLauncher):
          ...

       def my_community_class():
           from my_module.some_submodule import MyCommunityClass
           return MyCommunityClass

       @overlay(my_community_class)
       class A(CommunityLauncher):
          ...

   :param str_module_or_class: either the module to load or a Community class.
   :param str_definition: either the class definition to load or None if str_module_or_class is not a string.


.. py:function:: walk_strategy(str_module_or_class: str | type[3.0.ipv8.peerdiscovery.discovery.DiscoveryStrategy] | Callable[[], type[3.0.ipv8.peerdiscovery.discovery.DiscoveryStrategy]], str_definition: str | None = None, target_peers: int = 20, kw_args: dict | None = None) -> Callable[[type[CommunityLauncher]], type[CommunityLauncher]]

   Specify, as strings, a module and DiscoveryStrategy class object defined therein to lazy-load.
   Otherwise, give an actual DiscoveryStrategy class to load.

   For example:

    .. code-block :: Python

       @walk_strategy('my_module.some_submodule', 'MyStrategyClass')
       class A(CommunityLauncher):
          ...

       from my_module.some_submodule import MyStrategyClass
       @walk_strategy(MyStrategyClass)
       class A(CommunityLauncher):
          ...

       @walk_strategy('my_module.some_submodule', 'MyStrategyClass', target_peers=-1, kwargs={'a key': 'a value'})
       class A(CommunityLauncher):
          ...

      def my_strategy_class():
           from my_module.some_submodule import MyStrategyClass
           return MyStrategyClass

       @walk_strategy(my_strategy_class)
       class A(CommunityLauncher):
           ...

   :param str_module_or_class: either the module to load or a DiscoveryStrategy class.
   :param str_definition: either the class definition to load or None if str_module_or_class is not a string.
   :param target_peers: the target_peers for the strategy.
   :param kw_args: the keyword arguments to initialize the DiscoveryStrategy instance with.


.. py:function:: bootstrapper(str_module_or_class: str | type[3.0.ipv8.bootstrapping.bootstrapper_interface.Bootstrapper] | Callable[[], type[3.0.ipv8.bootstrapping.bootstrapper_interface.Bootstrapper]], str_definition: str | None = None, kw_args: dict | None = None) -> Callable[[type[CommunityLauncher]], type[CommunityLauncher]]

   Specify, as strings, a module and Bootstrapper class object defined therein to lazy-load.
   Otherwise, give an actual Bootstrapper class to load.

   For example:

    .. code-block :: Python

       @bootstrapper('my_module.some_submodule', 'MyBootstrapper')
       class A(CommunityLauncher):
          ...

       from my_module.some_submodule import MyBootstrapper
       @bootstrapper(MyBootstrapper)
       class A(CommunityLauncher):
          ...

       @bootstrapper('my_module.some_submodule', 'MyBootstrapper', kw_args={'a key': 'a value'})
       class A(CommunityLauncher):
          ...

      def my_bootstrapper_class():
           from my_module.some_submodule import MyBootstrapper
           return MyBootstrapper

       @bootstrapper(my_bootstrapper_class)
       class A(CommunityLauncher):
           ...

   :param str_module_or_class: either the module to load or a Bootstrapper class.
   :param str_definition: either the class definition to load or None if str_module_or_class is not a string.
   :param kw_args: the keyword arguments to initialize the Bootstrapper instance with.


.. py:function:: set_in_session(attribute_name: str) -> Callable[[type[CommunityLauncher]], type[CommunityLauncher]]

   Specify an attribute to set on the session, once the CommunityLauncher has finished initializing its Community.

   For example, the following sets the ``session.my_community`` to the loaded Community instance:

    .. code-block :: Python

       @set_in_session('my_community')
       class A(CommunityLauncher):
          ...

   :param attribute_name: the attribute name (string) to set on the session, once the Community is loaded.


.. py:function:: kwargs(**kw_args) -> Callable[[type[CommunityLauncher]], type[CommunityLauncher]]

   Specify keyword arguments as evaluated strings, to initialize the Community with.
   A ``session`` object is provided to pull a state from.

   For example:

    .. code-block :: Python

       @kwargs('working_directory'='session.working_directory')
       class A(CommunityLauncher):
          ...

       @kwargs(a_key='"I am a string! :)"')
       class A(CommunityLauncher):
          ...

   :param kw_args: the mapping of keyword arguments to statements to be evaluated.