Git Product home page Git Product logo

pydoctor's Introduction

Twisted

gitter_ rtd_ pypi_ ci_

For information on changes in this release, see the NEWS file.

What is this?

Twisted is an event-based framework for internet applications, supporting Python 3.6+. It includes modules for many different purposes, including the following:

  • twisted.web: HTTP clients and servers, HTML templating, and a WSGI server
  • twisted.conch: SSHv2 and Telnet clients and servers and terminal emulators
  • twisted.words: Clients and servers for IRC, XMPP, and other IM protocols
  • twisted.mail: IMAPv4, POP3, SMTP clients and servers
  • twisted.positioning: Tools for communicating with NMEA-compatible GPS receivers
  • twisted.names: DNS client and tools for making your own DNS servers
  • twisted.trial: A unit testing framework that integrates well with Twisted-based code.

Twisted supports all major system event loops -- select (all platforms), poll (most POSIX platforms), epoll (Linux), kqueue (FreeBSD, macOS), IOCP (Windows), and various GUI event loops (GTK+2/3, Qt, wxWidgets). Third-party reactors can plug into Twisted, and provide support for additional event loops.

Installing

To install the latest version of Twisted using pip:

$ pip install twisted

Additional instructions for installing this software are in the installation instructions.

Documentation and Support

Twisted's documentation is available from the Twisted Matrix website. This documentation contains how-tos, code examples, and an API reference.

Help is also available on the Twisted mailing list.

There is also an IRC channel, #twisted, on the Libera.Chat network. A web client is available at web.libera.chat.

Unit Tests

Twisted has a comprehensive test suite, which can be run by tox:

$ tox -l                       # to view all test environments
$ tox -e nocov                 # to run all the tests without coverage
$ tox -e withcov               # to run all the tests with coverage
$ tox -e alldeps-withcov-posix # install all dependencies, run tests with coverage on POSIX platform

You can test running the test suite under the different reactors with the TWISTED_REACTOR environment variable:

$ env TWISTED_REACTOR=epoll tox -e alldeps-withcov-posix

Some of these tests may fail if you:

  • don't have the dependencies required for a particular subsystem installed,
  • have a firewall blocking some ports (or things like Multicast, which Linux NAT has shown itself to do), or
  • run them as root.

Static Code Checkers

You can ensure that code complies to Twisted coding standards:

$ tox -e lint   # run pre-commit to check coding stanards
$ tox -e mypy   # run MyPy static type checker to check for type errors

Or, for speed, use pre-commit directly:

$ pipx run pre-commit run

All of the code in this distribution is Copyright (c) 2001-2024 Twisted Matrix Laboratories.

Twisted is made available under the MIT license. The included LICENSE file describes this in detail.

Warranty

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE USE OF THIS SOFTWARE IS WITH YOU.

IN NO EVENT WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY, BE LIABLE TO YOU FOR ANY DAMAGES, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Again, see the included LICENSE file for specific legal details.

pydoctor's People

Contributors

adiroiban avatar buhtz avatar cretz avatar dreid avatar exarkun avatar garetjax avatar garyvdm avatar glyph avatar graingert avatar hawkowl avatar hynek avatar iosonofabio avatar ivan-kalev avatar jelmer avatar khorn avatar lamby avatar markrwilliams avatar mikepurvis avatar moshez avatar mthuurne avatar mwhudson avatar not-my-profile avatar ntamas avatar rodrigc avatar tijuca avatar tomaarsen avatar tristanlatr avatar twm avatar wallrj avatar wsanchez avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

pydoctor's Issues

port to twisted.web.template

Noone cares about nevow any more, and now twisted has its own templating library, based on what was in nevow.

Unfortunately t.w.template doesn't support patterns, which pydoctor makes excessive usage of, so this is not trivial.


Imported from Launchpad using lp2gh.

pydoctor doesn't try to import the doc parser until after reading all the input modules

For example, if I tried to generate bzrlib API docs using this bzr.cfg:

projectname: bzrlib
packages: bzrlib
htmloutput: bzrlibapi
docformat: reStructuredText

... I wouldn't get an error message about not being able to import reStructuredText until after pydoctor had already looked at all the modules in bzrlib, which can take a bit. It's very frustrating to have it look like something is working only to fail for such an easy-to-check reason >10s in.

