Sort keys

A related area of convergence is comparison functions. Go uses ternary cmp functions, and Python used to. Collective Python experience has shown that while more general, a ternary comparison is rarely needed. Even more so with the ability to reverse and stably sort.

Go does not have the equivalent of Python’s orderable tuples, so a ternary cmp will always have its place. Still, sorting by scalars is extremely common, and Go could add key-based ordering, with iterator support.

Note bound and unbound methods are also first class functions. So models with a standard ordering or identifier could add methods for each. Then pass (*Type).Compare as a cmp function, and (*Type).Key as a key function. The readability of function parameters is even better when referenced by name instead of a lambda.

The key function approach is also simpler and more efficient for comparable use cases. Utilities like slices.CompareFunc could be iter.CompareBy and not repeat logic.

Sets

Go does not have a built-in set type. The options are to use a map explicitly, or via a library which wraps a map and ignores the values. The author’s iterset package demonstrates that a Pythonic approach is now possible. Set operations require either O(1) lookup - which maps already support - or mere iteration. So a custom map type is useful for efficiency, but its methods can support iter.Seq instead, just as Python methods do. This is both more flexible and efficient in most cases.

Take IsSubset as an example. The four interface choices have usage and performance trade-offs.

1. IsSubset(iter.Seq[K], iter.Seq[K]): most flexible, has to convert right argument to #2
2. IsSubset(iter.Seq[K], map[K]V)): fast, zero-copy, and flexible
3. IsSubset(map[K]V), iter.Seq[K]: similar to #1, but converting the right argument may exit early and use less space
4. IsSubset(map[K]V1), map[K]V2): similar to #2, but could exit early with a size check

Without function overloads, designing the interface for all use cases is a challenge. But in no case is forcing the caller to convert both arguments to map[K]struct{} first an improvement.

Conclusion

Go has just started to include iterator utilities like slices.Sorted{Func}. Iterators are going to have a transformative effect on readability.

Cursors and state

Cursors imply state, at least they used to. A database cursor is used for iterating over a result set. Meaning it has transactional integrity to pick up where it left off.

The vast majority of GraphQL APIs are inherently stateless. The “cursor” is being decoded as input to a new request, and offers no guarantees. From this observation, the advice falls apart.

The problem with stateless pagination is inconsistency; items may shift, appear, or disappear. Which gives the client the perception of missing or duplicate items. This happens regardless of whether the pagination is offset or ID based. Arguably worse in the case of IDs, since the reference can move arbitrarily or be gone.

Cursors don’t solve the consistency problem; they give the client the false impression of solving the problem.

Opaqueness and compatibility

The claim is that an opaque cursor is compatible across changes. Changed to do what exactly, would be the more relevant question.

Taking a step back, what is the problem being solved here? We assume there is a list of items, with an inherent ordering, and too many to return to the client with acceptable performance.

Given those assumptions, the first obvious step is an optional size limit. That is not in dispute; the disagreement if over the “offset”. A simple and versatile solution is a range filter over whatever field(s) is relevant to ordering. This is not even remotely controversial when the field in question has a name like date. In other words, “pagination” is not necessarily the problem that needs solving.

Range filters with a size limit are sufficient to implement pagination, and new optional filters are always backwards compatible. They also offer the flexibility of search, whereas cursors can only be used iteratively. And what if the client does not want visibility into the range filters? That is exactly what offset is for; offset is a range filter over an implied index field.

There is a reason why the recommendation does not offer a useful example of this supposed compatibility; there isn’t one. The advice is equivocating on the ambiguity of an after: $ID filter. Is the ID field relevant to the ordering?

• If yes, then it is just another range filter
• If no, then it is just another placeholder for index

There is no third case. There is no future secret field that relates to ordering, is relevant to the client, but somehow still opaque to the client.

Stateless pagination is a combination of range filters and size limits. No matter what the input fields are called. A true stateful is cursor is opaque precisely because it does not represent any known field.

Build backends

The crux of the poor user experience is choosing a build backend. The reader at this stage does not know what a “build backend” is, and moreover does not care.

The 4 backends in the tutorial are described here in their presented order. An example snippet of a pyproject.toml file is included, mostly assuming defaults, with a couple common options:

• dynamic version
• package data for type information

requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.sdist]
include = ["<package>/*"]

[tool.hatch.version]
path = "<package>/__init__.py"

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[tool.setuptools]
packages = ["<package>"]

[tool.setuptools.dynamic]
version = {attr = "<package>.__version__"}

[build-system]
requires = ["flit-core>=3.4"]
build-backend = "flit_core.buildapi"

requires = ["pdm-backend"]
build-backend = "pdm.backend"

[tool.pdm]
version = {source = "file", path = "<package>/__init__.py"}

Evaluations

Recommendations

It would be disingenuous to not end with recommendations, since the refusal to - in a document titled tool recommendations - is the problem. The PyPA endorses pip, build, and twine as standard tools, even though there are alternatives.

Author’s disclosures: I am a long-time Python developer of several packages, and a couple with extension modules. I use no project management tools, and am not affiliated with any of these projects.

1. flit-core - No criticisms. The dynamic version and description feature are a plus; not having any flit-specific sections feels like less coupling.
2. pdm-backend - No criticisms. A natural choice if one wants tests in the source distribution.
3. hatchling - The file selection issue is significant. Users need a warning that they should include an sdist section and check their tarballs. Many are going to have unnecessarily large distributions, and someone with a local secrets directory - whether ignored or untracked - is going to have a seriously bad day.
4. setuptools - Perpetually handicapped by backwards compatibility. The only advantage setuptools had was being already installed. It may be time to disavow it for new projects without extension modules.

My projects currently use setuptools for purely historical reasons. For new projects, I would likely use flit-core. I may switch-over existing projects, though there is really no incentive to.

