Idea: adding a capabilities fuction?

[dvarrazzo]

Several psycopg features depend on the libpq version and require precise knowledge of when a certain feature was added. For instance, skimming the ifs in the libpq: prepared statements, prepared statements compatibility with pgbouncer, PQhostAddr, async cancelling, set trace flag.

For pipelines the ad-hoc solution of Pipeline.is_supported(), but new needs are emerging for newer features.

Proposal: adding a psycopg.capability() function to check if a certain capability is supported or not. For instance:

def capability(name: str, *, check: bool = False) -> bool | None:
    """
    Verify if a capability is supported by the current libpq library or database function.

    :param name: the name of the capability to check
    :param check: if True, raise `NotSupportedError` if the capability is unsupported or unknown.
    :return: `True` if the capability is supported, `False` if not, `None` if unknown
    """
    ...

If check = True we may raise an error with a descriptive message for what is required to gain the capability, such as these. This could be add at import level to detect early if a capability required by a program is not supported. Otherwise, the result can be checked in an if.

import psycopg
psycopg.capability("pipeline", check=True)

...

if python.capability("pipeline"):
    with conn.pipeline():
       ...

The capabilities might be just strings or we might provide a string enum too to represent them. I would reserve ourselves the possibility to add a new capability check in bugfix releases.

class Capability(str, Enum):
    pipeline = "pipeline"
    close_prepared = "close_prepared"
    pgbouncer_prepared = "pgbouncer_prepared"  # maybe? Just a friendly alias for the above.
    hostaddr = "hostaddr"
    async_cancel = "async_cancel"
    trace_flags = "trace_flags"

I would like to add this feature in 3.2, because several feature conditional to the libpq version are being introduced.

What do you think? @dlax? @asqui?

[dlax]

I like the idea.

Another possible implementation would be to define one function per capability in a capability (or just cap?) module instead of using the "fragile" name: str argument for a single function:

# file cap.py

def pipeline(check: bool = False) -> bool: ...

def close_prepared(check: bool = False) -> bool: ...

...

to be used as:

import psycopg.cap

psycopg.cap.pipeline(check=True)

...

if psycopg.cap.pipeline():
    with conn.pipeline():
       ...

[dvarrazzo]

The reason to have a more "fragile" interface is to make us able to introduce capabilities without violating an interface, and allow some form of forward compatibility, by accepting psycopg.capability("i-dont-know-this-one") as long as the receiver can manage a None.

But it's probably a weak point: I guess we can just document that the module, or the object, might have methods added in bugfix released if deemed necessary.

I would avoid to call the methods pipeline() etc because I can envisage someone writing:

if psycopg.capabilities.pipeline:
    ...

so I would call the methods as verbs:

if psycopg.capabilities.has_pipeline():
    ...

I prefer to make it a class because it would make easier to pass the object around, mock it for testing, etc.

Therefore how does it looks?

# in psycopg/_capabilities.py

class Capabilities:
    def has_pipeline(self, check: bool = False) -> bool:
        ...

# in psycopg/__init__.py

from ._capabilities import Capabilities

capabilities = Capabilities()

[dlax]

I'm fine with has_pipeline() naming. Not sure why a class would be easier to work with than a module: would the class hold some kind of state (that would not be appropriate to be at module-scope)? After all, classes and modules are sort of namespaces; but in contrast with a class, a module is a singleton, so it seems more natural to me in that case. Nothing strong against the class approach though.

[dvarrazzo]

I don't know whether to introduce a cache or not. The fast path should be fast. If the object will only remain a singleton it's not too different that a module, otherwise, when we start passing it around, it would be a module object with a bunch of loose functions and the interface would be less defined. As we are preferring to have one function per check, with a defined interface, it seems to me that making it a module would waste this effort.

I'm whipping together a PoC...