Doc standard should specify a consistent way to describe a returned deferred Failure.

Open
#6,811 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
documentation

Research direction

Start by reviewing pydoctor's existing handling of @return, @rtype, and @raises fields and the documentation standard referenced in the issue. Define a consistent way to describe deferred Failure results without conflating them with ordinary returns, and verify that the standard and pydoctor behavior agree, including the relationship to issue #6812.

Written by the indexing model from the issue text.

Description

enhancement new priority-normal pydoctor
wsanchez's avatar @wsanchez reported
Trac ID trac#6811
Type enhancement
Created 2013-11-05 20:03:49Z

The documentation standard should specify a consistent way to describe a returned deferred Failure.

Here’s an example interface docstring:

    def recordsFromQuery(expressions, operand=Operand.AND):
        """
        Find records by composing a query consisting of an iterable of
        expressions and an operand.

        @param expressions: expressions to query against
        @type expressions: iterable of L{object}s

        @param operand: an operand
        @type operand: a L{NamedConstant}

        @return: The matching records.
        @rtype: deferred iterable of L{IDirectoryRecord}s

        @raises: L{QueryNotSupportedError} if the query is not
            supported by this directory service.
        ""”

This method should always return a deferred. It should never actually raise, or return a non-deferred value.

The returned deferred will usually fire with an iterable of IDirectoryRecords. (This part of the docstring poses another issue, #6812.)

But if an item in expressions is of an unknown expression type, or the given operand is of an unknown type, then the deferred will fire with a Failure wrapping a QueryNotSupportedError exception.

Putting the faille mode into the @return/@rtype fields seems wrong, as this is much more akin to an exception than a return value.

It seems like we need pydoctor to support an @fails field or something like that, similar to @raises and that we should document these in that way.

Searchable metadata 
trac-id__6811 6811
type__enhancement enhancement
reporter__wsanchez wsanchez
priority__normal normal
milestone__ 
branch__ 
branch_author__ 
status__new new
resolution__None None
component__pydoctor pydoctor
keywords__ 
time__1383681829000000 1383681829000000
changetime__1383700782000000 1383700782000000
version__None None
owner__ 
cc__mwh
Dominant language
Python
Stars
6k
Forks
1.2k
Avg merge
2d 10h
Merged PRs (30d)
10

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from twisted/twisted

All issues in twisted/twisted

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.