Unless a standard emerges, of course.

Addendum

A meta case could be made for Flit(-core) as well: that its limited scope and independence from a project manager is itself an asset. Whereas choosing Hatch(ling) or PDM(-backend) feels like picking a side. Flit can position itself as the minimalist choice for those who resent having to choose.

And yet the situation is even more absurd. There has been an under-documented default the entire time. The default is the legacy mode of setuptools, which differs only in its path setup. If one forgoes a dynamic __version__ attribute - which perhaps importlib.metadata was intended to do - then one can have a pyproject.toml with no references to build backends.

Multiple queries

A common beginner question is “can there be multiple queries in a request”. The question would be better phrased as “can multiple fields on the root query type be requested”. The answer is of course, because requesting multiple fields on a type is normal. The implementation would have to go out of its way to restrict that behavior on just the root type. The only need for further clarity would be to introduce aliases for duplicate fields.

Flat namespace

GraphQL types share a global namespace, causing conflicts when federating multiple graphs. Nothing can be done about that unless GraphQL adopts namespaces.

But many APIs design the root query type to have unnecessarily flat fields. One often sees a hierarchy of types and fields below the root, but the top-level fields resemble a loose collections of functions. Verbs at the top level; nouns the rest of the way down. This design choice appears to be in a feedback loop with the notion of “root fields”.

Even the convention of calling the root query type Query demonstrates a lack of specificity. In a service-oriented architecture, a particular service might be more narrowly defined.

Mutations

Top-level mutation fields are special in one aspect: they are executed in order. This has resulted in even flatter namespaces for mutations,

mutation {
    createUser # executed first
    deleteUser
}

This is not necessary, but seems widely believed that it is. Nested mutations work just fine.

mutation {
    user {
        create # executed in arbitrary order
        delete
    }
}

If the underlying reason is truly execution order, the client could be explicit instead.

mutation {
    created: user { # executed first
        create
    }
    deleted: user {
        delete
    }
}

There is no reason it has to influence API design.

Static methods

At the library level, the effect is top-level resolvers are implemented as functions (or static methods), whereas all other resolver are methods. This may lead to redundant or inefficient implementations, is oddly inconsistent, and is contrary to the documentation.

A resolver function receives four arguments:

obj The previous object, which for a field on the root Query type is often not used.

Sure, “often not used” by the developer of the API. That does not mean “should be unset” by the GraphQL library, but that is what has happened. Some libraries even exclude the object parameter entirely. In object-oriented libraries like strawberry, the code looks unnatural.

import strawberry
 
 
@strawberry.type
class Query:
    @strawberry.field
    def instance(self) -> bool | None:
        return None if self is None else isinstance(self, Query)


schema = strawberry.Schema(Query)
query = '{ instance }'
schema.execute_sync(query).data

{'instance': None}

Strawberry allows omitting self for this reason, creating an implicit staticmethod.

Root values

Libraries which follow the reference javascript implementation allow setting the root value explicitly.

schema.execute_sync(query, root_value=Query()).data

{'instance': True}

Strawberry unofficially supports supplying an instance, but it has no effect.

schema = strawberry.Schema(Query())
schema.execute_sync(query).data

{'instance': None}

And of course self can be of any type.

schema.execute_sync(query, root_value=...).data

{'instance': False}

Moreover, the execute functions are for internal usage. Each library will vary in how to configure the root in a production application. Strawberry requires subclassing the application type.

import strawberry.asgi


class GraphQL(strawberry.asgi.GraphQL):
    def __init__(self, root):
        super().__init__(strawberry.Schema(type(root)))
        self.root_value = root

    async def get_root_value(self, request):
        return self.root_value

Example

Consider a more practical example where data is loaded, and clearly should not be reloaded on each request.

@strawberry.type
class Dictionary:
    def __init__(self, source='/usr/share/dict/words'):
        self.words = {line.strip() for line in open(source)}

    @strawberry.field
    def is_word(self, text: str) -> bool:
        return text in self.words

Whether Dictionary is the query root - or attached to the query root - it should be instantiated only once. Of course it can be cached, but again there is a more natural way to write this outside the context of GraphQL.

@strawberry.type
class Query:
    dictionary: Dictionary

    def __init__(self):
        self.dictionary = Dictionary()

Caching, context values, and root values are all clunky workarounds compared to the consistency of letting the root be Query() instead of Query. The applications which do not require this feature would never notice the difference.

The notion of “root fields” behaving as “top-level functions” has resulted in needless confusion, poorer API design, and incorrect implementations.

Original implementation

import jnettool.tools.elements.NetworkElement
import jnettool.tools.Routing
import jnettool.tools.RouteInsector

ne = jnettool.tools.elements.NetworkElement('171.0.2.45')

try:
    routing_table = ne.getRoutingTable()
except jnettool.tools.elements.MissingVar:
    logging.exception('No routing table found')
    ne.cleanup('rollback')
else:
    num_routes = routing_table.getSize()
    for RToffset in range(num_routes):
        route = routing_table.getRouteByIndex(RToffset)
        name = route.getName()
        ipaddr = route.getIPAddr()
        print "%15s -> %s" % (name, ipaddr)
finally:
    ne.cleanup('commit')
    ne.disconnect()

Proposed interface

from nettools import NetworkElement

with NetworkElement('171.0.2.45') as ne:
    for route in ne.routing_table:
        print "%15s -> %s" % (route.name, route.ipaddr)

Proposed solution

import jnetool.tools.elements.NetworkElement
import jnetool.tools.Routing

class NetworkElementError(Exception):
    pass

