Facet

Service manager for asyncio (and classic blocking code since version 0.10.0).

• Facet
  • Reasons
    • Asyncio
    • Blocking code
  • Features
  • License
  • Requirements
  • Usage
    • Asyncio
    • Blocking code
  • API
    • Asyncio
      • start
      • stop
      • dependencies
      • add_task
      • run
      • wait
      • graceful_shutdown_timeout
      • running
    • Blocking code
      • start
      • stop
      • dependencies
      • running

Reasons

Asyncio

mode tries to do too much job: - Messy callbacks (on_start, on_started, on_crashed, etc.). - Inheritance restrict naming and forces super() calls. - Forced logging module and logging configuration.

Blocking code

• ExitStack is too low-level to manage services.
• Common api for async and blocking worlds.

Features

• Simple (start, stop, dependencies and add_task).
• Configurable via inheritance (graceful shutdown timeout).
• Mixin (no super() required).
• Requires no runner engine (Worker, Runner, etc.) just plain await or async with/with.

License

facet is offered under MIT license.

Requirements

• python 3.11+

Last version with python 3.6+ support is 0.9.1

Usage

Asyncio

``` python import asyncio from facet import AsyncioServiceMixin

class B(AsyncioServiceMixin): def init(self): self.value = 0

async def start(self):
    self.value += 1
    print("b started")

async def stop(self):
    self.value -= 1
    print("b stopped")

class A(AsyncioServiceMixin): def init(self): self.b = B()

@property
def dependencies(self):
    return [self.b]

async def start(self):
    print("a started")

async def stop(self):
    print("a stopped")

asyncio.run(A().run()) This will produce: b started a started `` Start and stop order determined by strict rule: **dependencies must be started first and stopped last**. That is whyBstarts beforeA. SinceAmay useBinstart` routine.

Hit ctrl-c and you will see: a stopped b stopped Traceback (most recent call last): ... KeyboardInterrupt Stop order is reversed, since A may use B in stop routine. Any raised exception propagates to upper context. facet do not trying to be too smart.

Service can be used as a context manager. Instead of python asyncio.run(A().run()) Code can look like: ``` python async def main(): async with A() as a: assert a.b.value == 1 await a.wait()

asyncio.run(main()) ```

Another service feature is add_task method: ``` python class A(AsyncioServiceMixin): async def task(self): await asyncio.sleep(1) print("task done")

async def start(self):
    self.add_task(self.task())
    print("start done")

asyncio.run(A().run()) This will lead to background task creation and handling: start done task done ``` Any non-handled exception on background task will lead the whole service stack crashed. This is also a key feature to fall down fast and loud.

All background tasks will be cancelled and awaited on service stop.

You can manage dependencies start/stop to start sequently, parallel or mixed. Like this: ``` python class A(AsyncioServiceMixin): def init(self): self.b = B() self.c = C() self.d = D()

@property
def dependencies(self):
    return [
        [self.b, self.c],
        self.d,
    ]

`` This leads to firstbandcstarts parallel, after they successfully starteddwill try to start, and thenaitself start will be called. And on stop routineastop called first, thendstop, then bothbandc` stops parallel.

The rule here is first nesting level is sequential, second nesting level is parallel

Blocking code

Since version 0.10.0 facet can be used in blocking code with pretty same rules. But with limited API. For example: ``` python from facet import BlockingServiceMixin

class B(BlockingServiceMixin): def init(self): self.value = 0

def start(self):
    self.value += 1
    print("b started")

def stop(self):
    self.value -= 1
    print("b stopped")

class A(BlockingServiceMixin): def init(self): self.b = B()

@property
def dependencies(self):
    return [self.b]

def start(self):
    print("a started")

def stop(self):
    print("a stopped")

with A() as a: assert a.b.value == 1 This will produce: b started a started a stopped b stopped `` As you can see, there is nowaitmethod. Waiting and background tasks are on user shoulders and technically can be implemented withconcurrent.futuresmodule. Butfacetdo not provide such functionality, since there are a lot of ways to do it:threading/multiprocessing` and their primitives.

Also, there are no «sequential, parallel and mixed starts/stops for dependencies» feature. So, just put dependencies in dependencies property as a plain list and they will be started/stopped sequentially.

API

Asyncio

Here is public methods you get on inheritance/mixin:

start

python async def start(self): pass Start routine.

stop

python async def stop(self): pass Stop routine.

dependencies

python @property def dependencies(self) -> list[AsyncioServiceMixin | list[AsyncioServiceMixin]]: return [] Should return iterable of current service dependencies instances.

add_task

python def add_task(self, coroutine: Coroutine[Any, Any, Any]) -> asyncio.Task[Any]: Add background task.

run

python async def run(self) -> None: Run service and wait until it stop.

wait

python async def wait(self) -> None: Wait for service stop. Service must be started. This is useful when you use service as a context manager.

graceful_shutdown_timeout

python @property def graceful_shutdown_timeout(self) -> int: return 10 How much total time in seconds wait for stop routines. This property can be overriden with subclass: python class CustomServiceMixin(AsyncioServiceMixin): @property def graceful_shutdown_timeout(self): return 60

running

python @property def running(self) -> bool: Check if service is running

Blocking code

start

python def start(self): pass Start routine.

stop

python def stop(self): pass Stop routine.

dependencies

python @property def dependencies(self) -> list[BlockingServiceMixin | list[BlockingServiceMixin]]: return [] Should return iterable of current service dependencies instances.

running

python @property def running(self) -> bool: Check if service is running