Documentation & GH Pages about graphql-core-legacy HOT 18 CLOSED

Closing the issue, as is not likely to document this package in short-term.
Any contribution in the docs to graphql-core will be welcome, but not a priority for the core developers.

from graphql-core-legacy.

Hey @jhgg, I didn't have a preference for where they might be hosted, so I didn't set anything up like that in dittos/graphqllib#5

I have been falling behind on keeping up with the Slack channel, is this a fork of graphqllib that expects to be merged back in, or is this the future of the project?

from graphql-core-legacy.

My intent is for this repo to supersede graphqllib. I've been reaching out to @dittos but haven't gotten a response yet. But for now, the show must go on!

from graphql-core-legacy.

But for now, the show must go on!

Agreed! I also like the idea of it being under the umbrella of an organization, hopefully more Python GraphQL libraries/projects will join in, too!

from graphql-core-legacy.

Thanks! In this case I'll edit this issue to be the one for actually documenting things.

from graphql-core-legacy.

@jhgg I've bought a domain for graphene, tomorrow I'll do the "big opening" for it.
Is managed by Jekyll, as is quite easy for creating new content. However, having both Sphinx docs and Jekyll generated pages makes also sense.
We could put some graphql-core pages on it, or we can create a custom gh-pages for this repo.
Either way I can help for using common styling between pages ;)

from graphql-core-legacy.

Yay! Very excited by this initiative!

from graphql-core-legacy.

has there been any progress here?

from graphql-core-legacy.

Btw is this task just about setting up the documentation web pages, or is it also about writing the documentation? Writing docs seems like an awfully big task to ask a single person to do - maybe should be split up into more specific tasks?

from graphql-core-legacy.

All of the above @dgoldstein0. I'm not the best at writing - nor do I have the time to write out full featured docs right now. But if someone can set up the doc site & gh static pages, I can write some stuff from day to day until it's done.

from graphql-core-legacy.

I was going to make a separate issue for my request, but instead I'll add my thoughts here. Could you add to the future documentation a spec and discussion on middleware?

I'm currently writing middleware for handling Google App Engine's NDB Future type, which is slightly different from Python 3.5's Future. I'm following the code and tests for Executor and AsyncioExecutionMiddleware. However, a spec and discussion would be great for helping me (and other middleware authors) ensure I have comprehensive tests and a simple implementation.

from graphql-core-legacy.

Hiya, @py-in-the-sky. The touch points are really just in two places.

For wrapping NDB's Future type, you have to connect their Future to the Deferred object that graphql-core uses internally. It should be as easy as checking when the Resolver returns a NDB Future & then chaining the callback to call deferred.errback() or deferred.callback() with the result or exception.

The other end of the chain is optionally overriding the execution_result to convert the Deferred back into a NDB Future.

The middleware should probably be about 30-40 lines, and fairly straightforward.

Unfortunately I don't have too much time right now to devote to this project. But if you want to send over some code I'd be more than happy to review.

As far as tests go. https://github.com/graphql-python/graphql-core/blob/master/tests_py35/core_execution/test_asyncio_executor.py is comprehensive enough and there's probably a fairly 1 to 1 equivalent for using NDB's Future type.

from graphql-core-legacy.

Thanks, @jhgg !

The other end of the chain is optionally overriding the execution_result to convert the Deferred back into a NDB Future.

I see AsyncioExecutionMiddleware uses this optional override. I'm not sure whether I have a use case for it, but could you explain the motivation for using the execution_result override in AsyncioExecutionMiddleware? What useful things would it allow me to do? I'd appreciate any insights you can provide into your decision-making process on the matter. It could help me reflect further on whether overriding execution_result would be useful for the middleware I'm writing.

from graphql-core-legacy.

It allows the conversion of the return value of executor.execute(...). By default, it is a deferred instance, which lets you attach a callback handler to it. In the asyncio middleware, I link it back to a Future so that it's awaitable. Let's us do:

async def do_stuff():
    result = await executor.execute(" { someQueryHere }")

Basically, developing a middleware takes whatever async primitive and turns it into a deferred (via run_resolve_fn) and then takes the deferred and turns it back into the async primitive (via execution_result) for interop with the async library you're using.

from graphql-core-legacy.

Crystal clear! Thanks!

from graphql-core-legacy.

@jhgg, when you get a chance, could you give me your thoughts on these tests and the implementation?

py-in-the-sky/gae-flask-redux-react-starter-kit@d629930

I just copied your AsyncioExecutionMiddleware implementation and made a few changes to make it work for the NDB Future type.

from graphql-core-legacy.

@py-in-the-sky 👍 lgtm.

from graphql-core-legacy.

http://graphene-python.org/ is up and looks great; can this issue be closed? If not, what remains to be done? I might be interested in trying to write docs.

from graphql-core-legacy.