class NetworkElement(object):

    def __init__(self, ipaddr):
        self.ipaddr = ipaddr
        self.oldne = jnetool.tools.elements.NetworkElement(ipaddr)

    @property
    def routing_table(self):
        try:
            return RoutingTable(self.oldne.getRoutingTable())
        except jnetool.tools.elements.MissingVar:
            raise NetworkElementError('No routing table found')

    def __enter__(self):
        return self

    def __exit__(self, exctype, excinst, exctb):
        if exctype == NetworkElementError:
            logging.exception('No routing table found')
            self.oldne.cleanup('rollback')
        else:
            self.oldne.cleanup('commit')
        self.oldne.disconnect()

    def __repr__(self):
        return '%s(%r)' % (self.__class__.__name__, self.ipaddr)


class RoutingTable(object):

    def __init__(self, oldrt):
        self.oldrt = oldrt

    def __len__(self):
        return self.oldrt.getSize()

    def __getitem__(self, index):
        if index >= len(self):
            raise IndexError
        return Route(self.oldrt.getRouteByIndex(index))


class Route(object):

    def __init__(self, old_route):
        self.old_route = old_route

    @property
    def name(self):
        return self.old_route.getName()

    @property
    def ipaddr(self):
        return self.old_route.getIPAddr()

No dispute that the interface is superior, but the implementation is using delegation as if it is dogma. The usage pattern has to be extrapolated from one example, but here are the issues:

• Custom exceptions are not helpful if they do nothing. The consumer of this code does not use NetworkElementError, and has lost the traceback if it did. Error hiding is not error handling.
• Comparing classes with == is widely considered an anti-pattern, as opposed to is or issubclass.
• The Route object doesn’t need to delegate. There is no reason to assume that the underlying attribute access must be lazy, particularly since the iteration could be lazy instead. A named tuple or dataclass would suffice here.
• The RoutingTable object doesn’t need to delegate. There is no need to support random access or lazy evaluation. Its only addition to the interface is to be sequence-like, which could be trivially accomplished by a sequence.
• The NetworkElement doesn’t need to delegate. It has the same name, same constructor, a repr designed to appear as the original, and only extends behavior. If this doesn’t pass as an is-a relation, nothing does.

Simple solution

import collections
from jnettool.tools import elements

Route = collections.namedtuple('Route', ['name', 'ipaddr'])

class NetworkElement(elements.NetworkElement):
    @property
    def routing_table(self):
        table = self.getRoutingTable()
        routes = map(table.getRouteByIndex, range(table.getSize()))
        return [Route(route.getName(), route.getIPAddr()) for route in routes]

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        if isinstance(exc_val, elements.MissingVar):
            logging.exception("No routing table found")
            self.cleanup('rollback')
        else:
            self.cleanup('commit')
        self.disconnect()

Which version is more maintainable? Surely the simpler one.

Which version is more extensible? Well, by whom? The implementor can extend either just as easily. The caller can use the inherited version without losing any functionality.

So a better question might be which version is more flexible or reusable? Surely the inherited version, because the delegated version would need to access oldne. Even naming the delegate is a pain point, because one has to decide if it is a part of the public interface or not. Should it have 0, 1, or 2 leading underscores? Delegation is often touted as achieving both encapsulation and extensibility, despite being opposing goals.

Finally, there is also a simpler interface, again with the caveat that there is only one usage example. An iterable of 2-field objects, one of which is called name, and “points to” the other field. Sounds like a mapping.

class NetworkElement(elements.NetworkElement):
    @property
    def routing_table(self):
        table = self.getRoutingTable()
        routes = map(table.getRouteByIndex, range(table.getSize()))
        return {route.getName(): route.getIPAddr() for route in routes}
    ...

Renamed

So the critical feature of the @ syntax is to retain the defined object’s name; otherwise it is just a function call. Which leads to the first example of overuse: defining a new object just to change the name. Consider this example adapted from a popular project.

class Response:
    def __bool__(self):
        return self.ok

    @property
    def ok(self):
        ...

Since a property wraps a function, it is natural to make the function have the implementation instead. Then it becomes clear that the property does not share the same name, so why bother with @.

class Response:
    def __bool__(self):
        ...

    ok = property(__bool__)

A related scenario is where the local name of the function is irrelevant, which is typical in wrapped functions:

@functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

This is a convenience function for invoking update_wrapper() as a function decorator when defining a wrapper function. It is equivalent to partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated). For example:

>>> from functools import wraps
>>> def my_decorator(f):
...     @wraps(f)
...     def wrapper(*args, **kwds):
...         print('Calling decorated function')
...         return f(*args, **kwds)
...     return wrapper

The “convenience function” is useless indirection when the wrapper is immediately returned. Even the documentation points out that wraps is just a partial function. The example could be simply:

def my_decorator(f):
    def wrapper(*args, **kwds):
        print('Calling decorated function')
        return f(*args, **kwds)
    return update_wrapper(wrapper, f)

Giving partial(update_wrapper, wrapped=f) a short name does not make it any clearer conceptually.

With blocks

Another sign is if the decorator’s functionality only executes code before or after the wrapped function. Context managers are inherently more flexible by providing the same functionality for any code block. In some cases a function boundary is natural to bookend, e.g., logging or timing. The question is whether the function block is too broad a context to manage.

Decorators were introduced in version 2.4; context managers in 2.5. All ancient history now, but decorators had a ~2 year head start. For example, transactions are a seminal use case for context managers, but Django pre-dates 2.5, so it had a transaction decorator first. This is how transactions are currently presented:

atomic is usable both as a decorator:

from django.db import transaction

@transaction.atomic
def viewfunc(request):
    # This code executes inside a transaction.
   do_stuff()

and as a context manager:

from django.db import transaction

def viewfunc(request):
    # This code executes in autocommit mode (Django's default).
    do_stuff()

    with transaction.atomic():
        # This code executes inside a transaction.
        do_more_stuff()