(Incidentally, what configuration do you use to generate the bzrlib API docs? I didn't find a .cfg file in either the bzr or pydoctor source trees.)


Imported from Launchpad using lp2gh.

line-spanning epytext markup generates an error

If some epytext markup with curlies spans multiple lines, pydoctor causes an epytext error to be emitted. However, using epydoc directly does not result in the same error, and epytext documentation suggests that spanning multiple lines is okay.


Imported from Launchpad using lp2gh.

pydoctor's handling of duplicate names needs a rethink

Originally reported as Twisted issue 2621:

There are several cases, some of which get quite tricky. This is not an exhaustive list, but some examples are:

def foo(): pass
def foo(): pass

class B: pass
class B(B): pass

if quux:
def foo(): pass
else:
def foo(): pass


Imported from Launchpad using lp2gh.

"from .module import foo" style imports not supported

Running "pydoctor foo" on the following structure gives "foo.quux:0 invalid ref to baz" and does not link "baz" in the generated HTML page for "foo.quux".

foo/init.py
1:# blank

foo/bar/init.py
1:from .other import baz

foo/bar/other.py
1:def baz():
2: pass

foo/quux.py
1:"L{baz}"
2:from .bar import baz


Imported from Launchpad using lp2gh.

pydoctor should be able to ignore 'test' directories

One common layout for python source trees is to put unit tests in a 'test' subdirectory of the code being tested. It would be nice to have a way to ignore these subdirectories when generating documentation.

epydoc has an --exclude option that can be used for this.


Imported from Launchpad using lp2gh.

zope.interface.Attribute docstrings should be treated as @ivar declarations, or something similar.

Right now if you define a zope.interface.Attribute, its docstring seems to be ignored. Since this is the preferred way to actually document zope.interface.Interfaces, it would be nice if the documentation showed up as if you had placed it in an @ivar in the interface class's docstring.


Imported from Launchpad using lp2gh.

how do you direct people's attention to the methods that count

Especially if the changes I recommended in https://bugs.launchpad.net/pydoctor/+bug/997295 are made, it should be a lot easier to see the public methods of private base classes, without having to be aware that the base class is there or private. It's a bit confusing to have to click into apparently private documentation to see important bits of functionality.

For example, on http://twistedmatrix.com/documents/current/api/twisted.python.filepath.FilePath.html, you can see lots of irrelevant methods (and you would see private methods, if there were any) on FilePath before seeing core functionality like walk() which happens to be defined on _PathHelper.

Maybe the thing to do here is just to emphasize the "implements interfaces" section a bit more and display the whole interface docstring on each method rather than just the somewhat ambiguous "from" link.


Imported from Launchpad using lp2gh.

@type fields render with trailing whitespace

@type fields in docstrings are rendered to HTML with trailing whitespace, which looks annoying in generated documentation when the value is placed in parentheses at the end of a paragraph. In the HTML source, it looks like this whitespace is a newline.


Imported from Launchpad using lp2gh.

implemented interfaces are not shown in subclasses

Looking at http://twistedmatrix.com/documents/current/api/twisted.protocols.amp.AMP.html I expect to see IBoxSender, IProtocol, IResponderLocator, and IBoxReceiver. Instead I have to click around in the hierarchy to see everything. It'd be great to have one list, especially since private utility superclasses and mixins often do the implements() themselves.


Imported from Launchpad using lp2gh.

links to stdlib modules

L{socket.AF_INET} could link to http://docs.python.org/library/socket.html#socket.AF_INET.

L{os.path.join} could link to http://docs.python.org/library/os.path.html#os.path.join

This link scheme isn't always accurate, but it's pretty consistent and it's accurate often enough to be highly useful. pydoctor could find the 'os' and 'socket' modules programmatically, it doesn't need to have a builtin list, and all the stdlib stuff goes together, so by using one stdlib module's file as reference, it could be quickly determined which things could be linked to in this way.


Imported from Launchpad using lp2gh.

references to builtins

There are lots of C{str} and C{int} littered all over @type and @param statements in Twisted. I'd really prefer these to be more properly expressed as L{str} and L{int}. Similarly, I'd like to express @raises statements with e.g. L{OSError}.

This doesn't need any fancy cross-reference stuff; I would like to be able to refer to arbitrary Python stdlib modules this way as well, but builtins and the standard exception hierarchy are important enough that I wouldn't mind if they all simply linked to a static 'python builtins' page included with the generated docs.


Imported from Launchpad using lp2gh.

document that properties are not supported

I've just spent the better part of a day figuring out why pydoctor refused to render my property in new twisted code while epydoc did so just fine, until I figured out that pydoctor doesn't know what properties are and prefers to document them like ivars (possibly read-only)

It'd be cool if the "how to use pydoctor" page mentioned this.


Imported from Launchpad using lp2gh.

pydoctor only seems to work on subversion checkouts

pydoctor discovers some portion of a path to use to use when computing source hrefs. It does this by looking for the base of a subversion working copy and assuming the path segments from the base up to the package directory are required as part of the links it generates.

I'd like to use pydoctor on an export or an unpacked release tarball. One way to do this is to make the package root explicit as an option.


Imported from Launchpad using lp2gh.

Add support for rendering @since

epytext has a @since field which indicates when an API was first introduced. It'd be great to have pydoctor render this information somehow (at least without saying "unhandled field").


Imported from Launchpad using lp2gh.

private stuff should be private-er

There is some visible indication that _-prefixed names are private when looking at the index, but when looking at the documentation for individual methods or functions, the text is on the same blue background.

Better would be a consistent style that always showed private stuff, in any context, as grey-on-grey so it's clear.

Also, the grey-on-grey doesn't ever have a textual explanation. There should be some text saying "This method is for maintainers only" and a link to a page that explains what it means to call a private method.

Finally, private methods should all be hidden by default, and shown via a "show private methods and bases" button (assuming the browser has JavaScript).


Imported from Launchpad using lp2gh.

interface multiple inheritance results in some missing documentation

The documentation generated for an interface which subclasses two other interfaces seems only to include documentation for methods inherited from one of the subclassed interfaces. For example, see http://twistedmatrix.com/documents/current/api/twisted.internet.interfaces.IReadWriteDescriptor.html which includes doWrite but not doRead.


Imported from Launchpad using lp2gh.

--add-package . --make-html

affects /products/pydoctor

pydoctor will crash when it is run on a top-level directory that
contains python source code. For example, running 'pydoctor
--add-package . --make-html' in a directory with python source code will
cause mediumName() in nevowhtml.pages to crash because it is trying to
sanitize "..name"

(shown to Michael IRL yesterday, just reporting here so it isn't lost)


Imported from Launchpad using lp2gh.

pydoctor should hide all private names by default

https://bugs.launchpad.net/pydoctor/+bug/209077 was a step forward, but it was not consistently applied.

For example, the "instance variables" section on http://twistedmatrix.com/documents/10.1.0/api/twisted.internet.endpoints.TCP4ClientEndpoint.html still doesn't render the private instance variables differently.

While displaying private names is useful to maintainers, the main public documentation really shouldn't show the private names at all, and should instead have a link that says "show all private names".


Imported from Launchpad using lp2gh.

doesn't support constants

integer and string contents are ignored at the moment, it'd be nice if they were documented. This would help with bug 410000 and with C inspection (though it's also possible to ignore explicitly constants of course).

Does this seem like a reasonable feature, and would implementing it this just be a matter of adding another subclass of pydoctor.model.Documentable?


Imported from Launchpad using lp2gh.

Use first paragraph instead of first line for method summary

There are cases where the summary doesn't fit in one line to be useful. An example would be

http://twistedmatrix.com/documents/11.0.0/api/twisted.application.service.ServiceMaker.html

The short summary in the green box for makeService().

I proposed a patch to mask the newline but exarkun refused it as he feels, it should be fixed inside of pydoctor so it works everywhere.

My idea would be to use the first paragraph instead of the first line for this summary and I'd also write a patch if others would support that idea.


Imported from Launchpad using lp2gh.

two classes with the same name confuse pydoctor

If two classes are defined in a file with the same name (e.g. one defined in an 'except' block, and the other in an 'else' block), pydoctor appends a number to the end of the generated name which links to nothing.

Generated docs:
http://twistedmatrix.com/documents/10.2.0/api/twisted.web.client.html

Source:
http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.2.0/twisted/web/client.py#L567


Imported from Launchpad using lp2gh.

pydoctor should have the equivalent of __docformat__ = "restructuredtext en"

Originally reported as Twisted issue 2187:

epydoc has a epytext variant that's valid restructured text. You can either set docformat = "restructuredtext en" in your module, or pass --docformat restructuredtext to epydoc to use it.

pydoctor should support these as well, so that it can be a better drop-in replacement for epydoc. For instance, bzr's source uses restructuredtext format epytext, so pydoctor isn't hugely useful with it.


Imported from Launchpad using lp2gh.

Analyze class assignments outside of their class scope

Pydoctor does not generate documentation for classes wrapped by SWIG (www.swig.org). SWIG creates classes like this:

class event(object):
    thisown = _swig_property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc='The membership flag')
    __repr__ = _swig_repr
    def __init__(self, _args, *_kwargs):
        _events.event_swiginit(self,_events.new_event(_args, *_kwargs))
    __swig_destroy__ = _events.delete_event
