buvar


Namebuvar JSON
Version 0.43.16 PyPI version JSON
download
home_pagehttps://github.com/diefans/buvar
SummaryAsyncio plugins, components, dependency injection and configs
upload_time2024-12-05 13:08:26
maintainerNone
docs_urlNone
authorOliver Berger
requires_python<4.0,>=3.7
licenseNone
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            Búvár
=====

This is heavily inspired by `Pyramid`_ and my daily needs to fastly create and
maintain microservice like applications.


a plugin mechanic
-----------------

- plugin may depend on other plugins

- plugins yield tasks to run

- a context registry serves as a store for application components created by plugins

- a dependency injection creates intermediate components

- a config source is mapped to plugin specific configuration and may be fully
  overridden by environment vars

- structlog boilerplate for json/tty logging

- fork the process and share bound sockets

- pytest fixtures to reduce testing boilerplate


You bootstrap like following:

.. code-block:: python

    from buvar import plugin

    plugin.stage("some.module.with.prepare")


.. code-block:: python

   # some.module.with.prepare
   from buvar import context, plugin

   class Foo:
       ...


   async def task():
       asyncio.sleep(1)


   async def server():
       my_component = context.get(Foo)
       await asyncio.Future()


   # there is also plugin.Teardown and plugin.Cancel
   async def prepare(load: plugin.Loader):
       await load('.another.plugin')

       # create some long lasting components
       my_component = context.add(Foo())

       # you may run simple tasks
       yield task()

       # you may run server tasks
       yield server()


a components and dependency injection solution
----------------------------------------------

Dependency injection relies on registered adapters, which may be a function, a
method, a class, a classmethod or a generic classmthod.

Dependencies are looked up in components or may be provided via kwargs.


.. code-block:: python

   from buvar import di

   class Bar:
       pass

   class Foo:
       def __init__(self, bar: Bar = None):
           self.bar = bar

       @classmethod
       async def adapt(cls, baz: str) -> Foo:
           return Foo()

   async def adapt(bar: Bar) -> Foo
       foo = Foo(bar)
       return foo


   async def task():
       foo = await di.nject(Foo, baz="baz")
       assert foo.bar is None

       bar = Bar()
       foo = await di.nject(Foo, bar=bar)
       assert foo.bar is bar

   async def prepare():
       di.register(Foo.adapt)
       di.register(adapt)

       yield task()



a config source
---------------

:code:`buvar.config.ConfigSource` is just a :code:`dict`, which merges
arbitrary dicts into one. It serves as the single source of truth for
application variability.

You can load a section of config values into your custom `attrs`_ class instance. ConfigSource will override values by environment variables if present.


`config.toml`

.. code-block:: toml

   log_level = "DEBUG"
   show_warnings = "yes"

   [foobar]
   some = "value"


.. code-block:: bash

   export APP_FOOBAR_SOME=thing


.. code-block:: python

   import attr
   import toml

   from buvar import config

   @attr.s(auto_attribs=True)
   class GeneralConfig:
       log_level: str = "INFO"
       show_warnings: bool = config.bool_var(False)


   @attr.s(auto_attribs=True)
   class FoobarConfig:
      some: str


   source = config.ConfigSource(toml.load('config.toml'), env_prefix="APP")

   general_config = source.load(GeneralConfig)
   assert general_config == GeneralConfig(log_level="DEBUG", show_warnings=True)

   foobar_config = source.load(FoobarConfig, 'foobar')
   assert foobar_config.some == "thing"


There is a shortcut to the above approach provided by
:code:`buvar.config.Config`, which requires to be subclassed from it with a
distinct :code:`section` attribute. If one adds a :code:`buvar.config.ConfigSource`
component, he will receive the mapped config in one call.

.. code-block:: python

   from buvar import config, plugin


   @attr.s(auto_attribs=True)
   class GeneralConfig(config.Config):
       log_level: str = "INFO"
       show_warnings: bool = config.bool_var(False)


   @attr.s(auto_attribs=True)
   class FoobarConfig(config.Config, section="foobar"):
       some: str


   async def prepare(load: plugin.Loader):
       # this would by typically placed in the main CLI entry point
       source = context.add(config.ConfigSource(toml.load('config.toml'), env_prefix="APP"))

       # to provide the adapter to di, which could also be done in the main entry point
       await load(config)
       foobar_config = await di.nject(FoobarConfig)


a structlog
-----------

Just `structlog`_ boilerplate.

.. code-block:: python

   import sys

   from buvar import log

   log_config = log.LogConfig(tty=sys.stdout.isatty(), level="DEBUG")
   log_config.setup()


forked process and shared sockets
---------------------------------

You may fork your process and bind and share sockets, to leverage available
CPUs e.g. for serving an aiohttp microservice.

Signals like INT, TERM, HUP are forwarded to the child processes.