So it has both, but the decorator is presented first, and is it a good example? Seems likely that a full request would have setup and teardown work that is unrelated to a database transaction. It is uncontroversial to want try blocks to be as narrow as possible. Surely there is no benefit to a request operation rolling back a vacuous transaction, nor a response operation rolling back a transaction that was committable.

Any context manager can be trivially transformed into a decorator; the converse is not true. And even if the function block is coincidentally perfect, a with block has negligible impact on readability. It is just indentation.

Partial functions

Next is a lack of appreciation of partially bound functions. Many decorator examples go out of their way to write an unnecessary def statement, in order to make using a decorator look natural. The below example is common in Python tutorials.

import functools

def repeat(num_times):
    def decorator_repeat(func):
        @functools.wraps(func)
        def wrapper_repeat(*args, **kwargs):
            for _ in range(num_times):
                value = func(*args, **kwargs)
            return value
        return wrapper_repeat
    return decorator_repeat

@repeat(num_times=4)
def greet(name):
    print(f"Hello {name}")

greet("World")

Hello World
Hello World
Hello World
Hello World

First the obligatory observation that abstracting a for loop in Python is not necessarily a good idea. But assuming that is the goal, it is still worth questioning why repeating 4 times is coupled to the name greet. Is print supposed to represent the “real” function in this example, or should the wrapped function be named greet_4x? It is much simpler to start with the basic functionality and postpone how to wrap it.

def repeat(num_times, func, *args, **kwargs):
    for _ in range(num_times):
        value = func(*args, **kwargs)
    return value

def greet(name):
    print(f"Hello {name}")

repeat(4, greet, "World")

Hello World
Hello World
Hello World
Hello World

We can stop there really. But even assuming that the goal is to bind the repetition, using partial functions is still simpler.

from functools import partial

greet_4x = partial(repeat, 4, greet)
greet_4x("World")

Hello World
Hello World
Hello World
Hello World

Not exactly the same without wraps, but that would be trivial to add. Futhermore it is less useful because partial objects can be easily introspected. Now onto the next - and dubious - assumption: that we really want it used as a decorator. This requires assuming the body of greet is not a simple call to an underlying wrapped function, and yet for some reason the repetition is supposed to be coupled to the wrapper function’s name anyway. Still simpler:

repeats = partial(partial, repeat, 4)

@repeats
def greet(name):
    print(f"Hello {name}")

greet("World")

Hello World
Hello World
Hello World
Hello World

Nested partials may appear a little too clever, but they are just the flatter version of the original nested repeat functions. And again, none of this indirection is necessary.

For loops

A real-world example of repeat is retrying functions until success, optionally with delays. A popular one uses examples like:

@backoff.on_exception(backoff.expo, requests.exceptions.RequestException)
def get_url(url):
    return requests.get(url)

The same pattern (ahem) repeats. The decorated function is a trivial wrapper around the “real” function. Why not:

get_url = backoff.on_exception(backoff.expo, requests.exceptions.RequestException)(requests.get)

Furthermore, for loops can be customized via the __iter__ protocol, just as with blocks are customizable. The author’s waiter package demonstrates the same functionality with for loops and undecorated functions.

Advocacy

So before assuming a decorator is the right abstraction, start with whether a def function is the right abstraction. Building out functionality in this progression works well:

1. code blocks: with and for and customizable
2. flat functions
3. nested functions: using partial
4. decorated functions

Fields are nullable by default.

Most type systems which recognise “null” provide both the common type and the nullable version of that type, whereby default types do not include “null” unless explicitly declared. However, in a GraphQL type system, every field is nullable by default.

This is true in the context of the spec and the reference graphql-js implementation. Whether it is relevant to a developer creating an API is entirely dependent on which graphql framework they are using.

• graphene-python: nullable by default. Types are wrapped by a NonNull type or passed a required=True flag.
• strawberry-graphql: non-null by default. Following the Python convention, types must be annotated as nullable explicitly.
• ariadne and every schema-first framework: assuming there is a default, it would be nullable.

Does the graphql schema have a “default”? In the sense that a Type must be annotated with a whole extra character to become Type!. Not in the same sense that query is the default operation, for example, because the operation can be omitted. There is no explicit Type? syntax which is being defaulted to. It is just as accurate to say there is no default in the schema; there is a syntactic binary choice.

Fields should default to nullable.

When designing a GraphQL schema, it’s important to keep in mind all the problems that could go wrong and if “null” is an appropriate value for a failed field. Typically it is, but occasionally, it’s not. In those cases, use non-null types to make that guarantee.

So not whether nulls literally are the default, but the recommendation that one should default to using nullable types. This advice would be fine in theory, but in practice has reversed what is “typical” versus “occasional”. Typically, errors propagate up to an enclosing type, possibly all the way up. It is common for trivial scalars to never be null, and like any tree there are far more leaf nodes than higher nodes.

It is also rare to want nulls in a list. Better to omit them; even more so for input lists.

The standard advice is often combined with a compatibility claim.

Including non-null fields and arguments in a schema makes that schema harder to evolve where a client expects a previously non-null field’s value to be provided in a response. For example, if a non-null email field on a User type is converted to a nullable field, will the clients that use that field be prepared to handle this potentially null value after the schema is updated? Similarly, if the schema changes in such a way that a client is suddenly expected to send a previously nullable argument with a request, then this may also result in a breaking change.

Notice the common mistake: the first sentence contradicts the last with respect to arguments. Null compatibility advice applies only to outputs; the opposite is true for inputs. Even the staunchest pro-null advocate must concede that one should “default” to inputs being non-null.

A better question to ask is “what would a null in this field represent”? In an implemented API, if the field can actually be null, then there will be an answer to that question. But if the field is truly never null, then there may be no answer. You may find yourself not just bike-shedding, but counterfactual bike-shedding. How is the client supposed to “correctly” handle a response that is impossible, in a scenario that is indescribable?