event.loop_once = new_instancemethod(_events.event_loop_once,None,event)
event.loop_wait = new_instancemethod(_events.event_loop_wait,None,event)
event_swigregister = _events.event_swigregister
event_swigregister(event)

pydoctor will in this case only document event.__init__(). It would be nice if it would also document event.loop_once and event.loop_wait.

Jelmer Vernooij - http://samba.org/~jelmer/
Jabber:


Imported from Launchpad using lp2gh.

pydoctor page should point people to Launchpad

http://codespeak.net/~mwh/pydoctor/ has no reference to launchpad, and says:

Where do I report bugs?
There is a pydoctor component in the trac instance on twistedmatrix.com. Assign to mwh.
This should be updated to point to launchpad, since any bugs in trac on twistedmatrix.com are being manually closed and redirected here.


Imported from Launchpad using lp2gh.

--introspect-c-modules loads foreign extension modules

If I build Twisted's extension modules using PyPy and then run pydoctor using CPython, passing the --introspect-c-modules flag, pydoctor fails with this exception:

Traceback (most recent call last):
File "/home/exarkun/Projects/pydoctor/trunk/bin/pydoctor", line 12, in
sys.exit(main(sys.argv[1:]))
File "/home/exarkun/Projects/pydoctor/trunk/pydoctor/driver.py", line 318, in main
system.addPackage(path, prependedpackage)
File "/home/exarkun/Projects/pydoctor/trunk/pydoctor/model.py", line 618, in addPackage
self.addPackage(fullname, package)
File "/home/exarkun/Projects/pydoctor/trunk/pydoctor/model.py", line 620, in addPackage
self.addModuleFromPath(package, fullname)
File "/home/exarkun/Projects/pydoctor/trunk/pydoctor/model.py", line 637, in addModuleFromPath
(suffix, mode, type))
ImportError: /home/exarkun/Projects/Twisted/trunk/twisted/runner/portmap.pypy-14.so: undefined symbol: _Py_InitPyPyModule

