Improve documentation

[djnnvx]

First of all I would like to say this project is very cool, and I would definitely see the benefit of using this in an app i'm building. Problem is, besides the README, I don't really know what can I do to best implement this.

I would for sure be open to write the docs myself on how to use it. Do you have any plans on adding them in the future ? Would you be open to talk about it by email or something ?

Best,
bogdzn

[gi0baro]

@bogdzn thank you!

I'm absolutely open to pull requests aiming to add documentation and update the README of the project.
Do you have any suggestions/expectations about it? For instance, do you expect to have just some additional details of granian command parameters in addition to what you can see with the --help option, or something different?

[djnnvx]

Yes, I think that would be great. (Actually, now that I think about it, it would be great to specify that a --help flag is available, because it might not be obvious to everyone)

Mostly, I would want information on the high-level python bindings without looking at the code.

Maybe there is a way to extend the logging class, for instance, in order to have more (or less) verbose info directly centralized into my application. Also, some cookbooks to integrate into FastAPI, or django in an efficient way could be interesting, because you might want to do something like this:

import asyncio
import uvicorn

from api import app as app_fastapi
from scheduler import app as app_rocketry


class Server(uvicorn.Server):
    """Customized uvicorn.Server

    Uvicorn server overrides signals and we need to include
    Rocketry to the signals."""
    def handle_exit(self, sig: int, frame) -> None:
        app_rocketry.session.shut_down()
        return super().handle_exit(sig, frame)


async def main():
    "Run scheduler and the API"
    server = Server(config=uvicorn.Config(app_fastapi, workers=1, loop="asyncio"))

    api = asyncio.create_task(server.serve())
    sched = asyncio.create_task(app_rocketry.serve())

    await asyncio.wait([sched, api])

if __name__ == "__main__":
    asyncio.run(main())

I used Rocketry in this example, which is quite similar as Celery in this example, because having periodic jobs on a specific worker is quite a common need, and it would be helpful to have it run in the same unix process

Is there any documentation on related subjects ? I was thinking of using sphinx for such a project, and maybe have the CI autogenerate new doc version on each push to master

[gi0baro]

Yes, I think that would be great. (Actually, now that I think about it, it would be great to specify that a --help flag is available, because it might not be obvious to everyone)

Probably I can add few details on the README.

Maybe there is a way to extend the logging class, for instance, in order to have more (or less) verbose info directly centralized into my application.

At the moment the only option is to choose the logging verbosity. AFAIK at the moment the logging bindings provided by pyo3-log don't support using custom loggers. Eventually I can dig a bit into their code and see what we can do to add this possibility.

I used Rocketry in this example, which is quite similar as Celery in this example, because having periodic jobs on a specific worker is quite a common need, and it would be helpful to have it run in the same unix process

I'm afraid this is hardly achievable with the current version of Granian. As a matter of fact, your application is not served from the process you use to start Granian, but from child processes launched by Granian itself, even with just one worker. In order to customise the behaviour so deeply, probably the only viable option is to write your own spawn method based on the ASGI one

granian/granian/server.py

Lines 84 to 133 in e5139e2

	@staticmethod
	def _spawn_asgi_worker(
	worker_id,
	callback_loader,
	socket,
	loop_impl,
	threads,
	pthreads,
	threading_mode,
	http_mode,
	http1_buffer_size,
	websockets,
	log_level,
	ssl_ctx
	):
	from granian._loops import loops, set_loop_signals
	configure_logging(log_level)
	loop = loops.get(loop_impl)
	sfd = socket.fileno()
	callback = callback_loader()
	lifespan_handler = LifespanProtocol(callback)
	loop.run_until_complete(lifespan_handler.startup())
	if lifespan_handler.interrupt:
	return
	shutdown_event = set_loop_signals(loop, [signal.SIGTERM, signal.SIGINT])
	worker = ASGIWorker(
	worker_id,
	sfd,
	threads,
	pthreads,
	http_mode,
	http1_buffer_size,
	websockets,
	*ssl_ctx
	)
	serve = getattr(worker, {
	ThreadModes.runtime: "serve_rth",
	ThreadModes.workers: "serve_wth"
	}[threading_mode])
	serve(
	_asgi_call_wrap(callback),
	loop,
	contextvars.copy_context(),
	shutdown_event.wait()
	)
	loop.run_until_complete(lifespan_handler.shutdown())

and pass it to the serve method of the Granian instance with the spawn_target parameter

granian/granian/server.py

Line 303 in e5139e2

def serve(self, spawn_target = None, target_loader = None):

But a this point, looking at your code, my first question would be: why don't you use the ASGI lifespan protocol directly in your FastAPI application to start and shutdown the rocketry server?

Is there any documentation on related subjects ? I was thinking of using sphinx for such a project, and maybe have the CI autogenerate new doc version on each push to master

I am not a big fan of Sphinx or any documentation generation project, as in general I see a very low value in the produced documentation (most of the IDEs out there can probably help you more with typing annotations). I would prefer some proper hand written documentation, maybe we can produce some markdown files with the relevant scopes we want to cover, like:

• CLI arguments
• Granian class interfaces
• Extending Granian behaviour

Probably also an architectural overview would be nice, but I surely need to write it by myself.

[djnnvx]

I can get started on documenting CLI arguments and submit a PR, if you want

I didn't know the Lifespan protocol was a thing. Thank you for pointing it out! Thank you also for your very detailed response, I will try to implement this to my application this week-end, & let you know whether there are any particular things that I found hard when getting started. That way, it could also maybe help you have a more detailed overview of what it needed for people to get started with your project ?

[gi0baro]

I can get started on documenting CLI arguments and submit a PR, if you want

Absolutely, thank you!

That way, it could also maybe help you have a more detailed overview of what it needed for people to get started with your project ?

It would help a lot for sure!

[djnnvx]

Ok, will get started on it at the end of the week. Please do let me know if there is anything else I can do as well, I'll let you know if I have the time!