There is no need to speculate on what a hypothetical API might do, nor to agree on a “default” behavior. Analyze how the implemented API actually behaves, and describe it accurately.

Optional == Nullable.

GraphQL is far from the first to conflate “optional” with “nullable”, but it has elevated it to a next level. There is no context in which the quote “nullable types are always optional and non-null types are always required” is both true and not vacuous.

• Output field
  • From the client’s perspective, optional would mean the client can omit the field from the request. No, all fields are optional in that sense.
  • From the server’s perspective, optional would mean the server can omit the field from the response. No, all fields are required in that sense. Nullables may null, not omitted.
• Input field or argument
  • From the client’s perspective, optional would mean the client can omit the input. Yes, so they are equivalent in this case? No, an input can also be optional by having a default value, even with a non-null type. Nullable implies optional; optional does not imply nullable.
  • From the server’s perspective, optional would mean omission is equivalent to a sent null value. No, the spec clarifies that those two scenarios are semantically different.

If the value null was provided for an input object field, and the field’s type is not a non-null type, an entry in the coerced unordered map is given the value null. In other words, there is a semantic difference between the explicitly provided value null versus having not provided a value.

So there is only one context in which the concept of “optional” has any meaning: when the client can omit the input. And being nullable is only one of two ways for an input to be optional. That makes “optional” roughly 12.5% identical to “nullable”. optional == omittable != nullable

Alternatives

So rather than just be a rant, let’s use this hard-fought contrarian knowledge to create better APIs.

Advocacy

The above suggestions are in this GraphQL proposal, and can be see implemented in the graphique project. It demonstrates fields like: slice(offset: Int! = 0, length: Int = null, reverse: Boolean! = false).

When debating this topic, beware of undue JavaScript influence from a client perspective. For example, undefined is neither a GraphQL nor a JSON concept. And all of the input points listed apply to input coercion of variables as well.

Example

The effect is an entire class of common problems which should be trivial. Typically - but not limited to - lists of objects which have since been deleted or for which the user is not authorized. The problem can be seen in the best practices example on authorization.

Authorization is a type of business logic that describes whether a given user/session/context has permission to perform an action or see a piece of data. For example:

“Only authors can see their drafts”

…

//Authorization logic lives inside postRepository
var postRepository = require('postRepository');

var postType = new GraphQLObjectType({
  name: ‘Post’,
  fields: {
    body: {
      type: GraphQLString,
      resolve: (post, args, context, { rootValue }) => {
        return postRepository.getBody(context.user, post);
      }
    }
  }
});

The incomplete example does not implement “only authors can see their drafts”. It implements “only authors can see the body field of a draft”. But the user would still know the post exists and see all metadata which is not protected. “Drafts” being plural and all, a parent field with a list of posts is missing from the example. Surely the preferred solution would be to not return the unauthorized post in the list at all.

The same problem exists if the post should be hidden for any reason, including deletion. It cannot be overstated how common a problem this is in real world APIs, and GraphQL offers no solution.

Well, as constructed. The workaround is to abandon the premise of the example and push the authorization logic up to the posts field. But even that fails to address race conditions, which are particularly relevant for deletions.

Interestingly, it would also be more efficient if the query which determined the list of posts were “correct” in the first place. This relates to a previous article GraphQL is the new ORM, which focused on performance. Ultimately this is the same issue: the elegance of single-purpose resolvers fails when context has been lost, and that failure is especially common and noticeable when lists are involved.

Solution

A general solution would be to allow resolvers to be coroutines, or equivalently to allow a finalize resolver. Here is an example implemented in graphql-core:

--- a/src/graphql/execution/execute.py
+++ b/src/graphql/execution/execute.py
@@ -546,6 +546,8 @@ class ExecutionContext:
             completed = self.complete_value(
                 return_type, field_nodes, info, path, result
             )
+            if field_def.finalize is not None:
+                completed = field_def.finalize(completed, info, *args)
             if self.is_awaitable(completed):
                 # noinspection PyShadowingNames
                 async def await_completed() -> Any:
diff --git a/src/graphql/type/definition.py b/src/graphql/type/definition.py

--- a/src/graphql/type/definition.py
+++ b/src/graphql/type/definition.py
@@ -471,6 +471,7 @@ class GraphQLField:
     deprecation_reason: Optional[str]
     extensions: Dict[str, Any]
     ast_node: Optional[FieldDefinitionNode]
+    finalize: Optional[GraphQLFieldResolver]
 
     def __init__(
         self,
@@ -482,6 +483,7 @@ class GraphQLField:
         deprecation_reason: Optional[str] = None,
         extensions: Optional[Dict[str, Any]] = None,
         ast_node: Optional[FieldDefinitionNode] = None,
+        finalize: Optional[GraphQLFieldResolver] = None,
     ) -> None:
         if args:
             args = {
@@ -500,6 +502,7 @@ class GraphQLField:
         self.deprecation_reason = deprecation_reason
         self.extensions = extensions or {}
         self.ast_node = ast_node
+        self.finalize = finalize
 
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__} {self.type!r}>"

With that minor extension, fields can supply a finalize resolver in addition to the usual one.

from dataclasses import dataclass
from graphql import (
    GraphQLField,
    GraphQLInt,
    GraphQLList,
    GraphQLNonNull,
    GraphQLObjectType,
    GraphQLSchema,
    GraphQLString,
    graphql_sync,
    print_schema,
)

post_data = {1: "first"}


@dataclass
class Post:
    id: int

    def body(self, info) -> str:
        return post_data.get(self.id)


postType = GraphQLObjectType(
    name="Post",
    fields={
        "id": GraphQLNonNull(GraphQLInt),
        "body": GraphQLField(GraphQLString, resolve=Post.body),
    },
)