It seems the logic for deciding whether a .so should be loaded as an extension or not needs a little more smarts.


Imported from Launchpad using lp2gh.

port to the ast module

pydoctor should really use the now-standard ast module, not the old, crufy & deprecated compiler package.

No idea how much work this is.


Imported from Launchpad using lp2gh.

Support customization of all html templates

Originally reported as Twisted issue 3125:

Pydoctor has a directory full of templates it uses to generate html output. It would be nice if these templates could be customized somehow (other than directly editing them).


Imported from Launchpad using lp2gh.

epylint

I'd like a tool that I can run which will quickly validate as much epytext as possible. In the vein of pyflakes or pep8.py, it doesn't have to catch everything, as long as it can catch a few common things quickly. Thanks to those tools providing real-time feedback in the background of my editor, I pretty much never type NameErrors any more, and I rarely get spacing wrong, but I still make pydoctor syntax errors all the time.

Pretty much everybody's editor has a persistent python interpreter nowadays, so this could be a sidecar process that hangs out for a while and keeps some state around, if necessary, as long as it looks like it's just a command-line tool on the front end.


Imported from Launchpad using lp2gh.

some invalid epytext markup is not reported as such

If a function's docstring includes epytext markup documenting a parameter which the function does not have, pydoctor doesn't seem to consider this an error. It generates output which includes the documentation for the parameter without emitting a warning or error.

eg

