.. image:: https://ipopo.readthedocs.io/en/latest/_images/logo_texte_200.png
:alt: iPOPO logo
:width: 200px
:align: center
:target: https://ipopo.readthedocs.io/
iPOPO: A Service-Oriented Component Model for Python
####################################################
.. image:: https://img.shields.io/badge/GitHub-Repository-black?logo=github
:target: https://github.com/tcalmant/ipopo/
:alt: GitHub repository
.. image:: https://img.shields.io/badge/ReadTheDocs-Documentation-black?logo=readthedocs
:target: https://ipopo.readthedocs.io/
:alt: ReadTheDocs
.. image:: https://img.shields.io/pypi/v/ipopo.svg
:target: https://pypi.python.org/pypi/ipopo/
:alt: Latest Version
.. image:: https://img.shields.io/pypi/l/ipopo.svg
:target: https://pypi.python.org/pypi/ipopo/
:alt: License
.. image:: https://github.com/tcalmant/ipopo/actions/workflows/ci-build.yml/badge.svg?branch=v3
:target: https://github.com/tcalmant/ipopo/actions/workflows/ci-build.yml
:alt: GitHub Actions CI status
.. image:: https://coveralls.io/repos/github/tcalmant/ipopo/badge.svg?branch=v3
:target: https://coveralls.io/github/tcalmant/ipopo?branch=v3
:alt: Coveralls status
`iPOPO <https://ipopo.readthedocs.io/>`_ is a Python-based Service-Oriented
Component Model (SOCM) based on Pelix, a dynamic service platform.
They are inspired on two popular Java technologies for the development of
long-lived applications: the
`iPOJO <https://web.archive.org/web/20210616112915/http://felix.apache.org/documentation/subprojects/apache-felix-ipojo.html>`_
component model and the `OSGi <https://www.osgi.org/>`_ Service Platform.
iPOPO enables to conceive long-running and modular IT services.
See https://ipopo.readthedocs.io/ for documentation and more information.
Note on this version
====================
This is the 3.x branch of iPOPO, which is intended to work with Python 3.10+.
The iPOPO API didn't change much between v1 and v3: all code working with iPOPO
v1 should be compatible with iPOPO v3 (as long as the Python syntax and
packages are compatible with newer Python versions).
If that's not the case, please fill in a bug report on
`GitHub issues <https://github.com/tcalmant/ipopo/issues>`_.
If you are working with Python between 2.7 and 3.7, you must instead use the
[1.x branch](https://github.com/tcalmant/ipopo/tree/v1) of iPOPO.
Note that iPOPO has not been tested with versions 3.8 and 3.9.
[Version 2.x](https://github.com/tcalmant/ipopo/tree/v2) was a trial to
implement iPOPO with ``asyncio`` for Python 3.7, but has been stalled due to
various issues and lack of contributions.
Usage survey
============
In order to gain insight from the iPOPO community, I've put a
`really short survey <https://docs.google.com/forms/d/1zx18_Rg27mjdGrlbtr9fWFmVnZNINo9XCfrYJbr4oJI>`_
on Google Forms (no login required).
Please, feel free to answer it, the more answers, the better.
All feedback is really appreciated.
.. contents::
Install
#######
Option 1: Using pip
===================
iPOPO is available on `PyPI <http://pypi.python.org/pypi/iPOPO>`_ and can be
installed using ``pip``:
.. code-block:: bash
# Install system-wide
$ sudo pip install iPOPO
# ... or user-wide installation
$ pip install --user iPOPO
Option 2: From source
=====================
.. code-block:: bash
$ git clone https://github.com/tcalmant/ipopo.git
$ cd ipopo
$ python setup.py install
Check install
=============
To check if Pelix is installed correctly, run the following command:
.. code-block:: bash
$ python -m pelix.shell --version
Pelix 3.0.0 from /home/tcalmant/git/ipopo/pelix/__init__.py
Concepts
########
Pelix brings the concept of *bundle* in Python.
A bundle is a module with a life cycle: it can be installed, started, stopped,
updated and *uninstalled*.
A bundle can declare a class acting as bundle activator, using the
``@BundleActivator`` decorator.
This class will be instantiated by the framework and its ``start()`` and
``stop()`` method will be called to notify the bundle about its activation and
deactivation.
When it is active, a bundle can register services.
A service is an object implementing a specification and associated to a set of
properties.
A component will then be able to select and consume a service according to the
specification(s) it provides and to its properties.
The components are a concept brought by iPOPO.
A component, or component instance, is an object managed by a container.
The container handles the interactions between the component and the Pelix
framework.
That way, the component contains only the code required for its task, not for
its bindings with the framework.
A component is an instance of a component factory, a class `manipulated <https://ipopo.readthedocs.io/en/latest/refcards/ipopo.html>`_
by iPOPO `decorators <https://ipopo.readthedocs.io/en/latest/refcards/ipopo_decorators.html>`_.
For more information, see the `concepts page <https://ipopo.readthedocs.io/en/latest/refcards/index.html>`_.
Sample
######
This sample gives a quick overview of the usage of iPOPO.
For more information, take a look at `iPOPO in 10 minutes <https://ipopo.readthedocs.io/en/latest/quickstart.html>`_.
Service specification
=====================
In iPOPO v3, you can use a Python `procotol <https://docs.python.org/3/library/typing.html#typing.Protocol>`_
to define the specification of a service.
A specification class/protocol should be decorated with ``@Specification`` to be
given a unique name.
The components providing that specification should then inherit that specification
class/protocol in order for the development tools you use to be able to warn if
a method is missing or uses invalid types.
Note that it is possible to skip that step and use a string constant as
specification like in iPOPO v1.
Here is a sample description of an Hello World service specification:
.. code-block:: python
from typing import Protocol
from pelix.constants import Specification
@Specification("sample.hello")
class HelloWorld(Protocol):
"""
Hello world specification: definition of the methods a component providing
that service must implement
"""
def hello(self, name: str) -> None:
"""
Prints hello
"""
...
def bye(self, name: str) -> None:
"""
Prints bye
"""
...
Service provider
================
The following code defines a component factory (a class) which instances will
provide a ``sample.hello`` service.
.. code-block:: python
# iPOPO decorators
from pelix.ipopo.decorators import ComponentFactory, Provides, Instantiate
# Import the specification, if we want to use its type
from specification import HelloWorld
# Manipulates the class and sets its (unique) factory name
@ComponentFactory("hello-provider-factory")
# Indicate that the components will provide a service
@Provides(HelloWorld)
# Like in iPOPOv1, We could also use the specification name directly:
# @Provides("sample.hello")
# Tell iPOPO to instantiate a component instance as soon as the file is loaded
@Instantiate("hello-provider-auto")
# When using Python protocols, it is recommended to inherit from it to
# benefit from types handling of IDEs.
class HelloProvider(HelloWorld):
"""
A sample service provider
"""
def hello(self, name="world"):
"""
Says hello
"""
print("Hello,", name, "!")
def bye(self, name="cruel world"):
"""
Says bye
"""
print("Bye,", name, "!")
Due to the ``@Instantiate`` decorator, iPOPO will
automatically instantiate a component when the bundle providing this component
factory will be started.
It is also possible to instantiate a component using shell commands or via the
iPOPO runtime service
(see `use_ipopo <https://ipopo.readthedocs.io/en/latest/refcards/ipopo.html#pelix.ipopo.constants.use_ipopo>`_).
Each component instance will provide a ``sample.hello`` service, which can be
consumed by any bundle or any other component.
Service consumer
================
The following code defines a component factory (a class) which instances will
consume a ``sample.hello`` service. If multiple services are available, iPOPO
will select the one with the highest rank and the lowest service ID
(*i.e.* the oldest service).
In iPOPO v3, it is again recommended to use typing as much as possible.
For injected fields and properties, the fields injected with ``@Requires`` should
be defined at class level with the right type hint: type, optional, list, ...
based on the requirement configuration.
.. code-block:: python
from pelix.ipopo.decorators import ComponentFactory, Instantiate, Invalidate, Requires, Validate
from specification import HelloWorld
# Manipulates the class and sets its (unique) factory name
@ComponentFactory("hello-consumer-factory")
# Indicate that the components require a sample.hello service to work
# and to inject the found service in the _svc field
# We could also use the specification name instead of the type
@Requires("_svc", HelloWorld)
# Tell iPOPO to instantiate a component instance as soon as the file is loaded
@Instantiate("hello-consumer-auto")
class HelloConsumer:
"""
A sample service consumer
"""
# Define the injected field type for static typing (optional)
_svc: HelloWorld
@Validate
def validate(self, context):
"""
Component validated: all its requirements have been injected
"""
self._svc.hello("Consumer")
@Invalidate
def invalidate(self, context):
"""
Component invalidated: one of its requirements is going away
"""
self._svc.bye("Consumer")
When the bundle providing this component factory will be started, iPOPO will
automatically instantiate a component, due to the ``@Instantiate`` decorator.
Each component instance will require a ``sample.hello`` service. Once iPOPO
has injected all the required services (here, a single ``sample.hello`` service)
in a component instance, this instance will be considered *valid* and iPOPO
will call its method decorated by ``@Validate``.
There, the component can consume its dependencies, start threads, etc.
It is recommended for this method to start threads and to return quickly, as it
blocks iPOPO and the Pelix framework.
When a required service is unregistered by its provider, the component
instances consuming it are invalidated.
When the method decorated by ``@Invalidate`` is called, the service is still
injected and should be usable (except for special cases, like remote services).
Run!
====
To run this sample, you'll need to copy the snippets above in different files:
* copy the *Service specification* snipper in a file named *specification.py*
* copy the *Service provider* snippet in a file named *provider.py*
* copy the *Service consumer* snippet in a file named *consumer.py*
You can also find those files in the project repository in the
``samples/hello_world`` folder.
Then, run a Pelix shell in the same folder as those files, and execute the
commands listed in this trace:
.. code-block:: bash
$ python -m pelix.shell
** Pelix Shell prompt **
$ # Install the bundles
$ install provider
Bundle ID: 15
$ install consumer
Bundle ID: 16
$ # Start the bundles (the order isn't important here)
$ start 15 16
Starting bundle 15 (provider)...
Starting bundle 16 (consumer)...
Hello, Consumer !
$ # View iPOPO instances
$ instances
+----------------------+------------------------------+-------+
| Name | Factory | State |
+======================+==============================+=======+
| hello-consumer-auto | hello-consumer-factory | VALID |
+----------------------+------------------------------+-------+
| hello-provider-auto | hello-provider-factory | VALID |
+----------------------+------------------------------+-------+
| ipopo-shell-commands | ipopo-shell-commands-factory | VALID |
+----------------------+------------------------------+-------+
3 components running
$ # View details about the consumer
$ instance hello-consumer-auto
Name.....: hello-consumer-auto
Factory..: hello-consumer-factory
Bundle ID: 16
State....: VALID
Services.:
Dependencies:
Field: _svc
Specification: sample.hello
Filter......: None
Optional.....: False
Aggregate....: False
Handler......: SimpleDependency
Bindings:
ServiceReference(ID=18, Bundle=15, Specs=['sample.hello'])
Properties:
+---------------+---------------------+
| Key | Value |
+===============+=====================+
| instance.name | hello-consumer-auto |
+---------------+---------------------+
$ # Modify the provider file (e.g. change the 'Hello' string by 'Hi')
$ # Update the provider bundle (ID: 15)
$ update 15
Updating bundle 15 (provider)...
Bye, Consumer !
Hi, Consumer !
$ # Play with other commands (see help)
First, the ``install`` commands are used to install the bundle: they will be
imported but their activator won't be called. If this command fails, the bundle
is not installed and is not referenced by the framework.
If the installation succeeded, the bundle can be started: it's activator is
called (if any). Then, iPOPO detects the component factories provided by the
bundle and instantiates the components declared using the ``@Instantiate``
decorator.
The ``instances`` and ``instance`` commands can be use to print the state and
bindings of the components. Some other commands are very useful, like ``sl``
and ``sd`` to list the registered services and print their details. Use the
``help`` command to see which ones can be used.
The last part of the trace shows what happens when updating a bundle.
First, update the source code of the provider bundle, *e.g.* by changing the
string it prints in the ``hello()`` method.
Then, tell the framework to update the bundle using the ``update`` command.
This command requires a bundle ID, which has been given as a result of the
``install`` command and can be found using ``bl``.
When updating a bundle, the framework stops it and reloads it (using
`importlib.reload <https://docs.python.org/3/library/importlib.html#importlib.reload>`_).
If the update fails, the old version is kept.
If the bundle was active before the update, it is restarted by the framework.
Stopping a bundle causes iPOPO to kill the component instance(s) of the
factories it provided.
Therefore, no one provides the ``sample.hello`` service, which causes the
consumer component to be invalidated.
When the provider bundle is restarted, a new provider component is instantiated
and its service is injected in the consumer, which becomes valid again.
Batteries included
##################
Pelix/iPOPO comes with some useful services:
* Pelix Shell: a simple shell to control the framework (manage bundles,
show the state of components, ...).
The shell is split in 5 parts:
* the parser: a shell interpreter class, which can be reused to create other
shells (with a basic support of variables);
* the shell core service: callable from any bundle, it executes the given
command lines;
* the UIs: text UI (console) and remote shell (TCP/TLS, XMPP)
* the commands providers: iPOPO commands, report, EventAdmin, ...
* the completion providers: Pelix, iPOPO
See the `shell tutorial <http://ipopo.readthedocs.io/en/latest/quickstart.html#play-with-the-shell>`_
for more information.
* An HTTP service, based on the HTTP server from the standard library.
It provides the concept of *servlet*, borrowed from Java.
See the `HTTP service reference <http://ipopo.readthedocs.io/en/latest/refcards/http.html>`_
for more information.
There is also a `routing utility class <http://ipopo.readthedocs.io/en/latest/refcards/http_routing.html>`_,
based on decorators, which eases the development of REST-like servlets.
* Remote Services: export and import services to/from other Pelix framework or
event Java OSGi frameworks!
See the `remote services reference <http://ipopo.readthedocs.io/en/latest/refcards/remote_services.html>`_
and the `Remote Service Admin reference <https://ipopo.readthedocs.io/en/latest/refcards/rsa.html>`_
for more information.
The former should be used to link iPOPO instances while the latter targets both iPOPO and Java OSGi frameworks.
Pelix also provides an implementation of the `EventAdmin service <http://ipopo.readthedocs.io/en/latest/refcards/eventadmin.html>`_,
inspired from the `OSGi specification <http://www.osgi.org/Specifications/HomePage>`_.
Feedback
########
Feel free to send feedback on your experience of Pelix/iPOPO, via the mailing
lists:
* User list: https://groups.google.com/g/ipopo-users
* Development list: https://groups.google.com/g/ipopo-dev
* GitHub Discussions: https://github.com/tcalmant/ipopo/discussions
Bugs and features requests can be submitted using the
`Issue Tracker <https://github.com/tcalmant/ipopo/issues>`_ on GitHub.
Contributing
############
All contributions are welcome!
#. Create an `issue <https://github.com/tcalmant/ipopo/issues>`_ to discuss
about your idea or the problem you encounter
#. `Fork <https://github.com/tcalmant/ipopo/fork>`_ the project
#. Develop your changes
#. Check your code with `pylint <https://pypi.python.org/pypi/pylint/>`_
and `pep8 <https://pypi.python.org/pypi/pep8>`_
#. If necessary, write some unit tests
#. Commit your changes, indicating in each commit a reference to the issue
you're working on
#. Push the commits on your repository
#. Create a *Pull Request*
#. Enjoy!
Please note that your contributions will be released under the project's
license, which is the `Apache Software License 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`__.
Compatibility
#############
Pelix and iPOPO are tested using
`GitHub actions <https://github.com/tcalmant/ipopo/actions>`_
targetting Python 3.10, 3.11 and 3.12.
iPOPO v3 doesn't support Python 2 neither versions earlier than 3.10.
If you need to work with those versions of Python, please use iPOPO v1.
You can then use Remote Services to allow interactions between iPOPO v1 and v3.
License
#######
iPOPO is released under the `Apache Software License 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`__.
Raw data
{
"_id": null,
"home_page": "https://github.com/tcalmant/ipopo/",
"name": "iPOPO",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Thomas Calmant",
"author_email": "thomas.calmant@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5d/a1/62ac3e3175db0c93a5c3f0ca767a79124cfd7be93fd5e3e93d43daf1168c/iPOPO-3.0.0.tar.gz",
"platform": null,
"description": ".. image:: https://ipopo.readthedocs.io/en/latest/_images/logo_texte_200.png\r\n :alt: iPOPO logo\r\n :width: 200px\r\n :align: center\r\n :target: https://ipopo.readthedocs.io/\r\n\r\niPOPO: A Service-Oriented Component Model for Python\r\n####################################################\r\n\r\n.. image:: https://img.shields.io/badge/GitHub-Repository-black?logo=github\r\n :target: https://github.com/tcalmant/ipopo/\r\n :alt: GitHub repository\r\n\r\n.. image:: https://img.shields.io/badge/ReadTheDocs-Documentation-black?logo=readthedocs\r\n :target: https://ipopo.readthedocs.io/\r\n :alt: ReadTheDocs\r\n\r\n.. image:: https://img.shields.io/pypi/v/ipopo.svg\r\n :target: https://pypi.python.org/pypi/ipopo/\r\n :alt: Latest Version\r\n\r\n.. image:: https://img.shields.io/pypi/l/ipopo.svg\r\n :target: https://pypi.python.org/pypi/ipopo/\r\n :alt: License\r\n\r\n.. image:: https://github.com/tcalmant/ipopo/actions/workflows/ci-build.yml/badge.svg?branch=v3\r\n :target: https://github.com/tcalmant/ipopo/actions/workflows/ci-build.yml\r\n :alt: GitHub Actions CI status\r\n\r\n.. image:: https://coveralls.io/repos/github/tcalmant/ipopo/badge.svg?branch=v3\r\n :target: https://coveralls.io/github/tcalmant/ipopo?branch=v3\r\n :alt: Coveralls status\r\n\r\n`iPOPO <https://ipopo.readthedocs.io/>`_ is a Python-based Service-Oriented\r\nComponent Model (SOCM) based on Pelix, a dynamic service platform.\r\nThey are inspired on two popular Java technologies for the development of\r\nlong-lived applications: the\r\n`iPOJO <https://web.archive.org/web/20210616112915/http://felix.apache.org/documentation/subprojects/apache-felix-ipojo.html>`_\r\ncomponent model and the `OSGi <https://www.osgi.org/>`_ Service Platform.\r\niPOPO enables to conceive long-running and modular IT services.\r\n\r\nSee https://ipopo.readthedocs.io/ for documentation and more information.\r\n\r\n\r\nNote on this version\r\n====================\r\n\r\nThis is the 3.x branch of iPOPO, which is intended to work with Python 3.10+.\r\nThe iPOPO API didn't change much between v1 and v3: all code working with iPOPO\r\nv1 should be compatible with iPOPO v3 (as long as the Python syntax and\r\npackages are compatible with newer Python versions).\r\nIf that's not the case, please fill in a bug report on\r\n`GitHub issues <https://github.com/tcalmant/ipopo/issues>`_.\r\n\r\nIf you are working with Python between 2.7 and 3.7, you must instead use the\r\n[1.x branch](https://github.com/tcalmant/ipopo/tree/v1) of iPOPO.\r\nNote that iPOPO has not been tested with versions 3.8 and 3.9.\r\n\r\n[Version 2.x](https://github.com/tcalmant/ipopo/tree/v2) was a trial to\r\nimplement iPOPO with ``asyncio`` for Python 3.7, but has been stalled due to\r\nvarious issues and lack of contributions.\r\n\r\nUsage survey\r\n============\r\n\r\nIn order to gain insight from the iPOPO community, I've put a\r\n`really short survey <https://docs.google.com/forms/d/1zx18_Rg27mjdGrlbtr9fWFmVnZNINo9XCfrYJbr4oJI>`_\r\non Google Forms (no login required).\r\n\r\nPlease, feel free to answer it, the more answers, the better.\r\nAll feedback is really appreciated.\r\n\r\n.. contents::\r\n\r\nInstall\r\n#######\r\n\r\nOption 1: Using pip\r\n===================\r\n\r\niPOPO is available on `PyPI <http://pypi.python.org/pypi/iPOPO>`_ and can be\r\ninstalled using ``pip``:\r\n\r\n.. code-block:: bash\r\n\r\n # Install system-wide\r\n $ sudo pip install iPOPO\r\n\r\n # ... or user-wide installation\r\n $ pip install --user iPOPO\r\n\r\n\r\nOption 2: From source\r\n=====================\r\n\r\n.. code-block:: bash\r\n\r\n $ git clone https://github.com/tcalmant/ipopo.git\r\n $ cd ipopo\r\n $ python setup.py install\r\n\r\n\r\nCheck install\r\n=============\r\n\r\nTo check if Pelix is installed correctly, run the following command:\r\n\r\n.. code-block:: bash\r\n\r\n $ python -m pelix.shell --version\r\n Pelix 3.0.0 from /home/tcalmant/git/ipopo/pelix/__init__.py\r\n\r\nConcepts\r\n########\r\n\r\nPelix brings the concept of *bundle* in Python.\r\nA bundle is a module with a life cycle: it can be installed, started, stopped,\r\nupdated and *uninstalled*.\r\n\r\nA bundle can declare a class acting as bundle activator, using the\r\n``@BundleActivator`` decorator.\r\nThis class will be instantiated by the framework and its ``start()`` and\r\n``stop()`` method will be called to notify the bundle about its activation and\r\ndeactivation.\r\n\r\nWhen it is active, a bundle can register services.\r\nA service is an object implementing a specification and associated to a set of\r\nproperties.\r\nA component will then be able to select and consume a service according to the\r\nspecification(s) it provides and to its properties.\r\n\r\nThe components are a concept brought by iPOPO.\r\nA component, or component instance, is an object managed by a container.\r\nThe container handles the interactions between the component and the Pelix\r\nframework.\r\nThat way, the component contains only the code required for its task, not for\r\nits bindings with the framework.\r\nA component is an instance of a component factory, a class `manipulated <https://ipopo.readthedocs.io/en/latest/refcards/ipopo.html>`_\r\nby iPOPO `decorators <https://ipopo.readthedocs.io/en/latest/refcards/ipopo_decorators.html>`_.\r\n\r\nFor more information, see the `concepts page <https://ipopo.readthedocs.io/en/latest/refcards/index.html>`_.\r\n\r\n\r\nSample\r\n######\r\n\r\nThis sample gives a quick overview of the usage of iPOPO.\r\nFor more information, take a look at `iPOPO in 10 minutes <https://ipopo.readthedocs.io/en/latest/quickstart.html>`_.\r\n\r\n\r\nService specification\r\n=====================\r\n\r\nIn iPOPO v3, you can use a Python `procotol <https://docs.python.org/3/library/typing.html#typing.Protocol>`_\r\nto define the specification of a service.\r\nA specification class/protocol should be decorated with ``@Specification`` to be\r\ngiven a unique name.\r\nThe components providing that specification should then inherit that specification\r\nclass/protocol in order for the development tools you use to be able to warn if\r\na method is missing or uses invalid types.\r\n\r\nNote that it is possible to skip that step and use a string constant as\r\nspecification like in iPOPO v1.\r\n\r\nHere is a sample description of an Hello World service specification:\r\n\r\n.. code-block:: python\r\n\r\n from typing import Protocol\r\n from pelix.constants import Specification\r\n\r\n @Specification(\"sample.hello\")\r\n class HelloWorld(Protocol):\r\n \"\"\"\r\n Hello world specification: definition of the methods a component providing\r\n that service must implement\r\n \"\"\"\r\n\r\n def hello(self, name: str) -> None:\r\n \"\"\"\r\n Prints hello\r\n \"\"\"\r\n ...\r\n\r\n def bye(self, name: str) -> None:\r\n \"\"\"\r\n Prints bye\r\n \"\"\"\r\n ...\r\n\r\nService provider\r\n================\r\n\r\nThe following code defines a component factory (a class) which instances will\r\nprovide a ``sample.hello`` service.\r\n\r\n.. code-block:: python\r\n\r\n # iPOPO decorators\r\n from pelix.ipopo.decorators import ComponentFactory, Provides, Instantiate\r\n\r\n # Import the specification, if we want to use its type\r\n from specification import HelloWorld\r\n\r\n # Manipulates the class and sets its (unique) factory name\r\n @ComponentFactory(\"hello-provider-factory\")\r\n # Indicate that the components will provide a service\r\n @Provides(HelloWorld)\r\n # Like in iPOPOv1, We could also use the specification name directly:\r\n # @Provides(\"sample.hello\")\r\n # Tell iPOPO to instantiate a component instance as soon as the file is loaded\r\n @Instantiate(\"hello-provider-auto\")\r\n # When using Python protocols, it is recommended to inherit from it to\r\n # benefit from types handling of IDEs.\r\n class HelloProvider(HelloWorld):\r\n \"\"\"\r\n A sample service provider\r\n \"\"\"\r\n def hello(self, name=\"world\"):\r\n \"\"\"\r\n Says hello\r\n \"\"\"\r\n print(\"Hello,\", name, \"!\")\r\n\r\n def bye(self, name=\"cruel world\"):\r\n \"\"\"\r\n Says bye\r\n \"\"\"\r\n print(\"Bye,\", name, \"!\")\r\n\r\nDue to the ``@Instantiate`` decorator, iPOPO will\r\nautomatically instantiate a component when the bundle providing this component\r\nfactory will be started.\r\nIt is also possible to instantiate a component using shell commands or via the\r\niPOPO runtime service\r\n(see `use_ipopo <https://ipopo.readthedocs.io/en/latest/refcards/ipopo.html#pelix.ipopo.constants.use_ipopo>`_).\r\n\r\nEach component instance will provide a ``sample.hello`` service, which can be\r\nconsumed by any bundle or any other component.\r\n\r\n\r\nService consumer\r\n================\r\n\r\nThe following code defines a component factory (a class) which instances will\r\nconsume a ``sample.hello`` service. If multiple services are available, iPOPO\r\nwill select the one with the highest rank and the lowest service ID\r\n(*i.e.* the oldest service).\r\n\r\nIn iPOPO v3, it is again recommended to use typing as much as possible.\r\nFor injected fields and properties, the fields injected with ``@Requires`` should\r\nbe defined at class level with the right type hint: type, optional, list, ...\r\nbased on the requirement configuration.\r\n\r\n.. code-block:: python\r\n\r\n from pelix.ipopo.decorators import ComponentFactory, Instantiate, Invalidate, Requires, Validate\r\n from specification import HelloWorld\r\n\r\n # Manipulates the class and sets its (unique) factory name\r\n @ComponentFactory(\"hello-consumer-factory\")\r\n # Indicate that the components require a sample.hello service to work\r\n # and to inject the found service in the _svc field\r\n # We could also use the specification name instead of the type\r\n @Requires(\"_svc\", HelloWorld)\r\n # Tell iPOPO to instantiate a component instance as soon as the file is loaded\r\n @Instantiate(\"hello-consumer-auto\")\r\n class HelloConsumer:\r\n \"\"\"\r\n A sample service consumer\r\n \"\"\"\r\n\r\n # Define the injected field type for static typing (optional)\r\n _svc: HelloWorld\r\n\r\n @Validate\r\n def validate(self, context):\r\n \"\"\"\r\n Component validated: all its requirements have been injected\r\n \"\"\"\r\n self._svc.hello(\"Consumer\")\r\n\r\n @Invalidate\r\n def invalidate(self, context):\r\n \"\"\"\r\n Component invalidated: one of its requirements is going away\r\n \"\"\"\r\n self._svc.bye(\"Consumer\")\r\n\r\nWhen the bundle providing this component factory will be started, iPOPO will\r\nautomatically instantiate a component, due to the ``@Instantiate`` decorator.\r\n\r\nEach component instance will require a ``sample.hello`` service. Once iPOPO\r\nhas injected all the required services (here, a single ``sample.hello`` service)\r\nin a component instance, this instance will be considered *valid* and iPOPO\r\nwill call its method decorated by ``@Validate``.\r\nThere, the component can consume its dependencies, start threads, etc.\r\nIt is recommended for this method to start threads and to return quickly, as it\r\nblocks iPOPO and the Pelix framework.\r\n\r\nWhen a required service is unregistered by its provider, the component\r\ninstances consuming it are invalidated.\r\nWhen the method decorated by ``@Invalidate`` is called, the service is still\r\ninjected and should be usable (except for special cases, like remote services).\r\n\r\n\r\nRun!\r\n====\r\n\r\nTo run this sample, you'll need to copy the snippets above in different files:\r\n\r\n* copy the *Service specification* snipper in a file named *specification.py*\r\n* copy the *Service provider* snippet in a file named *provider.py*\r\n* copy the *Service consumer* snippet in a file named *consumer.py*\r\n\r\nYou can also find those files in the project repository in the\r\n``samples/hello_world`` folder.\r\n\r\nThen, run a Pelix shell in the same folder as those files, and execute the\r\ncommands listed in this trace:\r\n\r\n.. code-block:: bash\r\n\r\n $ python -m pelix.shell\r\n ** Pelix Shell prompt **\r\n $ # Install the bundles\r\n $ install provider\r\n Bundle ID: 15\r\n $ install consumer\r\n Bundle ID: 16\r\n $ # Start the bundles (the order isn't important here)\r\n $ start 15 16\r\n Starting bundle 15 (provider)...\r\n Starting bundle 16 (consumer)...\r\n Hello, Consumer !\r\n $ # View iPOPO instances\r\n $ instances\r\n +----------------------+------------------------------+-------+\r\n | Name | Factory | State |\r\n +======================+==============================+=======+\r\n | hello-consumer-auto | hello-consumer-factory | VALID |\r\n +----------------------+------------------------------+-------+\r\n | hello-provider-auto | hello-provider-factory | VALID |\r\n +----------------------+------------------------------+-------+\r\n | ipopo-shell-commands | ipopo-shell-commands-factory | VALID |\r\n +----------------------+------------------------------+-------+\r\n 3 components running\r\n $ # View details about the consumer\r\n $ instance hello-consumer-auto\r\n Name.....: hello-consumer-auto\r\n Factory..: hello-consumer-factory\r\n Bundle ID: 16\r\n State....: VALID\r\n Services.:\r\n Dependencies:\r\n Field: _svc\r\n Specification: sample.hello\r\n Filter......: None\r\n Optional.....: False\r\n Aggregate....: False\r\n Handler......: SimpleDependency\r\n Bindings:\r\n ServiceReference(ID=18, Bundle=15, Specs=['sample.hello'])\r\n Properties:\r\n +---------------+---------------------+\r\n | Key | Value |\r\n +===============+=====================+\r\n | instance.name | hello-consumer-auto |\r\n +---------------+---------------------+\r\n\r\n $ # Modify the provider file (e.g. change the 'Hello' string by 'Hi')\r\n $ # Update the provider bundle (ID: 15)\r\n $ update 15\r\n Updating bundle 15 (provider)...\r\n Bye, Consumer !\r\n Hi, Consumer !\r\n $ # Play with other commands (see help)\r\n\r\nFirst, the ``install`` commands are used to install the bundle: they will be\r\nimported but their activator won't be called. If this command fails, the bundle\r\nis not installed and is not referenced by the framework.\r\n\r\nIf the installation succeeded, the bundle can be started: it's activator is\r\ncalled (if any). Then, iPOPO detects the component factories provided by the\r\nbundle and instantiates the components declared using the ``@Instantiate``\r\ndecorator.\r\n\r\nThe ``instances`` and ``instance`` commands can be use to print the state and\r\nbindings of the components. Some other commands are very useful, like ``sl``\r\nand ``sd`` to list the registered services and print their details. Use the\r\n``help`` command to see which ones can be used.\r\n\r\nThe last part of the trace shows what happens when updating a bundle.\r\nFirst, update the source code of the provider bundle, *e.g.* by changing the\r\nstring it prints in the ``hello()`` method.\r\nThen, tell the framework to update the bundle using the ``update`` command.\r\nThis command requires a bundle ID, which has been given as a result of the\r\n``install`` command and can be found using ``bl``.\r\n\r\nWhen updating a bundle, the framework stops it and reloads it (using\r\n`importlib.reload <https://docs.python.org/3/library/importlib.html#importlib.reload>`_).\r\nIf the update fails, the old version is kept.\r\nIf the bundle was active before the update, it is restarted by the framework.\r\n\r\nStopping a bundle causes iPOPO to kill the component instance(s) of the\r\nfactories it provided.\r\nTherefore, no one provides the ``sample.hello`` service, which causes the\r\nconsumer component to be invalidated.\r\nWhen the provider bundle is restarted, a new provider component is instantiated\r\nand its service is injected in the consumer, which becomes valid again.\r\n\r\n\r\nBatteries included\r\n##################\r\n\r\nPelix/iPOPO comes with some useful services:\r\n\r\n* Pelix Shell: a simple shell to control the framework (manage bundles,\r\n show the state of components, ...).\r\n The shell is split in 5 parts:\r\n\r\n * the parser: a shell interpreter class, which can be reused to create other\r\n shells (with a basic support of variables);\r\n * the shell core service: callable from any bundle, it executes the given\r\n command lines;\r\n * the UIs: text UI (console) and remote shell (TCP/TLS, XMPP)\r\n * the commands providers: iPOPO commands, report, EventAdmin, ...\r\n * the completion providers: Pelix, iPOPO\r\n\r\n See the `shell tutorial <http://ipopo.readthedocs.io/en/latest/quickstart.html#play-with-the-shell>`_\r\n for more information.\r\n\r\n* An HTTP service, based on the HTTP server from the standard library.\r\n It provides the concept of *servlet*, borrowed from Java.\r\n\r\n See the `HTTP service reference <http://ipopo.readthedocs.io/en/latest/refcards/http.html>`_\r\n for more information.\r\n\r\n There is also a `routing utility class <http://ipopo.readthedocs.io/en/latest/refcards/http_routing.html>`_,\r\n based on decorators, which eases the development of REST-like servlets.\r\n\r\n* Remote Services: export and import services to/from other Pelix framework or\r\n event Java OSGi frameworks!\r\n\r\n See the `remote services reference <http://ipopo.readthedocs.io/en/latest/refcards/remote_services.html>`_\r\n and the `Remote Service Admin reference <https://ipopo.readthedocs.io/en/latest/refcards/rsa.html>`_\r\n for more information.\r\n The former should be used to link iPOPO instances while the latter targets both iPOPO and Java OSGi frameworks.\r\n\r\nPelix also provides an implementation of the `EventAdmin service <http://ipopo.readthedocs.io/en/latest/refcards/eventadmin.html>`_,\r\ninspired from the `OSGi specification <http://www.osgi.org/Specifications/HomePage>`_.\r\n\r\nFeedback\r\n########\r\n\r\nFeel free to send feedback on your experience of Pelix/iPOPO, via the mailing\r\nlists:\r\n\r\n* User list: https://groups.google.com/g/ipopo-users\r\n* Development list: https://groups.google.com/g/ipopo-dev\r\n* GitHub Discussions: https://github.com/tcalmant/ipopo/discussions\r\n\r\nBugs and features requests can be submitted using the\r\n`Issue Tracker <https://github.com/tcalmant/ipopo/issues>`_ on GitHub.\r\n\r\n\r\nContributing\r\n############\r\n\r\nAll contributions are welcome!\r\n\r\n#. Create an `issue <https://github.com/tcalmant/ipopo/issues>`_ to discuss\r\n about your idea or the problem you encounter\r\n#. `Fork <https://github.com/tcalmant/ipopo/fork>`_ the project\r\n#. Develop your changes\r\n#. Check your code with `pylint <https://pypi.python.org/pypi/pylint/>`_\r\n and `pep8 <https://pypi.python.org/pypi/pep8>`_\r\n#. If necessary, write some unit tests\r\n#. Commit your changes, indicating in each commit a reference to the issue\r\n you're working on\r\n#. Push the commits on your repository\r\n#. Create a *Pull Request*\r\n#. Enjoy!\r\n\r\nPlease note that your contributions will be released under the project's\r\nlicense, which is the `Apache Software License 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`__.\r\n\r\n\r\nCompatibility\r\n#############\r\n\r\nPelix and iPOPO are tested using\r\n`GitHub actions <https://github.com/tcalmant/ipopo/actions>`_\r\ntargetting Python 3.10, 3.11 and 3.12.\r\n\r\niPOPO v3 doesn't support Python 2 neither versions earlier than 3.10.\r\nIf you need to work with those versions of Python, please use iPOPO v1.\r\nYou can then use Remote Services to allow interactions between iPOPO v1 and v3.\r\n\r\n\r\nLicense\r\n#######\r\n\r\niPOPO is released under the `Apache Software License 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`__.\r\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "A service-oriented component model framework",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/tcalmant/ipopo/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a9b8e5ad0a4bcab6f97ca5ac2d962a64518e84d70a9c4cb41a3a401fd802ddb0",
"md5": "8ee4d0797b9a4a79906af98763ee8f59",
"sha256": "d4efe853067430307942dc1c8ad66dcda430f235add4c4b826d746e0fbebf9d0"
},
"downloads": -1,
"filename": "iPOPO-3.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "8ee4d0797b9a4a79906af98763ee8f59",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 399585,
"upload_time": "2024-08-26T14:20:26",
"upload_time_iso_8601": "2024-08-26T14:20:26.576674Z",
"url": "https://files.pythonhosted.org/packages/a9/b8/e5ad0a4bcab6f97ca5ac2d962a64518e84d70a9c4cb41a3a401fd802ddb0/iPOPO-3.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5da162ac3e3175db0c93a5c3f0ca767a79124cfd7be93fd5e3e93d43daf1168c",
"md5": "9b07a703e251f2965d59861255bf3144",
"sha256": "ba26c0bca5a404959c7128156a57325aba402a2512593426daa3f219cc8dff28"
},
"downloads": -1,
"filename": "iPOPO-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "9b07a703e251f2965d59861255bf3144",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 360154,
"upload_time": "2024-08-26T14:20:28",
"upload_time_iso_8601": "2024-08-26T14:20:28.577854Z",
"url": "https://files.pythonhosted.org/packages/5d/a1/62ac3e3175db0c93a5c3f0ca767a79124cfd7be93fd5e3e93d43daf1168c/iPOPO-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-26 14:20:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tcalmant",
"github_project": "ipopo",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "ipopo"
}
JSON