postsField = GraphQLField(
    GraphQLNonNull(GraphQLList(GraphQLNonNull(postType))),
    resolve=lambda *_: [Post(1), Post(2)],
    finalize=lambda objs, _: [obj for obj in objs if obj["body"] is not None],
)

schema = GraphQLSchema(
    query=GraphQLObjectType(name="Query", fields={"posts": postsField})
)
print(print_schema(schema))

type Query {
  posts: [Post!]!
}

type Post {
  id: Int!
  body: String
}

source = "{ posts { id body } }"
graphql_sync(schema, source)

ExecutionResult(data={'posts': [{'id': 1, 'body': 'first'}]}, errors=None)

Addendum

In Python, this could be implemented as a generator-based coroutine. Similar to contextlib.contextmanager or pytest fixtures, the generator would yield types, receive the result maps, and yield one more final result.

def resolve(*_):
    objs = yield [Post(1), Post(2)]
    yield [obj for obj in objs if obj["body"] is not None]

But there are some obstacles to that approach. The result data is in map (dict) form, not the domain types, so the code is not necessarily more readable. Additionally, generators can already be used to implement list types (whether intentional or not); graphql-core simply iterates the result. There would need to be another mechanism to distinguish a true coroutine from a regular generator.

Speaking of domain types, notice how convenient and readable using a dataclass is, and how redundant the GraphQL type definition is. In strawberry-graphql, the schema is automatically derived from the domain types. The example would be simply:

@strawberry.type
class Post:
    id: int

    @strawberry.field
    def body(self) -> str:
        return post_data.get(self.id)

Example

The problems can be seen immediately in GraphQL’s own introductory resolver example.

Query: {
  human(obj, args, context, info) {
    return context.db.loadHumanByID(args.id).then(
      userData => new Human(userData)
    )
  }
}

Human: {
  name(obj, args, context, info) {
    return obj.name
  }
}

What makes the name resolver trivial? It’s pre-fetched by loadHumanByID, whose only parameter is id, so it’s clearly unaware of whether name has been requested. What if the requested field was a nested object, or a json field, or just a large text blob? Then one would clearly be directed towards using a non-trivial resolver which fetches the field on demand. Of course, but then whatever work is common in the human id lookup is duplicated.

This is by no means specific to SQL or relational databases, but SQL is a convenient lingua franca of databases to demonstrate the inefficiency. The choices are:

• SELECT * FROM human WHERE id = ?
• SELECT field FROM human WHERE id = ? repeated for each “expensive” field

Even in the simplest possible example, over-fetching has already occurred, and the only proposed workaround is under-fetching. The single query we want is:

• SELECT f1, f2, ... FROM human WHERE id = ? for requested fields

In other words, exactly what happens with ORMs, except even ORMs typically offer an option of requesting a subset of fields. Naturally the problem gets worse with list fields.

Human: {
  appearsIn(obj) {
    return obj.appearsIn // returns [ 4, 5, 6 ]
  }
}

Human: {
  starships(obj, args, context, info) {
    return obj.starshipIDs.map(
      id => context.db.loadStarshipByID(id).then(
        shipData => new Starship(shipData)
      )
    )
  }
}

Now there are two sets of associate keys (.appearsIn and .starshipIDs) that have been over-fetched. Nonetheless starships is under-fetched as well. The starships resolver is neither the most efficient nor the simplest way of resolving this field:

• fetch all the data by human id in the starships resolver
• fetch all the data in bulk by starshipIDs
• push the resolution down to the Starship layer if forced to fetch one at a time

The example implementation seems to be going out of its way to showcase JavaScript promises. And the assumptions being made about the underlying data store are unusual:

1. The data is relational in nature.
2. Associative keys have neglible cost to pre-fetch.
3. But joins are not available.
4. And neither are primary key in queries.

Workaround

From GraphQL’s best practices

GraphQL is designed in a way that allows you to write clean code on the server, where every field on every type has a focused single-purpose function for resolving that value. However without additional consideration, a naive GraphQL service could be very “chatty” or repeatedly load data from your databases.

This is commonly solved by a batching technique, where multiple requests for data from a backend are collected over a short period of time and then dispatched in a single request to an underlying database or microservice by using a tool like Facebook’s DataLoader.

That’s an understatement. It’s not clear how “naive” differs from best practice.

Clearly there is value in transforming multiple primary key = queries into a single primary key in query. As in the starships example however, that can be done more simply in the parent resolver. There is more value in not needing a primary key in query at all. Furthermore adding caching to a dataloader avoids the central issue.

Again reminiscent of ORMs, any data layer can add caching. The point is efficiently resolving a query requires context, which strict adherence to single-purpose resolvers explictly disregards.

Aggregation

The inefficencies becomes even more glaring when moving beyond associative keys. Nearly any aggregation requires knowing what summaries are requested. Such as if the appearsIn field optionally included counts or times. Using SQL as an example again, the query would resemble one of:

• SELECT distinct field FROM ...
• SELECT field, count(*) FROM ... GROUP BY field

The conditional logic if "count" in requested_fields must exist in some form in the code, because the alternatives are over-fetching or under-fetching. Both of which are far more inefficient in this scenario than in the “select N+1” problem. A dataloader-esque approach is not going to be applicable to “group by” operations.

Computation

One last generalized example: computed fields. What are typically query flags in REST (and RPC) APIs, become field selections in GraphQL.

For example, computing scores in a search engine interface. Instead of a scores: Boolean! = false input option, the more obvious approach would be to skip score calculation when the score field isn’t requested.

As with aggregation, the same pattern recurs. It’s unacceptable to over-fetch, i.e., compute the scores when not needed. It’s worse still to under-fetch, i.e., run some sort of lean search that will find matches and then go back and compute scores later.