.. code-block:: python

    import aiohttp.web
    from buvar import fork, plugin, di, context
    from buvar_aiohttp import AioHttpConfig


    async def hello(request):
        return aiohttp.web.Response(body=b"Hello, world")


    async def prepare_aiohttp(load: plugin.Loader):
        await load("buvar_aiohttp")

        app = await di.nject(aiohttp.web.Application)
        app.router.add_route("GET", "/", hello)


    context.add(AioHttpConfig(host="0.0.0.0", port=5678))

    fork.stage(prepare_aiohttp, forks=0, sockets=["tcp://:5678"])


pytest
------

There are a couple of pytest fixtures provided to get your context into a
reasonable state:

:code:`buvar_config_source`
    A :code:`dict` with arbitrary application settings.

:code:`buvar_context`
    The basic context staging operates on.

:code:`buvar_stage`
    The actual stage processing all plugins.

:code:`buvar_load`
    The loader to add plugins to the stage.

:code:`buvar_plugin_context`
    The context all plugins share, when they are prepared.


Following markers may be applied to a test

:code:`buvar_plugins(plugin, ...)`
    Load all plugins into plugin context.


.. code-block:: python

    import pytest


    async def prepare():
        from buvar import context

        context.add("foobar")


    @pytest.mark.asyncio
    @pytest.mark.buvar_plugins("tests.test_testing")
    async def test_wrapped_stage_context():
        from buvar import context, plugin

        assert context.get(str) == "foobar"
        assert context.get(plugin.Cancel)


    @pytest.mark.asyncio
    @pytest.mark.buvar_plugins()
    async def test_wrapped_stage_context_load(buvar_load):
        from buvar import context, plugin

        await buvar_load(prepare)
        assert context.get(str) == "foobar"
        assert context.get(plugin.Cancel)