exarkun@charm:$ mkdir foo
exarkun@charm:
$ touch foo/init.py
exarkun@charm:$ cat > foo/foo.py
def bar(baz):
"""
@param quux: foo
"""
exarkun@charm:
$ pydoctor --make-html --add-package foo/
adding directory /home/exarkun/foo
2/2 modules processed 0 warnings
WARNING: guessing foo for project name
writing html to apidocs using pydoctor.nevowhtml.writer.NevowWriter
starting ModuleIndexPage ... took 0.038186s
starting ClassIndexPage ... took 0.002309s
starting IndexPage ... took 0.007698s
starting NameIndexPage ... took 0.007809s
starting UndocumentedSummaryPage ... took 0.003291s
3/3 pages written
exarkun@charm:~$


Imported from Launchpad using lp2gh.

pydoctor throws AttributeError

pydoctor -c doc/pydoctor.cfg
/usr/lib/pymodules/python2.6/pydoctor/model.py:6: DeprecationWarning: the sets module is deprecated
import sets
adding directory otfbot
findImportStars
74 / 74 modules parsed
extractDocstrings
74 / 74 modules parsed 13 warnings
finalStateComputations
Traceback (most recent call last):
File "/usr/bin/pydoctor", line 5, in
main(sys.argv[1:])
File "/usr/lib/pymodules/python2.6/pydoctor/driver.py", line 247, in main
f()
File "/usr/lib/pymodules/python2.6/pydoctor/astbuilder.py", line 352, in finalStateComputations
self._finalStateComputations()
File "/usr/lib/pymodules/python2.6/pydoctor/twisted.py", line 165, in _finalStateComputations
super(TwistedASTBuilder, self)._finalStateComputations()
File "/usr/lib/pymodules/python2.6/pydoctor/astbuilder.py", line 235, in _finalStateComputations
self.recordBasesAndSubclasses()
File "/usr/lib/pymodules/python2.6/pydoctor/astbuilder.py", line 243, in recordBasesAndSubclasses
o.subclasses.append(cls)
AttributeError: 'Module' object has no attribute 'subclasses'


Imported from Launchpad using lp2gh.

pydoctor assumes all docs are in the same directory

Originally reported as Twisted issue 1886.

This has two bad effects:

it's hard for packagers to package pydoctor's output for the different bits of twisted because if (say) twisted web's docs are in /usr/share/doc/twisted-web/ they should link to twisted core's docs in /usr/share/doc/twisted-core/ and this isn't currently possible.

Similarly, the pydoctor output for nevow should link to the pydoctor output for twisted, if it knows where it is.

I think this can be addressed by loading a bunch of systems that know the base url of their documentation, and having the documentation generator look in more than just the system being generated when trying to link to something.

Having written all this out, I don't think it should be too hard...


Imported from Launchpad using lp2gh.

introspection for C modules

affects pydoctor

It would be really nice if pydoctor could support introspection next to
parsing of Python code. I work with a lot of projects that have Python
code that is partially in C and partially in Python itself, and this is

the only thing blocking us from adopting pydoctor atm.

Jelmer Vernooij - http://samba.org/~jelmer/
Jabber:


Imported from Launchpad using lp2gh.

pydoctor should put the module name at the beginning of the document title

Originally reported as Twisted issue 3343:

I've been working on Twisted-based code recently, and I've been consulting the online API references quite a bit. Right now, I have 18 tabs open, all next to each other, all displaying 'API docs for "twisted...', which makes it somewhat difficult to find the particular section of the documentation I'm looking for.

It would be convenient if pydoctor's HTML output mode formatted titles more like:

twisted.python.log API docs

...or even better, re-format the information in the

on every page:

t.p.log Module docs


Imported from Launchpad using lp2gh.

__all__ no longer works

Something about http://bazaar.launchpad.net/~mwhudson/pydoctor/dev/revision/569 or http://bazaar.launchpad.net/~mwhudson/pydoctor/dev/revision/570 completely broke all aliasing for me. Rolling back fixes it. Do a basic

pydoctor --add-package .../twisted --make-html

and have a look at, e.g., twisted.internet.ssl.

This is what it should look like, for reference:

http://twistedmatrix.com/documents/10.2.0/api/twisted.internet.ssl.html


Imported from Launchpad using lp2gh.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.