Solution

The inescapable conclusion is that in some cases parent resolvers need to know which of their children are being requested. There’s no need to throw away GraphQL’s server-side resolver hierarchy. No one is advocating a thousand line root resolver named RunIt that processes the entire query.

All that’s needed is a conceptual shift which encourages introspecting the GraphQLResolveInfo object. The requested fields are right there waiting to be useful, but good luck finding documentation and examples to that effect. In every non-trivial GraphQL project, this author has used a utility like:

def selections(node):
    """Return tree of field name selections."""
    nodes = getattr(node.selection_set, 'selections', [])
    return {node.name.value: selections(node) for node in nodes}

Those fields would be checked or passed to a data layer as needed. For example, in Django’s ORM, it could be as simple as appending a query set with .values(*selections(*info.nodes)).

Well, almost. The next issue is that typical GraphQL model validators raise an error if required fields are missing. Thanks validator; the field is missing because the client didn’t request it.

This is actually a different age-old problem: equivocating “optional” and “nullable”. GraphQL requires populating all requested fields, and specifiying whether they may be null. Server-side implementations understandably, but still incorrectly, interpret that by making nullables optional and non-nullables required at the model layer. So typically it’s necessary to pad resolved objects with empty (but not null) data.

Although a minor problem, it reveals the bias related to single-purpose resolvers. The point of GraphQL is to efficiently return only the requested fields, yet standard practice in GraphQL models is to require populating fields that haven’t been requested.

Over- and under- fetching can be addressed directly in resolvers, with the data layer’s own interface, instead of hidden behind another abstraction layer.

In theory

Good points, and why limit this advice to file descriptors? Any resource may be limited or require exclusivity; that’s why they’re called resources. Similarly one should always explicitly call dict.clear when finished with a dict. After all, “there are no guarantees as to when the runtime will actually run the <object’s> destructor. And”code that deals with many such objects may exhaust those resources unnecessarily”, such as memory, or whatever else is in the dict.

But in all seriousness, this advice is applying a notably higher standard of premature optimization to file descriptors than to any other kind of resource. There are plenty of Python projects that are guaranteed to run on CPython for a variety of reasons, where destructors are immediately called. And there are plenty of Python projects where file descriptor usage is just a non-issue. It’s now depressingly commonplace to see this in setup.py files:

with open("README.md") as readme:
    long_description = readme.read()

Let’s consider a practical example: a load function which is supposed to read and parse data given a file path.

import csv
import json

def load(filepath):
    """the supposedly bad way"""
    return json.load(open(filepath))

def load(filepath):
    """the supposedly good way"""
    with open(filepath) as file:
        return json.load(file)

def load(filepath):
    """with a different file format"""
    with open(filepath) as file:
        return csv.reader(file)

Which versions work correctly? Are you sure? If it’s not immediately obvious why one of these is broken, that’s the point. In fact, it’s worth trying out before reading on.

…

The csv version returns an iterator over a closed file. It’s a violation of procedural abstraction to know whether the result of load is lazily evaluated or not; it’s just supposed to implement an interface. Moreover, according to this best practice, it’s impossible to write the csv version correctly. As absurd as it sounds, it’s just an abstraction that can’t exist.

Defiantly clever readers are probably already trying to fix it. Maybe like this:

def load(filepath):
    with open(filepath) as file:
        yield from csv.reader(file)

No, it will not be fixed. This version only appears to work by not closing the file until the generator is exhausted or collected.

This trivial example has deeper implications. If one accepts this practice, then one must also accept that storing a file handle anywhere, such as on an instance, is also disallowed. Unless of course that object then virally implements it owns context manager, ad infinitum.

Furthermore it demonstrates that often the context is not being managed locally. If a file object is passed another function, then it’s being used outside of the context. Let’s revisit the json version, which works because the file is fully read. Doesn’t a json parser have some expensive parsing to do after it’s read the file? It might even throw an error. And isn’t it desirable, trivial, and likely that the implementation releases interest in the file as soon as possible?

So in reality there are scenarios where the supposedly good way could keep the file open longer than the supposedly bad way. The original inline version does exactly what it’s supposed to do: close the file when all interested parties are done with it. Python uses garbage collection to manage shared resources. Any attempt to pretend otherwise will result in code that is broken, inefficient, or reinventing reference counting.

A true believer now has to accept that json.load is a useless and dangerous wrapper, and that the only correct implementation is:

def load(filepath):
    with open(filepath) as file:
        contents = file.read()
    return json.loads(contents)

This line of reasoning reduces to the absurd: a file should never be passed or stored anywhere. Next an example where the practice has caused real-world damage.

In practice

Requests is one of the most popular python packages, and officially recommended. It includes a Session object which supports closing via a context manager. The vast majority of real-world code uses the the top-level functions or single-use sessions.

response = requests.get(...)

with requests.Session() as session:
    response = session.get(...)

Sessions manage the connection pool, so this pattern of usage is establishing a new connection every time. There are popular standard API clients which seriously do this, for every single request to the same endpoint.

Requests’ documentation prominently states that “Keep-alive and HTTP connection pooling are 100% automatic”. So part of the blame may lay with that phrasing, since it’s only “automatic” if sessions are reused. But surely a large part of the blame is the dogma of closing sockets, and therefore sessions, explicitly. The whole point of a connection pool is that it may leave connections open, so users who genuinely need this granularity are working at the wrong abstraction layer. http.client is already builtin for that level of control.

Tellingly, requests’ own top-level functions didn’t always close sessions. There’s a long history to that code, including a version that only closed sessions on success. An older version was causing warnings, when run to check for such warnings, and was being blamed for the appearance of leaking memory. Those threads are essentially debating whether a resource pool is “leaking” resources.

Truce