.. _Pyramid: https://github.com/Pylons/pyramid
.. _structlog: https://www.structlog.org/en/stable/
.. _attrs: https://www.attrs.org/en/stable/


            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/diefans/buvar",
    "name": "buvar",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.7",
    "maintainer_email": null,
    "keywords": null,
    "author": "Oliver Berger",
    "author_email": "diefans@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/83/a8/aca55b5594a1ef6afa15ab88f541fbe1a063b5cfb96ad094f260a8df3693/buvar-0.43.16.tar.gz",
    "platform": null,
    "description": "B\u00fav\u00e1r\n=====\n\nThis is heavily inspired by `Pyramid`_ and my daily needs to fastly create and\nmaintain microservice like applications.\n\n\na plugin mechanic\n-----------------\n\n- plugin may depend on other plugins\n\n- plugins yield tasks to run\n\n- a context registry serves as a store for application components created by plugins\n\n- a dependency injection creates intermediate components\n\n- a config source is mapped to plugin specific configuration and may be fully\n  overridden by environment vars\n\n- structlog boilerplate for json/tty logging\n\n- fork the process and share bound sockets\n\n- pytest fixtures to reduce testing boilerplate\n\n\nYou bootstrap like following:\n\n.. code-block:: python\n\n    from buvar import plugin\n\n    plugin.stage(\"some.module.with.prepare\")\n\n\n.. code-block:: python\n\n   # some.module.with.prepare\n   from buvar import context, plugin\n\n   class Foo:\n       ...\n\n\n   async def task():\n       asyncio.sleep(1)\n\n\n   async def server():\n       my_component = context.get(Foo)\n       await asyncio.Future()\n\n\n   # there is also plugin.Teardown and plugin.Cancel\n   async def prepare(load: plugin.Loader):\n       await load('.another.plugin')\n\n       # create some long lasting components\n       my_component = context.add(Foo())\n\n       # you may run simple tasks\n       yield task()\n\n       # you may run server tasks\n       yield server()\n\n\na components and dependency injection solution\n----------------------------------------------\n\nDependency injection relies on registered adapters, which may be a function, a\nmethod, a class, a classmethod or a generic classmthod.\n\nDependencies are looked up in components or may be provided via kwargs.\n\n\n.. code-block:: python\n\n   from buvar import di\n\n   class Bar:\n       pass\n\n   class Foo:\n       def __init__(self, bar: Bar = None):\n           self.bar = bar\n\n       @classmethod\n       async def adapt(cls, baz: str) -> Foo:\n           return Foo()\n\n   async def adapt(bar: Bar) -> Foo\n       foo = Foo(bar)\n       return foo\n\n\n   async def task():\n       foo = await di.nject(Foo, baz=\"baz\")\n       assert foo.bar is None\n\n       bar = Bar()\n       foo = await di.nject(Foo, bar=bar)\n       assert foo.bar is bar\n\n   async def prepare():\n       di.register(Foo.adapt)\n       di.register(adapt)\n\n       yield task()\n\n\n\na config source\n---------------\n\n:code:`buvar.config.ConfigSource` is just a :code:`dict`, which merges\narbitrary dicts into one. It serves as the single source of truth for\napplication variability.\n\nYou can load a section of config values into your custom `attrs`_ class instance. ConfigSource will override values by environment variables if present.\n\n\n`config.toml`\n\n.. code-block:: toml\n\n   log_level = \"DEBUG\"\n   show_warnings = \"yes\"\n\n   [foobar]\n   some = \"value\"\n\n\n.. code-block:: bash\n\n   export APP_FOOBAR_SOME=thing\n\n\n.. code-block:: python\n\n   import attr\n   import toml\n\n   from buvar import config\n\n   @attr.s(auto_attribs=True)\n   class GeneralConfig:\n       log_level: str = \"INFO\"\n       show_warnings: bool = config.bool_var(False)\n\n\n   @attr.s(auto_attribs=True)\n   class FoobarConfig:\n      some: str\n\n\n   source = config.ConfigSource(toml.load('config.toml'), env_prefix=\"APP\")\n\n   general_config = source.load(GeneralConfig)\n   assert general_config == GeneralConfig(log_level=\"DEBUG\", show_warnings=True)\n\n   foobar_config = source.load(FoobarConfig, 'foobar')\n   assert foobar_config.some == \"thing\"\n\n\nThere is a shortcut to the above approach provided by\n:code:`buvar.config.Config`, which requires to be subclassed from it with a\ndistinct :code:`section` attribute. If one adds a :code:`buvar.config.ConfigSource`\ncomponent, he will receive the mapped config in one call.\n\n.. code-block:: python\n\n   from buvar import config, plugin\n\n\n   @attr.s(auto_attribs=True)\n   class GeneralConfig(config.Config):\n       log_level: str = \"INFO\"\n       show_warnings: bool = config.bool_var(False)\n\n\n   @attr.s(auto_attribs=True)\n   class FoobarConfig(config.Config, section=\"foobar\"):\n       some: str\n\n\n   async def prepare(load: plugin.Loader):\n       # this would by typically placed in the main CLI entry point\n       source = context.add(config.ConfigSource(toml.load('config.toml'), env_prefix=\"APP\"))\n\n       # to provide the adapter to di, which could also be done in the main entry point\n       await load(config)\n       foobar_config = await di.nject(FoobarConfig)\n\n\na structlog\n-----------\n\nJust `structlog`_ boilerplate.\n\n.. code-block:: python\n\n   import sys\n\n   from buvar import log\n\n   log_config = log.LogConfig(tty=sys.stdout.isatty(), level=\"DEBUG\")\n   log_config.setup()\n\n\nforked process and shared sockets\n---------------------------------\n\nYou may fork your process and bind and share sockets, to leverage available\nCPUs e.g. for serving an aiohttp microservice.\n\nSignals like INT, TERM, HUP are forwarded to the child processes.\n\n\n.. code-block:: python\n\n    import aiohttp.web\n    from buvar import fork, plugin, di, context\n    from buvar_aiohttp import AioHttpConfig\n\n\n    async def hello(request):\n        return aiohttp.web.Response(body=b\"Hello, world\")\n\n\n    async def prepare_aiohttp(load: plugin.Loader):\n        await load(\"buvar_aiohttp\")\n\n        app = await di.nject(aiohttp.web.Application)\n        app.router.add_route(\"GET\", \"/\", hello)\n\n\n    context.add(AioHttpConfig(host=\"0.0.0.0\", port=5678))\n\n    fork.stage(prepare_aiohttp, forks=0, sockets=[\"tcp://:5678\"])\n\n\npytest\n------\n\nThere are a couple of pytest fixtures provided to get your context into a\nreasonable state:\n\n:code:`buvar_config_source`\n    A :code:`dict` with arbitrary application settings.\n\n:code:`buvar_context`\n    The basic context staging operates on.\n\n:code:`buvar_stage`\n    The actual stage processing all plugins.\n\n:code:`buvar_load`\n    The loader to add plugins to the stage.\n\n:code:`buvar_plugin_context`\n    The context all plugins share, when they are prepared.\n\n\nFollowing markers may be applied to a test\n\n:code:`buvar_plugins(plugin, ...)`\n    Load all plugins into plugin context.\n\n\n.. code-block:: python\n\n    import pytest\n\n\n    async def prepare():\n        from buvar import context\n\n        context.add(\"foobar\")\n\n\n    @pytest.mark.asyncio\n    @pytest.mark.buvar_plugins(\"tests.test_testing\")\n    async def test_wrapped_stage_context():\n        from buvar import context, plugin\n\n        assert context.get(str) == \"foobar\"\n        assert context.get(plugin.Cancel)\n\n\n    @pytest.mark.asyncio\n    @pytest.mark.buvar_plugins()\n    async def test_wrapped_stage_context_load(buvar_load):\n        from buvar import context, plugin\n\n        await buvar_load(prepare)\n        assert context.get(str) == \"foobar\"\n        assert context.get(plugin.Cancel)\n\n\n.. _Pyramid: https://github.com/Pylons/pyramid\n.. _structlog: https://www.structlog.org/en/stable/\n.. _attrs: https://www.attrs.org/en/stable/\n\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Asyncio plugins, components, dependency injection and configs",
    "version": "0.43.16",
    "project_urls": {
        "Homepage": "https://github.com/diefans/buvar"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "dc5b348711427363112d190b8975fdcbff217a8b6dc24fcb7d9818844d0f7c73",
                "md5": "530231356fd8a6b67f1d33fa812247ae",
                "sha256": "c5b6170692413b15f9d9e7806043ecd5c66bc6f16e19378b3f778a7c3c69083a"
            },
            "downloads": -1,
            "filename": "buvar-0.43.16-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_28_x86_64.whl",
            "has_sig": false,
            "md5_digest": "530231356fd8a6b67f1d33fa812247ae",
            "packagetype": "bdist_wheel",
            "python_version": "cp310",
            "requires_python": "<4.0,>=3.7",
            "size": 680616,
            "upload_time": "2024-12-05T13:08:27",
            "upload_time_iso_8601": "2024-12-05T13:08:27.873190Z",
            "url": "https://files.pythonhosted.org/packages/dc/5b/348711427363112d190b8975fdcbff217a8b6dc24fcb7d9818844d0f7c73/buvar-0.43.16-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_28_x86_64.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "6fc9d2d8503ad7f55bfb916c841470747b90b41e5dd33c83b0c260bdf75520bc",
                "md5": "30580471c36dc822252381de08012dd2",
                "sha256": "c5ff30d2f61cb3473dbae42487c3ead11d9ca612da90c83f594d6ca3d6b866af"
            },
            "downloads": -1,
            "filename": "buvar-0.43.16-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_28_x86_64.whl",
            "has_sig": false,
            "md5_digest": "30580471c36dc822252381de08012dd2",
            "packagetype": "bdist_wheel",
            "python_version": "cp311",
            "requires_python": "<4.0,>=3.7",
            "size": 728170,
            "upload_time": "2024-12-05T13:08:27",
            "upload_time_iso_8601": "2024-12-05T13:08:27.945818Z",
            "url": "https://files.pythonhosted.org/packages/6f/c9/d2d8503ad7f55bfb916c841470747b90b41e5dd33c83b0c260bdf75520bc/buvar-0.43.16-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_28_x86_64.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "f33f90cae80cc2ba7b68e42e6544c038540b27374fbbca4b78121cb510442f1f",
                "md5": "cc93554a3a9f69e675d509f05cf95e20",
                "sha256": "edb3ba83b5a9a142f499c63f82af66e49cbde4564765ec31b85ef2603e1c6534"
            },
            "downloads": -1,
            "filename": "buvar-0.43.16-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_28_x86_64.whl",
            "has_sig": false,
            "md5_digest": "cc93554a3a9f69e675d509f05cf95e20",
            "packagetype": "bdist_wheel",
            "python_version": "cp312",
            "requires_python": "<4.0,>=3.7",
            "size": 745430,
            "upload_time": "2024-12-05T13:08:27",
            "upload_time_iso_8601": "2024-12-05T13:08:27.779758Z",
            "url": "https://files.pythonhosted.org/packages/f3/3f/90cae80cc2ba7b68e42e6544c038540b27374fbbca4b78121cb510442f1f/buvar-0.43.16-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_28_x86_64.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "83a8aca55b5594a1ef6afa15ab88f541fbe1a063b5cfb96ad094f260a8df3693",
                "md5": "8efc7707fd893a9778a727ab2b50ca39",
                "sha256": "67f4445480bfe74b44321abb37126db747b7e436f110c7edfe4a0d4d9c35202f"
            },
            "downloads": -1,
            "filename": "buvar-0.43.16.tar.gz",
            "has_sig": false,
            "md5_digest": "8efc7707fd893a9778a727ab2b50ca39",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.7",
            "size": 33218,
            "upload_time": "2024-12-05T13:08:26",
            "upload_time_iso_8601": "2024-12-05T13:08:26.178127Z",
            "url": "https://files.pythonhosted.org/packages/83/a8/aca55b5594a1ef6afa15ab88f541fbe1a063b5cfb96ad094f260a8df3693/buvar-0.43.16.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-05 13:08:26",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "diefans",
    "github_project": "buvar",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": true,
    "tox": true,
    "lcname": "buvar"
}
        
Elapsed time: 0.37214s