Prior to with being introduced in Python 2.5, it was not recommended that inlined reading of a file required a try... finally block. Far from it, in the past idioms like open(...).read() and for line in open(...) were lauded for being succinct and expressive. But if all this orphaned file descriptor paranoia was well-founded, it would have been a problem back then too.

Finally, let’s address readability. It could be argued (though it rarely is) that showing the reader when the file is closed has inherent value. Conveniently, that tends to align with having opened the file for writing anyway, thereby needing an reference to it. In which case, the readability is approximately equal, and potential pitfalls are more realistic. But readability is genuinely lost when the file would have been opened in a inline expression.

The best practice is unjustifiably special-casing file descriptors, and not seeing its own reasoning through to its logical conclusion. This author proposes advocating for anonymous read-only open expressions. Your setup script is not going to run out of file descriptors because you wrote open("README.md").read().

Window

import itertools

def window(iterable, size=2):
    """Generate a sliding window of values."""
    its = itertools.tee(iterable, size)
    return zip(*(itertools.islice(it, index, None) for index, it in enumerate(its)))

list(window('abcde'))

[('a', 'b'), ('b', 'c'), ('c', 'd'), ('d', 'e')]

That’s simple, and close to optimal. There is slight overhead in iterating an islice object, so a minor variant would be to force the step-wise iteration in advance.

import collections

def window(iterable, size=2):
    """Generate a sliding window of values."""
    its = itertools.tee(iterable, size)
    for index, it in enumerate(its):
        collections.deque(itertools.islice(it, index), 0)  # exhaust iterator
    return zip(*its)

list(window('abcde'))

[('a', 'b'), ('b', 'c'), ('c', 'd'), ('d', 'e')]

Chunks

A lesser-known and under-utilized feature of iter is that in can take a callable (of no arguments) and a sentinel to create an iterator. A perfect use case of the “loop and a half” idiom.

def chunks(iterable, size):
    """Generate adjacent chunks of data"""
    it = iter(iterable)
    return iter(lambda: tuple(itertools.islice(it, size)), ())

list(chunks('abcde', 3))

[('a', 'b', 'c'), ('d', 'e')]

This should also be optimal, for reasonable sizes.

Sequences with dispatch

Rather than explicitly check isinstance, this is a perfect use case for functools.singledispatch.

import functools
from collections.abc import Sequence

window = functools.singledispatch(window)

@window.register
def _(seq: Sequence, size=2):
    for index in range(len(seq) - size + 1):
        yield seq[index:index + size]

list(window('abcde'))

['ab', 'bc', 'cd', 'de']

list(window(iter('abcde')))

[('a', 'b'), ('b', 'c'), ('c', 'd'), ('d', 'e')]

chunks = functools.singledispatch(chunks)

@chunks.register
def _(seq: Sequence, size):
    for index in range(0, len(seq), size):
        yield seq[index:index + size]

list(chunks('abcde', 3))

['abc', 'de']

list(chunks(iter('abcde'), 3))

[('a', 'b', 'c'), ('d', 'e')]

Python 1

Prior to version 2.0, Python had neither list comprehensions nor nested scopes. Therefore simple map and filter operations had to use a for... append loop, or lambda. But the lacked of nested scopes was inherently crippling to the latter approach.

x = 2
map(lambda y: y * x, range(5))

<map at 0x108e57250>

A NameError would have been raised on x, because it’s not defined in the inner scope. One clever work-around was to shadow default arguments.

x = 2
list(map(lambda y, x=x: y * x, range(5)))

[0, 2, 4, 6, 8]

Unsurprisingly, that was widely viewed as an ugly hack. Many resigned themselves to for... append loops instead.

Python 2

Then Python added list comprehensions in 2.0, and that became the one obvious way to do it.

x = 2
[y * x for y in range(5)]

[0, 2, 4, 6, 8]

Python acquired nested scopes in the next version, 2.1, but the damage was done. Functional programming in Python in general, and lambda in particular, was widely frowned upon. Even though the lack of nested scopes affected all inner functions used in any context; it was never really about lambda per se.

Python 3

It’s sometimes claimed to this day that map and filter only exist for backwards compatibility. But that belies the history of Python 3. map, filter, and reduce were all considered for removal. But only reduce was banished to the functools module. map and filter were not only retained, but updated to return iterators.

So it’s already dubious to claim that using a built-in is unapproved. But the real point is that map and filter remain a higher level abstraction. Sure, with lambda there are the same number of logical components, and it’s just a matter of syntactic sugar. But there is some abstraction value when the functions already have a name.

It’s also commonly pointed out that generator expressions are superior because they can do a map and filter simultaneously, but crucially only if the filter comes first. Consider this task: normalizing an iterable of strings.

values = 'sample ', ' '
list(filter(None, map(str.strip, values)))

['sample']

Note list is only being used for printing, and should be ignored for the sake of comparisons.

As for the alternative, surely calling strip twice to use a single expression is just plain cheating. So really the only option is:

[value for value in (value.strip() for value in values) if value]

['sample']

Some would consider nested comprehensions already enough to separate with a temporary name. But that’s inadvertently acknowledging how much more verbose it is.

Can it really be claimed that the latter is more readable than the former? It’s just boilerplate, which never seems acknowledged in small examples. But if one only has to double the size of the context to show how verbose comprehensions are, doesn’t that demonstrate the value of map and filter.

Epilogue

And now a shameless plug of the author’s placeholder package for readers who appreciate function-style programming. It provides syntactic sugar for lambda.

from placeholder import _

list(map(_ * 2, range(5)))

[0, 2, 4, 6, 8]

But even speaking as the author, map isn’t the best use case. Sort keys are a much better example, since there is no competing syntax.

min(['ab', 'ba'], key=_[-1])

'ba'

Python 3.8’s new assignment expressions provide yet another alternative.