diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/conf.py b/conf.py new file mode 100644 index 0000000..f38a4cd --- /dev/null +++ b/conf.py @@ -0,0 +1,52 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Twisted' +copyright = '2022, TDB' +author = 'TDB' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'furo' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/content/pages/APIDocs.rst b/content/pages/APIDocs.rst new file mode 100644 index 0000000..653c5d3 --- /dev/null +++ b/content/pages/APIDocs.rst @@ -0,0 +1,27 @@ +Twisted API Documentation +######################### + + +This page describes how to generate the API docs for the Twisted web site. + +You will need the latest Twisted release unpacked and the latest version of pydoctor + +Steps +===== + +1. Modify template.tpl to include the Google Analytics JavaScript (which can be found in the source of any trac page). +2. Run an interactive Python session that goes something like this: + +.. code-block:: python + + >>> from twisted.python._release import APIBuilder + >>> from twisted.python.filepath import FilePath + >>> APIBuilder().build('Twisted', 'http://twistedmatrix.com/trac', + 'http://twistedmatrix.com/trac/browser/tags/releases/twisted-8.2.0', + FilePath('Twisted-8.2.0/twisted'), FilePath('apidocs')) + +Be sure to use the tag which corresponds to the version of Twisted the docs are being generated for. Note that if your working is the Twisted source directory you checked out, then ''that'' version of `APIBuilder` will be used! + +3. Upload the resulting ``apidocs`` directory to www-data@cube. Use ``tar cx apidocs | ssh www-data@twistedmatrix.com tar xv`` or something. +4. Put the apidocs directory into the appropriate location beneath vhosts/twistedmatrix.com/documents/ (eg 8.2.0/api) +5. If desired, update the ``current`` symlink. diff --git a/content/pages/ArchivedNews.rst b/content/pages/ArchivedNews.rst new file mode 100644 index 0000000..b718671 --- /dev/null +++ b/content/pages/ArchivedNews.rst @@ -0,0 +1,92 @@ +Twistery In the News +#################### + + +Twisted Announces Membership in the Software Freedom Conservancy (2008-03-16) +============================================================================= + +At PyCon 2008 we were delighted to share some good news with the Python community: the announcement of the `Twisted Software Foundation `_. Glyph had previously emailed the Twisted mail list, letting those close to the project know of this major event shortly after the paperwork was signed. Before we brought this before a more public audience, we wanted to give companies a chance to become "founding sponsors" -- and this is what has happened at PyCon. We're looking forward to issuing a formal press release about this (including info on the founding sponsors) and will have more details in the near future. + +We would like to send a special thank-you out to those sponsors who made contributions immediately. In order of contribution, they are: + +* Chris Armstrong +* Michel Pelletier +* AdytumSolutions, Inc. +* tummy.com +* Drew Perttula +* Glenn Tarbox +* Ilya Novoselov + +Read the initial announcement `here `_. If the video for the announcement made at PyCon gets published somewhere, we will post an update. + +The Twisted Show: Episode 2 (2008-02-26) +======================================== + +Yesterday, Duncan had the chance to talk with Jack Moffitt and Christopher Zorn of `Chesspark `_ about their company, their vision, and how Twisted played an integral role in their application and helped them to meet their goals. + +The interview is on `the site `_ and the feed is available `there `_. + +We're still experimenting with podcasting and feed enclosures, so please be patient with us! If you have any issues, the media files are available at `archive.org `_. + + +Twisted Matrix Laboratories Blog (2007-12-02) +============================================= + +TM Labs has a `new blog `_ ! We will be posting various items of interest that relate to development of Twisted, useful community information, and enthralling news events. Add us to your reader! + +Episode 1 of the "Twisted Show" (2007-01-22) +============================================ + +`The Twisted Show `_ is a new experiment we are trying at TM Labs in an effort to let people and business who are solving unique and/or interesting problems with Twisted share their solutions with a wide audience. + +This first installment is an interview with a few folks at `Renkoo `_ who are using Twisted to innovate meetings as part of the social media landscape. + +Twisted 2.5.0 (2007-01-11) +========================== + +Major Twisted release! Read the `release announcement `_ and click +on things on the `Downloads `_ page. + +New Twisted Site Goes Live! (2006-12-04) +======================================== + +Thanks to the efforts of the Twisted Team and the visual design and CSS skills of `Huw Wilkins `_, we have rolled out our latest version of the Twisted Matrix Labs web site. + +Enjoy! + +Apple Releases iCal Server Code (2006-08-07) +============================================ + +Apple's iCal Server is written in Twisted. Visit the `development site `_ to read more about the software and to get started with it now. + +Twisted 2.4.0 (2006-05-25) +========================== + +Including updates to Words, Web, Names, Mail, Conch, and more. See `TwistedProject `_. + +Twisted Sprint in Sydney (2006-05-19) +====================================== + +Twisted's Australian hackers are converging in Sydney on the June 3-4 weekend. If you are Australian and think you might be made of internet, find out more about the SydneySprint + +Twisted 2.2.0 (2006-02-12) +========================== + +Twisted 2.2.0 is out. See `TwistedProject `_. + +Twisted (core) 2.1.0 + First Virtual Sprint (2005-10-09) +======================================================== + +In Twisted's first virtual sprint the weekend of 2005-10-08, many people contributed to Twisted in general and helped get the Twisted 2.1.0 release out. See the Twisted project page and read about what's new. + +Australian Twisted Sprint 2005.2 (2005-08-07) +============================================= + +A Twisted Sprint will be held in Sydney Australia on the 19-21 August 2005. Topics will probably include documentation, a VFS layer (including WebDAV support), the new Axiom database, and whatever else anyone can think of. For more information, please see the Australian Twisted Sprint Wiki. + +Thanks to Linux Australia for funding this sprint. + +Twisted 2.0.1 NOW released (2005-05-25) +======================================= + +Twisted 2.0.1 is now out. This is a minor release, only including bugfixes since 2.0.0. One of the most important fixes was a bug causing many gtk GUI apps to crash. Twisted News is now properly included in the Sumo release. Enjoy. diff --git a/content/pages/BasicGuideToContributingCode.rst b/content/pages/BasicGuideToContributingCode.rst new file mode 100644 index 0000000..87fc40c --- /dev/null +++ b/content/pages/BasicGuideToContributingCode.rst @@ -0,0 +1,5 @@ +Basic Guide To Contributing Code +################################ + + +Please see `Contributing to Twisted Labs! `_ diff --git a/content/pages/BranchPolicy.rst b/content/pages/BranchPolicy.rst new file mode 100644 index 0000000..c1e0969 --- /dev/null +++ b/content/pages/BranchPolicy.rst @@ -0,0 +1,5 @@ +Branch Policy +############# + + +Please see `Ultimate Quality Development System! `_ diff --git a/content/pages/BugKeywords.rst b/content/pages/BugKeywords.rst new file mode 100644 index 0000000..1285d9a --- /dev/null +++ b/content/pages/BugKeywords.rst @@ -0,0 +1,10 @@ +Bug Keywords +############ + + +* **documentation** - bug is against the Twisted documentation +* **easy** - bug should be easy to fix and is a good ticket to start with if you want to get started contributing to Twisted +* **review** - bug is waiting for review +* **tests** - bugs against the Twisted unit test suite +* **upstream** - bug was submitted upstream and is waiting for them to resolve it +* **windows** - bug is against one of the Windows operating systems diff --git a/content/pages/CancellableDeferredUseCases.rst b/content/pages/CancellableDeferredUseCases.rst new file mode 100644 index 0000000..a69a4b8 --- /dev/null +++ b/content/pages/CancellableDeferredUseCases.rst @@ -0,0 +1,6 @@ +Cancellable Deferred Use Cases +############################## + + + +* ``twisted.web._newclient.Request.writeTo`` returns a ``Deferred`` which fires when the request has been completely written to the transport. If the connection is lost and a request is in the process of writing itself out, it should be told to stop. This could be done by canceling the ``Deferred`` returned by ``writeTo``. It is currently done by having a separate method on ``Request`` (requiring extra state tracking). diff --git a/content/pages/CodeReview.rst b/content/pages/CodeReview.rst new file mode 100644 index 0000000..6598579 --- /dev/null +++ b/content/pages/CodeReview.rst @@ -0,0 +1,19 @@ +Code Review +########### + + +Divmod uses code review for just about every change to any project. The exceptions to this are generally extremely new code which isn't seeing any use yet where the consequences of breaking things are minimal and don't outweigh the cost of developer time required by the review. + +Code review is a pretty simple process: at its heart, it is little more than reading some code written by someone else. Nevertheless, it can be useful to have a set of things on which to focus during a review: + +* Does the branch merge or the diff apply cleanly? +* Are there unit tests for the code being changed or added? +* Do the unit tests pass for you? +* Do the unit tests pass for buildbot? +* Is there documentation for new code? +* Where appropriate, has existing documentation been updated (including ChangeLog/NEWS files)? +* Does the code adhere to the coding style? + +There's the easy list. Most are mechanical checks. Don't feel bad about rejecting a branch if the answer to any of these questions is no: the problems may seem minor in isolation, but each contributes to overall poor code quality. Moreover, sometimes apparently minor problems can be hiding larger issues. + +Taking a look at the bigger picture can be a little bit harder, but it's just as important. diff --git a/content/pages/CommitterCheckList.rst b/content/pages/CommitterCheckList.rst new file mode 100644 index 0000000..dbeccc9 --- /dev/null +++ b/content/pages/CommitterCheckList.rst @@ -0,0 +1,46 @@ +Committer Checklist +################### + + + +These are things that developers with commit access to the Twisted source repository should know. The first list is of policy items (i.e., things you should or should not try to do). + +#. All development is done in branches. +#. All code committed to trunk must go through the `Review Process `_ . +#. trunk commit messages must follow the format described on `Review Process `_ so that various pieces of automation can work. +#. If you check in something that breaks `trunk `_ , revert it +#. Everything you check in to Git is licensed under `Twisted's license `_ +#. Be in the IRC channel, at least when you're going to be committing to trunk (don't feel bad about avoiding the distraction when you're trying to get stuff done though). +#. Have fun, but not too much. + +This second list includes various technical details about how you might go about doing Twisted development (and has overlap for organizational purposes): + +#. All development is done in branches + + #. Branch names must follow the naming convention so that various pieces of automation can work. + +#. trunk commit messages must follow the format described on `Review Process `_ so that various pieces of automation can work. + + #. If you check in something that breaks `trunk `_ , revert it + + #. If the bad revision was 07c854353d, + + #. ``cd ~/Projects/Twisted`` + #. ``git revert -m 1 07c854353d .`` + + #. Use "Reopens ticket:NNNN" in the commit message to re-open the corresponding ticket + #. Explain what broke and how and perhaps on which platform in the commit message + + #. If you need to re-merge the reverted branch, revert the reversion. + + #. Create a new branch or merge trunk into your branch with was previously reverted. + #. Revert again the commit containing the revert and commit the reversion: `git revert REVERT-SHA`. + #. Make your changes. + #. Push the changes for re-review + +#. If you are merging a branch into trunk, you must commit exactly the merge. You may not make extra changes in the trunk working copy after the merge. It's easiest to do this if you merge changes via the Github pull request UI. + +Other documents that overlap and supplement this information include: + +* `Working from Twisted's Code repository `_ +* `Review Process `_ diff --git a/content/pages/CommunityCode.rst b/content/pages/CommunityCode.rst new file mode 100644 index 0000000..e05d76e --- /dev/null +++ b/content/pages/CommunityCode.rst @@ -0,0 +1,42 @@ +Twisted Community Code +###################### + + +This wiki page is the home for information about projects to which we are collectively referring by the "super project" name "Twisted Community Code" (abbreviated "tx"). + +Motivation +========== + +This effort was a culmination of `this discussion `_ that occurred on the Twisted mail list (and expressed in condensed form `here `_). In summary, by creating a place where anyone can contribute whatever they want, we address the long-lamented barrier to entry for Twisted community members: + +#. what are often perceived as impossibly high standards, and +#. limitations on what projects are included in Twisted. + +The Twisted projects (Twisted Core, Twisted Web, Twisted Mail, etc.) are maintained with exacting standards, contributions to which are rigorously reviewed and held under the highest scrutiny for code quality. This places a heavy responsibility on the developer, one that may not be desired or enjoyed by all. Additionally, there are would-be contributors whose projects, though based on Twisted, were not accepted for inclusion in Twisted proper for various reasons. + +This seems to have been a good idea, as we've made a good start with three newly associated projects, even before announcing this initiative :-) + +Suggestions, Not Mandates +========================= + +We are making no proclamations about standards, adherences, etc.: community members are free to follow their own development practices, etc. We would like to encourage people to use the "tx" prefix for their projects, in the same way that "py" is used for general Python projects. For example, we would like the authors of "Twisted SNMP" and "Twisted Storage" to instead use something like "txSNMP" and "txStorage." We want the "Twisted" name to be reserved for projects that are part of Twisted proper. + +Leadership +========== + +In so much as an autonomous collective has leadership, Phil Christensen has kindly agreed to act as the point of contact for this community effort. He will maintain the community presence on Launchpad, send out announcements as necessary, and respond to inquiries, while at the same time receiving the full support of `the Labs' members `_. + +Launchpad +========= + +We are encouraging community members to use `Launchpad `_ to manage their Twisted code projects, or at the very least, mirror them. Doing so allows the project managers to assign the "tx" super project to their own, thus including them in the community of projects that use or depend on Twisted. + +The Launchpad super project site is here: + https://launchpad.net/tx + +To associate your Launchpad project with this super project, click the "Change details" link on your project overview page and type "tx" in the super project field. Your project should then show up in the list on the tx front page. + +Useful Info +=========== + +* `Bazaar with Subversion `_ diff --git a/content/pages/CompatibilityPolicy.rst b/content/pages/CompatibilityPolicy.rst new file mode 100644 index 0000000..f6f49f8 --- /dev/null +++ b/content/pages/CompatibilityPolicy.rst @@ -0,0 +1,5 @@ +Compatibility Policy +#################### + + +content moved here https://twistedmatrix.com/documents/current/core/development/policy/compatibility-policy.html diff --git a/content/pages/ContributingToTwistedLabs.rst b/content/pages/ContributingToTwistedLabs.rst new file mode 100644 index 0000000..3dcd18f --- /dev/null +++ b/content/pages/ContributingToTwistedLabs.rst @@ -0,0 +1,78 @@ +Contributing To Twisted +####################### + + +.. contents:: + +There are many ways individuals and organizations can make contributions to Twisted. + +Many open source projects are perpetually crunched for volunteer labor. Twisted is no different in this respect — we could always use more help from the community. However, we are lucky to have something that most projects don't: the ability to convert dollars directly into maintenance that benefits the project. + +When you contribute money to the Twisted project, you are directly contributing to get bugs fixed, features implemented, and tickets reviewed. +Donations are `tax-deductible `_ and can be made via `Google Checkout or Paypal `_ or directly to the `Twisted Software Foundation `_. + +Code Contributions +================== + +Overview +-------- + +* `Submitting a Patch `_, a simplified overview +* `Detailed Contribution Requirements `_, with that and more +* `Review Process `_, how contributed code is quality checked and reviewed +* `Checklist for Twisted committers `_, things that developers with commit access should know + + +Prepare +------- +* Get a GitHub account and then come back and `Login using GitHub `_ on this site + +* Intimately familiarize yourself with `The Ultimate Quality Development System `_ + +* Understand the `Developer docs `_ (how-tos, core docs, examples, API reference) + +* Twisted has a rigorous policy standards for code, documentation, and testing: + + * `Coding standard `_ + + * `Writing Style guide `_ + + * `Testing standard `_ + + * `Git Access `_ + +* Understand the `Review Process `_ code review process + +* Multiple CI services are used to automate the build process across platforms and test for breakage. Watch their feedback on each pull request page. + +Explore and Contribute +---------------------- + +* Examine some of the `sources `_ + +* Take a look at the `open tickets `_ open tickets + +* Learn the `bug keywords `_ + + * `'Easy' keyword tickets `_ are low-hanging fruit and good to get your feet wet + +* `Submit a Patch `_ + +* Learn how to apply for commit privileges with the `Contributor Advancement Path `_ + +Other Ways to Contribute +======================== + +* `Review and add documentation `_ +* `Code Reviews `_ +* Submit bug reports (you must first be `registered `_) +* Provide technical support (answer questions on `IRC and the mail lists `_) +* Sign up for a `project job `_. Help us maintain our build CI, speed center, Trac instance, and more. + +Wiki Portals +============ + +* `Infrastructure `_ +* `ContinuousIntegration `_ +* `users `_ +* `DocumentationAnalysis `_ diff --git a/content/pages/ContributorAdvancementPath.rst b/content/pages/ContributorAdvancementPath.rst new file mode 100644 index 0000000..f6e3dec --- /dev/null +++ b/content/pages/ContributorAdvancementPath.rst @@ -0,0 +1,47 @@ +How to Apply for Commit Privileges +################################## + + +To request commit privileges, please submit an application to commit@twistedmatrix.com (you must be logged in to trac in order to view this email address). The application should contain a list of 10 tickets, at least 5 of which are patches you've submitted, and at least 5 of which are code reviews you've done which have been accepted by a committer. At least 2 of your authored patches should have gone all of the way through the review process to be landed. Once you've sent in your application, a group of core contributors will review it and decide whether to grant you commit privileges. + +The following is an example application using some of glyph's commit history: + +.. code-block:: + + Hi Twisted committers, + + I would like to apply for commit privileges. My trac username is glyph. + + Code Reviews Performed + ---------------------- + 7176 - Use twisted.python.runtime in twisted.internet.serialport + 7485 - Porting t.w._newclient and t.w.t.test_newclient to Python 3 + 7624 - @inlineCallbacks ignores return values in Python3.3 and greater + 7684 - twisted.internet.endpoints._parseSSL defaults to SSLv23_METHOD, should default to None + 7702 - Remove twisted.application.internet.UDPClient. + + Patches Submitted + ----------------- + 4900 - twisted.web server sends responses without explicit Content-Type; potential XSS + 5572 - twisted.internet.tcp.Connector.getDestination has invalid epytext in it + 6751 - twisted.web._newclient.Response leaves its transport in an unpredictable state depending on how large the response body is + 7836 - LoopingCall.withCount countCallable called with 0 + 7878 - twisted.internet.process raises an exception when encoding tracebacks that occur post-fork/pre-exec and include non-ASCII characters + + Patches Accepted + ---------------- + 4900 - twisted.web server sends responses without explicit Content-Type; potential XSS + 5572 - twisted.internet.tcp.Connector.getDestination has invalid epytext in it + + Thanks! + +Directions for the Review Committee +=================================== + +The committee will use the following process when deciding to grant commit privileges: + +#. Once at least 1 committee member sponsors the application, other committers have 7 days to object to the application. + +#. If no objections are received within the 7 day period, any member of the committee may grant the applicant commit privileges. + +#. If the committee decides to grant privileges to the applicant, a committee member will make an announcement on the mailing list welcoming the new committer. If the application is denied, then the applicant will be notified privately and given an explanation. diff --git a/content/pages/DanielHenninger.rst b/content/pages/DanielHenninger.rst new file mode 100644 index 0000000..9342304 --- /dev/null +++ b/content/pages/DanielHenninger.rst @@ -0,0 +1,15 @@ +Daniel Henninger +################ + + +You probably know me more as Jadestorm than as Daniel Henninger. Either way, outside of work, I have a lot of active Jabber related projects that I am involved in. The "biggest" of them are: + +* PyAIMt (Python Jabber Transport for AIM) + +* PyICQt (Python Jabber Transport for ICQ) + +* JWGC (Jabber WindowGram Client) + +* Jabber Script Repository + +I am also the maintainer of the oscar functionality in Words, though I have not yet passed any code back to the project. (I have been working on it within PyICQt/PyAIMt, and will prep things to be returned to Twisted Words at some point in the hopefully near future) diff --git a/content/pages/Documentation/Documentation.rst b/content/pages/Documentation/Documentation.rst new file mode 100644 index 0000000..f340667 --- /dev/null +++ b/content/pages/Documentation/Documentation.rst @@ -0,0 +1,52 @@ +Documentation +############# + +:save_as: index.html + +.. _Start here: http://twistedmatrix.com/documents/current/core/howto/index.html +.. |Start here| replace:: **Start here** + +|Start here|_ , the developer guides for Twisted's core networking libraries. See also our many `examples `__ and the current `API reference `_. + +`Web Servers and Clients howtos `__ and `examples `__ . Want to use Twisted for **web development**? Please read `this page first! `_ + + +* Read our `FAQ `_. + +* Documentation for other Twisted components: + + * SSH Servers and Clients - `howtos `__ and `examples `__. + + * Email protocols: SMTP, IMAP, POP3 - `STMP client tutorial `_ and `examples `__. + + * DNS - `howtos `__ and `examples `__. + + * Instant messaging and IRC - `howtos `__ and `examples `__. + +* Twisted Core `man pages `_. + +* The complete developer guide in `PDF format `_. + + +Third Party Documentation +========================= + +Dave Peticolas has written a number of `excellent tutorials `_ on Twisted. They don't assume a lot of existing knowledge about networking or concurrency mechanisms, and as such are well-suited for new users. + +Developer Docs +============== + +* Want to contribute? We have a page dedicated to `documentation for contributors `_. +* Here are some notes about `Twisted Development `_. + +Mail Lists +========== + +* Search the `twisted `_ or `twisted-web `_ mail list archives. + +Books +===== + +* `Twisted Network Programming Essentials `_ by Abe Fettig & Jessica McKellar, published by O'Reilly. +* `Foundations of Python Network Programming `_ also covers the use of Twisted to some extent. +* `Game Programming With Python `_ covers Twisted in the chapters on programming networked games. diff --git a/content/pages/Downloads.rst b/content/pages/Downloads.rst new file mode 100644 index 0000000..9f31e07 --- /dev/null +++ b/content/pages/Downloads.rst @@ -0,0 +1,17 @@ +Downloads +######### + + +For more information about Twisted, please see the `Twisted Project `_ page. + +You can get the latest release from `PyPI Twisted `_ project page. + +You can get older releases from `PyPI archives `_ or `Twisted download site `_. + + +The recommended way is to run ``pip install Twisted``, preferably inside a virtualenv. + +If you are installing on macOS, ``pip install Twisted[macos_platform]`` will install the macOS-specific requirements. + +If you are installing on Windows, ``pip install Twisted[windows_platform]`` will install the Windows-specific requirements. + diff --git a/content/pages/FrequentlyAskedQuestions.rst b/content/pages/FrequentlyAskedQuestions.rst new file mode 100644 index 0000000..16160d7 --- /dev/null +++ b/content/pages/FrequentlyAskedQuestions.rst @@ -0,0 +1,351 @@ +Twisted FAQ +########### + + +This is a list of Frequently Asked Questions regarding Twisted. + +.. contents:: + + +General +======= + +What is Twisted? +---------------- + +See the `Twisted Project `_ + +Why should I use Twisted? +------------------------- + +See the `Twisted Advantage `_ + +I have a problem getting Twisted. +--------------------------------- + +Did you check the `Documentation HOWTO collection? `_ There are so many documents there that they might overwhelm you... try starting from the index, reading through the overviews and seeing if there seems to be a chapter which explains what you need to. You can try reading the PostScript or PDF formatted books, inside the distribution. And, remember, the source will be with you... always. + +How big is Twisted? +------------------- + +As of Twisted 15.4, the source release archive of Twisted is about 3MB. Installed normally, uncompressed, Twisted is a bit larger - about 12MB. + +Which parts of Twisted are stable? +---------------------------------- + +In general, everything which is part of a Twisted release is stable. See `CompatibilityPolicy `_ for details. + +Why doesn't Twisted follow PEP 8? +--------------------------------- + +Twisted does follow much of PEP 8 (as is documented in the `Twisted coding standard `_. However, Twisted prefers camelCase for variables, functions, and methods (whereas PEP 8 recommends underscores) because Twisted predates PEP 8 and converting the entire codebase now is infeasible. Twisted continues to use its existing naming convention for new APIs to retain consistency within the project (according to PEP 8's recommendation). + +Installation +============ + +Why am I getting ImportErrors for Twisted subpackages on my 64bit installation of RedHat/Fedora/CentOS? +-------------------------------------------------------------------------------------------------------- + +Red Hat and derived Linux distributions arrange to have certain Python libraries installed in ``/usr/lib/`` and other parts installed in ``/usr/lib64/`` This is problematic for Twisted, since it results in some of Twisted being installed in one directory and the rest installed in another. Python will load a package from only one directory. You can override this default behavior when you install Twisted by supplying the ``--install-lib`` parameter when running Twisted's ``setup.py``. + +Can I install Twisted using easy_install or pip? +------------------------------------------------ + +Yes, Twisted can be installed both using pip and easy_install, although pip is recommended. + +Core Twisted +============ + +Why does Twisted depend on Zope? +-------------------------------- + +Twisted only depends on `Zope Interface `_, an interface package which is also packaged and distributed independently from the main Zope distribution. Twisted uses Zope Interface to define and document APIs. Packages are available for all major operating systems. + +How can I access self.factory from my Protocol's __init__? +------------------------------------------------------------ + +You can't. A ``Protocol`` doesn't have a ``Factory`` when it is created. Instead, you should probably be doing that in your Protocol's ``connectionMade`` method. + +Similarly you shouldn't be doing real work, like connecting to databases, in a Factory's ``__init__`` either. Instead, do that in ``startFactory`` + +See `Writing Servers `_ and `Writing Clients `_ for more details. + +Where can I find out how to write Twisted servers? +-------------------------------------------------- + +Try `Writing Servers `_. + +How do I make Twisted talk to multiple clients / connect to multiple servers? +----------------------------------------------------------------------------- + +Twisted already does this. If you want to connect to multiple servers, call ``connectTCP`` (or similar) multiple times, and each call will result in a single outgoing connection. ``listenTCP`` will result in your factory (and therefore your protocol) being invoked for each incoming connection. + +Sometimes people ask this question when they write a function that calls ``connectTCP``, then ``reactor.run()``. You don't usually need to call ``reactor.run()`` yourself; let `twistd `_ (not "Twisted") do it. If you do need to call it yourself, call it *just once* after your initial setup. When ``reactor.run()`` exits, your program should too. + +How do I make input on one connection result in output on another? +------------------------------------------------------------------ + +This seems like it's a Twisted question, but actually it's a Python question. Each ``Protocol`` object represents one connection; you can call its ``transport.write`` to write some data to it. These are regular Python objects; you can put them into lists, dictionaries, or whatever other data structure is appropriate to your application. + +As a simple example, add a list to your factory, and in your protocol's ``connectionMade`` and ``connectionLost``, add it to and remove it from that list. Here's the Python code: + +.. code-block:: python + + from twisted.internet.protocol import Protocol, Factory + from twisted.internet import reactor + + class MultiEcho(Protocol): + def __init__(self, factory): + self.factory = factory + + def connectionMade(self): + self.factory.echoers.append(self) + + def dataReceived(self, data): + for echoer in self.factory.echoers: + echoer.transport.write(data) + + def connectionLost(self, reason): + self.factory.echoers.remove(self) + + + class MultiEchoFactory(Factory): + def __init__(self): + self.echoers = [] + + def buildProtocol(self, addr): + return MultiEcho(self) + + reactor.listenTCP(4321, MultiEchoFactory()) + reactor.run() + +Why is ``protocol.dataReceived`` called with only part of the data I called ``transport.write`` with? +----------------------------------------------------------------------------------------------------- + +TCP is a stream-oriented transport. This means that when you call ``transport.write``, the data may be broken up into arbitrarily-sized chunks for transmission over the network. There is no way for Twisted to determine how large the data originally written to the transport was. + +If you want to send a message and receive it whole on the other end of a connection, you must decide on a format for the message and parse it. For example, prefixing the message with a length or terminating it with a message boundary. Luckily, Twisted provides many different utilities for this purpose, which can automatically divide the data stream into messages for you: + +* `LineReceiver `_ +* `NetstringReceiver `_ +* `Int16StringReceiver `_ + +These are implemented as classes you inherit from rather than ``Protocol``, and implement methods other than ``dataReceived`` (such as ``stringReceived`` or ``lineReceived``). You may also want to consider a higher-level messaging protocol, to exchange messages with more structure than a simple collection of bytes. For example, the `Asynchronous Messaging Protocol `_, or `Perspective Broker `_. + +Why isn't my ``connectionLost`` method called? +---------------------------------------------- + +``connectionLost`` is called when the platform notifies Twisted that the TCP connection has been closed. TCP connections are closed in one of two ways. They can either be closed "actively" - by one side of the connection sending a close message to the other side - or they can be closed by timeout - one side deciding that the other side has taken too long to respond and interpreting this to mean that the other side is no longer paying attention to the connection. However, for the timeout case, it is important to understand that if an application is not sending data over the connection, **there is no response** to *take too long* so no timeout will ever occur. This means that if a network error disrupts a connection but the application is not sending data over it, it's possible for ``connectionLost`` to never be called. However, if the application is sending data over it, then the timeout will eventually expire. TCP uses very large timeouts in order to account for very poor networks. If you rely on TCP timeouts, expect as much as two hours (the precise amount is platform specific) to pass between when the disruption occurs and when ``connectionLost`` is called. If this is too long, you may want to use an application-level *keep alive* mechanism to discover lost connections earlier. This just involves sending simple messages back and forth over a connection. If it ever takes longer than whatever amount of time you decide is appropriate for your application to receive a response to one of these messages, consider the connection lost. + +Also, keep in mind that ``transport.loseConnection()`` may not result in the connection closing immediately, e.g. if you have writes buffered. To close the connection immediately, discarding any buffered writes, call ``transport.abortConnection()``. + +When I try to install my reactor, I get errors about a reactor already being installed. What gives? +--------------------------------------------------------------------------------------------------- + +Here's the rule - installing a reactor should always be the **first** thing you do, and I do mean first. Importing other stuff before you install the reactor can break your code. + +`Tkinter `_ and `wxPython `_ support, as they do not install a new reactor, can be done at any point, IIRC. + +``twistd`` won't load my ``tap`` file! What's this Ephemeral nonsense? +---------------------------------------------------------------------- + +When the pickled application state cannot be loaded for some reason, it is common to get a rather opaque error like so: + +.. code-block:: console + + % twistd -f test2.tap + + Failed to load application: global name 'initRun' is not defined + + +The rest of the error will try to explain how to solve this problem, but a short comment first: this error is indeed terse -- but there is probably more data available elsewhere -- namely, the ``twistd.log`` file. Open it up to see the full exception. + +The error might also look like this: + +.. code-block:: console + + Failed to load application: is not safe for unpickling + +To load a ``.tap`` file, as with any unpickling operation, all the classes used by all the objects inside it must be accessible at the time of the reload. This may require the ``PYTHONPATH`` variable to have the same directories as were available when the application was first pickled. + +A common problem occurs in single-file programs which define a few classes, then create instances of those classes for use in a server of some sort. If the class is used directly, the name of the class will be recorded in the ``.tap`` file as something like ``__main__.MyProtocol``. When the application is reloaded, it will look for the class definition in ``__main__`` which probably won't have it. The unpickling routines need to know the module name, and therefore the source file, from which the class definition can be loaded. + +The way to fix this is to import the class from the same source file that defines it: if your source file is called ``myprogram.py`` and defines a class called ``MyProtocol`` you will need to do a ``from myprogram import MyProtocol`` before (and in the same namespace as) the code that references the ``MyProtocol`` class. This makes it important to write the module cleanly: doing an ``import myprogram`` should only define classes, and should not cause any other subroutines to get run. All the code that builds the Application and saves it out to a .tap file must be inside an ``if __name__ == '__main__'`` clause to make sure it is not run twice (or more). + +When you import the class from the module using an external name, that name will be recorded in the pickled ``.tap`` file. When the ``.tap`` is reloaded by ``twistd`` it will look for ``myprogram.py`` to provide the definition of ``MyProtocol``. + +Here is a short example of this technique: + +.. code-block:: console + + # file dummy.py + from twisted.internet import protocol + class Dummy(protocol.Protocol): pass + if __name__ == '__main__': + from twisted.application import service, internet + a = service.Application("dummy") + import dummy + f = protocol.Factory() + f.protocol = dummy.Dummy # Note! Not "Dummy" + internet.TCPServer(2000, f).setServiceParent(a) + a.save() + +I get Interrupted system call errors when I use os.popen2. How do I read results from a sub-process in Twisted? +--------------------------------------------------------------------------------------------------------------- + +You should be using ``reactor.spawnProcess`` (see `interfaces.IReactorProcess.spawnProcess `_ There's also a convenience function, `getProcessOutput `_, in `twisted.internet.utils `_. + +Why don't my spawnProcess programs see my environment variables? +---------------------------------------------------------------- + +`spawnProcess `_ defaults to clearing the environment of child processes as a security feature. You can either provide a dictionary with exactly the name-value pairs you want the child to use, or you can simply pass in ``os.environ`` to inherit the complete environment. + +My exceptions and tracebacks aren't getting printed! Or My Deferred or DeferredList seems like it never fires, so my program just mysteriously hangs! What's wrong? +-------------------------------------------------------------------------------------------------------------------------------------------------------------------- + +It really depends on what your program is doing, but the most common cause is this: it is firing -- but it's an error, not a success, and you have forgotten to add an `errback `_ , so it looks like nothing happens. Always add errbacks! + +The reason ``Deferred`` can't automatically show your errors is because a ``Deferred`` can still have callbacks and errbacks added to it even after a result is available -- so we have no reasonable place to put a logging call that wouldn't result in spurious tracebacks that are handled later on. When a deferred is garbage collected with a Failure, a traceback is automatically printed. However, if you keep a reference to your Deferred and it is never garbage collected, it's possible no traceback will be printed. But in that case, you also have a memory leak. + +For even more verbose debugging information to be printed in Failure tracebacks, set ``defer.setDebugging(True)``. + +Why does it take a long time for data I send with ``transport.write`` to arrive at the other side of the connection? +-------------------------------------------------------------------------------------------------------------------- + +Twisted TCP, UDP, and SSL transports don't buffer data before sending it. When you write data to a connection, it should show up on the other side as quickly as the network is capable of transporting it there. However, a couple things may prevent this from happening: + +* Twisted can only send data after you give up control of execution to the reactor. For example, if you have an infinite loop writing data to a transport, the data will never actually be sent since control will never leave your code and return to the reactor. +* Twisted APIs are largely not threadsafe. If you call ``transport.write`` from a thread other than the reactor thread, the behavior is undefined. This may manifest as very long delivery times, or deliveries that don't succeed until another unrelated event occurs in the system. To use Twisted APIs from a non-reactor thread, see the documentation for ``reactor.callFromThread``. + +If your program appears to send messages as expected, it might be possible that the sending program is working as expected but the receiving program is buffering the messages. Eg: your messages are buffered by a web browser, and you don't close your message. Use telnet instead. Especially as a beginner, never forget that you can only see messages indirectly through the eyes of another program. Check your receiving program! + +How do I use Deferreds to make my blocking code non-blocking? +------------------------------------------------------------- + +You don't. Deferreds don't magically turn a blocking function call into a non-blocking one. A Deferred is just a simple object that represents a deferred result, with methods to allow convenient adding of callbacks. (This is a common misunderstanding; suggestions on how to make this clearer in the `Deferred Execution `_ howto are welcome!) + +If you have blocking code that you want to use non-blockingly in Twisted, either rewrite it to be non-blocking, or run it in a thread. There is a convenience function, `deferToThread `_, to help you with the threaded approach -- but be sure to read `Using Threads in Twisted `_. + +I get ``exceptions.ValueError: signal only works in main thread`` when I try to run my Twisted program! What's wrong? +--------------------------------------------------------------------------------------------------------------------- + +The default reactor, by default, will install signal handlers to catch events like Ctrl-C, ``SIGTERM`` and so on. However, you can't install signal handlers from non-main threads in Python, which means that ``reactor.run()`` will cause an error. Pass the ``installSignalHandlers=0`` keyword argument to ``reactor.run`` to work around this. + +I'm trying to stop my program with sys.exit(), but Twisted seems to catch it! How do I exit my program? +------------------------------------------------------------------------------------------------------- + +Use ``reactor.stop()`` instead. This will cleanly shutdown the reactor. + +How do I find out the IP address of the other end of my connection? +------------------------------------------------------------------- + +The ``.transport`` object (which implements the `ITransport `_ interface) offers a pair of methods named `getPeer `_ and `getHost `_. ``getPeer`` will give you a tuple that describes the address of the system at the other end of the connection. For example: + +.. code-block:: python + + class MyProtocol(protocol.Protocol): + def connectionMade(self): + print "connection from", self.transport.getPeer() + +Why don't Twisted's network methods support Unicode objects as well as strings? +------------------------------------------------------------------------------- + +In general, such methods (e.g. `FileDescriptor `_ 's write) are designed to send bytes over the network. These methods use non-Unicode string objects as a container for the bytes that they send and receive. + +Unicode objects are not byte-based and are an abstraction used for representing strings of human readable text. In order to send Unicode strings using these methods, you should explicitly specify a byte-based encoding for them, for example: ``s.encode("utf-8")`` and explicitly decode them at the receiving end. + +Twisted cannot choose an encoding for you at this level: your encoding choice will be protocol specific and may need to be specified in the message you send (for example, HTTP headers include a encoding specification). + +For a more complete discussion of the distinction between Unicode strings and specific encodings of Unicode strings, see the following articles: + +* Glyph's `Implicit encoding is bad example `_ +* Dan Sugalski's `What the heck is: A string; `_ +* Joel Spolsky's `The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!) `_. + +Why do I get a *Permission denied* error trying to write `.../site-packages/twisted/plugins/dropin.cache.new` when I use ``twistd`` or ``trial`` or some other Twisted program? +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + +Twisted's plugin system uses certain cache files to improve performance. These cache files are automatically updated as necessary. However, when a Twisted installation is used by processes without write permission to it (as is commonly the case for a site-wide installation), if this cache file is not up to date, attempts to rewrite it will result in this error. The solution is for the administrator (whoever performed the site install) to generate the cache. See the `Plugin Caching `_ section of the plugin documentation for details on how to regenerate this cache. + +Why can't the Twisted's reactor be restarted? +--------------------------------------------- + +There is no interesting reason. This is mainly a limitation of the current implementation, and a lack of interest on this particular feature. It's just a matter of someone spending the time on it. + +What's the best way of integrating Twisted with pygame? +------------------------------------------------------- + +Take a look at `game `_ to see an example of the world's best practice for integrating pygame and Twisted. + +Perspective Broker +================== + +How can I get the reference to a client from a Perspective? +----------------------------------------------------------- + +Firstly, the client must send a reference when it connects to the perspective broker. This can be done by passing the reference as a parameter to `pb.connect `_. + +At the server end, you must override the `Perspective.attach `_, which is called when a client attaches to a perspective. The first argument of this method is a remote reference to the client object that was passed to `pb.connect `_. + +Note that a single perspective can have many attached clients. For further information, see `Managing Clients of Perspectives `_ HOWTO and the `twisted.spread.pb `_ API docs. + +Requests and Contributing +========================= + +Twisted is cool, but I need to add more functionality. +------------------------------------------------------ + +Great! Read `our docs `_, and if you're feeling generous, contribute patches. + +I have a patch. How do I maximize the chances the Twisted developers will include it? +------------------------------------------------------------------------------------- + +There are several steps you can take to increase the chances of inclusion into Twisted: + +#. Be sure you have read and are familiar with the information and linked material `here `__ and `here `_. +#. `Open a ticket `_ for the feature you wish to add. +#. Get feedback from others on your ideas and thoughts. +#. Write ``trial`` tests for your code! +#. When providing a patch, use unified ``diff`` Either use ``svn diff`` or, better yet, make a clean checkout and use ``diff -urN`` between them. Make sure your patch applies cleanly. +#. If you post the patch to the mailing list, make sure it is inlined and without any word wrapping. + +And to whom do I send it? +------------------------- + +`Open a ticket `_ , and if it's an urgent or important issue you may want to tell the `mailing list `_ about the issue you added. + +My company would love to use Twisted, but it's missing feature X, can you implement it? +--------------------------------------------------------------------------------------- + +You have 3 options: + +#. Pay one of the Twisted developers to implement the feature. +#. Implement the feature yourself. +#. Add a feature request to our bug tracker. We will try to implement the feature, but there are no guarantees when and if this will happen. + +Documentation +============= + +Twisted really needs documentation for X, Y or Z - how come it's not documented?. +--------------------------------------------------------------------------------- + +Twisted's documentation is a work in progress, and one that we would appreciate assistance with. If you notice a gap or flaw in the documentation, please file a bug in the `Twisted Issue tracker `_ and mark it as having topic 'documentation'. Patches appreciated. Unit tests even more so. + +Communicating with us +===================== + +There's a bug in Twisted. Where do I report it? +----------------------------------------------- + +Unless it is a show-stopper bug, we usually won't roll out a new release with a fix it if it's already fixed in `Git `_, so check if it is fixed there. If it is not fixed in Git, you should add it to the `issue tracker `_, including pertinent information about the bug (hopefully as much information needed to reproduce it: OS, Git versions of any important files, Python version, code you wrote or things you did to trigger the bug, etc. If the bug appears to be severe, you should also raise it on the `mailing list `_, with a pointer to the issue already filed in the bug tracker. + +Where do I go for help? +----------------------- + +Ask for help `where the Twisted team hangs out `_. + +How do I e-mail a Twisted developer? +------------------------------------ + +First, note that in many cases this is the wrong thing to do: if you have a question about a part of Twisted, it's usually better to e-mail the mailing list. However, the preferred e-mail addresses for all Twisted developers are listed in the CREDITS file in the Subversion repository. diff --git a/content/pages/JonathanLange.rst b/content/pages/JonathanLange.rst new file mode 100644 index 0000000..c1ed547 --- /dev/null +++ b/content/pages/JonathanLange.rst @@ -0,0 +1,5 @@ +Jonathan Lange +############## + + +Maintainer of Trial. diff --git a/content/pages/ProjectsUsingTwisted.rst b/content/pages/ProjectsUsingTwisted.rst new file mode 100644 index 0000000..5a9b1a6 --- /dev/null +++ b/content/pages/ProjectsUsingTwisted.rst @@ -0,0 +1,147 @@ +Projects Using Twisted +###################### + + +Twisted is used by many open-source, academic and commercial projects. + +**Got a successful project you'd like added to this page?** Mail a brief description and an URL (if appropriate) to success at twistedmatrix dot com! + +Community Code Project +====================== + +`Twisted Community Code `_ - This is a `super project `_ hosting or mirroring many Twisted add-ons, Twisted-based libraries, etc., that are not part of the Twisted Project proper, but depend upon it. + +Libraries and Add-Ons +===================== + + * `Ampoule `_ - Ampoule is a process pool implementation written on top of Twisted Matrix. Its name comes from the use of AMP as the default communication protocol between the pool and all its children. + * `BEEPy `_ - BEEP protocol implementation for Python. + * `Corotwine `_ - Coroutine-based APIs for Twisted. Corotwine lets you use Twisted with a blocking API. + * `foolscap `_ - A Python library that implements object-capability style secure remote objects. + * `Ldaptor `_ - LDAP protocol implementation and utilities. + * `M.U.T.A.N.T `_ - A library for doing test-driven GTK user-interfaces for Twisted programs. + * `Paisley `_ - Paisley is a CouchDB client written in Python to be used within a Twisted application. + * `PyAMF `_ - Python support for the `AMF Format `_, used for RPC communication with Adobe's Flash Player + * `PyOSD `_ - module for displaying text on your X display, much like the "On Screen Displays" used on TVs and some monitors. + * `pyrad `_ - A RADIUS client/server implementation with a Twisted wrapper. + * `python-tvi955 `_ - Python-TVI955 is a partial implementation of the TVI955 terminal. It includes a parser for the computer to terminal ("server to client") protocol and an in-memory terminal emulator. + * `Qt4 Reactor `_ - Integration of Twisted and Qt4 + * `sAsync `_ - SQLAlchemy done Asynchronously. + * `RTMPy `_ - Implementation of the `RTMP Protocol `_, used for audio/video/data streaming to Adobe's Flash Player + * `Scrapy `_ - a screen scraping and web crawling framework, used to crawl websites and extract structured data from their pages. + * `Synchronous Deferred `_ - Synchronous Deferred is for authors of libraries who want to support both synchronous and asynchronous APIs. + * `TLS Lite `_ - Python TLS/SSL implementation. + * `Torc `_ - An implementation of Orc, a language for orchestrating distributed services, for the Twisted networking framework. + * `treq `_ - Python requests like API built on top of Twisted's HTTP client. + * `TwistedCronService `_ - Provides an interface for describing recurring events to be run according to a cron-like schedule. + * `TwistedSNMP `_ - PySNMP integration for Twisted. + * `twisted-x11 `_ - Experimental low-level implementation of the X11 protocol on top of twisted. This is pure python, it does not wrap libxcb or libX11. This means it does not integrate with existing libraries. It uses the xml protocol definitions from xcb, so it is pretty complete. + * `Twotp `_ - Twotp is an implementation of the Erlang node protocol written in Python using the Twisted networking engine. It makes possible to run an Erlang node in Python, like the Jinterface library of Erlang allows to do in Java. You can then call methods on an Erlang node or receive method calls. + * `txmemcache `_ - Multi-Client and Hashing utilities on top of twisted.protocols.memcache. + * `txAMQP `_ - Python library for communicating with AMQP peers and brokers using Twisted (RabbitMQ, Qpid, OpenAMQ). It also includes support for using Thrift RPC over AMQP in Twisted applications. + * `txAWS `_ - Twisted-based Asynchronous Libraries for Amazon Web Services and Eucalyptus private clouds. + * `txCobalt `_ - An async, Twisted-based Python library for Bluetooth communications. + * `txcomputegrid `_ - Twisted based compute grid. + * `txCumulus `_ - The goal of txCumulus is to provide an abstraction layer on top of other Twisted-based (Python) async cloud APIs such as txAWS and txRackspace (and possibly txComputeGrid). + * `txdnspython `_ - txdnspython is a way to use dnspython to create and manipulate DNS messages and then send those messages over the network using Twisted's asynchronous networking. + * `txEvolver `_ - txEvolver is a Twisted-based set of libraries for performing calculations of genetic algorithms as well as genetic programs in an asynchronous, distributed manner. + * `txFigleafTrial `_ - Allows you to use figleaf to generate code coverage reports with twisted.trial. + * `txFluidDB `_ - Bindings for the `FluidDB `_ HTTP interface. + * `txGenshi `_ - This project provides a small Twisted/Nevow package for running Genshi templates in the Twisted web framework, Nevow. + * `txGraylog `_ - txGraylog is a Twisted-based client for Graylog servers. It supports multiple interfaces to send log messages to the server including: TCP and UDP (using either plain text or the Gelf protocol) + * `txJSON-RPC `_ - This is the project page for creating Python JSON-RPC servers and clients using the Twisted Networking Engine. + * `txM `_ - Twisted for microcontrollers. txM aims to provide the Twisted asynchronous network programming idiom for solid-state devices without operating systems via the Python-on-a-chip Python VM. + * `txMailServer `_ - This project provides a starter mail server written using Twisted. + * `txNetTools `_ - Ping, traceroute, icmp, etc., implemented in Twisted, and a library for those who want to build their own network tools. + * `txNetFlow `_ - !NetFlow and IPFIX protocol, client, and server support in Twisted. + * `txProtoBuf `_ - Protocol buffers (http://code.google.com/p/protobuf/) RPC implemented using Twisted. + * `txRackspace `_ - An async, Twisted Python API for Rackspace Cloud. + * `txRDQ `_ - Provides a !ResizableDispatchQueue class that gives you a queue to dispatch jobs and a pool of in-progress tasks. This is a combination of a Twisted defer.DeferredQueue and a task.Cooperator. + * `txRedis `_ - A Redis client library for Twisted Python. + * `txRemoteDeploy `_ - Remote deployment for Twisted applications. + * `txSimpleDB `_ - Twisted support for Amazon's SimpleDB with the ability to develop/test against a local SimpleDB instance. + * `txSmug `_ - A Twisted wrapper for !SmugMug's API. + * `txSpore `_ - An asynchronous Spore Python API using Twisted. + * `txsshserver `_ - Extends Twisted's SSH server with some useful features for hosting Bazaar branches. Much of this code could & should be rolled back into Twisted. The project provides a playground for experimenting with new extensions, a holding area for the extensions we've already written, and a home for the things that don't really belong in Twisted. + * `txStomp `_ - txStomp is a Twisted implementation of the open protocol Stomp and allows for Twisted applications to be integrated in environments (e.g., ones that use ActiveMQ) that depend on this technology. + * `txULS `_ - Twisted Python experiments and prototyping for ultra large-scale systems. + * `txXCP `_ - This project is focused on developing an open source, Twisted-based version of Jabber XCP. + * `Wokkel `_ - Wokkel is collection of enhancements on top of the Twisted networking framework, written in Python. It mostly provides a testing ground for enhancements to the Jabber/XMPP protocol implementation as found in Twisted Words, that are meant to eventually move there. + +Applications +============ + * `apt-proxy2 `_ - caching proxy for Debian apt-get clients. + * `BuildBot `_ - a distributed building/testing framework. + * `CIA Bot `_ - notification system, used by many projects for source code checkin notification. + * `Crow's Nest `_ - collect log information from various sources and to apply some filter to them in a very modular way. + * `CVSToys `_ - CVS change notification via email, IRC and HTTP. + * `Quotient `_ - multi-protocol messaging server with tools for information management and retrieval, including a mail server (SMTP/POP3/IMAP/webmail) and much more. + * `DocmaServer `_ - batch processing server that does Word <-> XML conversion. + * `dohop.com `_ - a flight planning web site which searches many other flight databases. + * `Downpour `_ - a web-based !BitTorrent client. + * `Freevo `_ - open-source home theatre and PVR PC platform. + * `Flumotion `_ - a streaming media server. + * `Gridspy `_ - live power monitoring and analysis + * `hellanzb `_ - an application designed for \*nix environments that retrieves and processes Usenet nzb files. + * `Hep `_ - Message routing super-server. + * `Howie the Chatterbot `_ - a conversational AI. + * `Informant `_ - GNOME Panel applet for event notification. + * `Itaka `_ - an on-demand screen capture server + * `Jasmin `_ - Open source SMS gateway + * `Khashmir `_ - distributed hash table. + * `Landscape Client `_ - the Ubuntu system management agent that communicates with the Canonical Landscape management service. + * `Launchpad `_ - Cross-project collaboration for the Open Source world + * `Lunch `_ - Simple process launcher for complex distributed setup + * `MaxJax `_ - a solution for real-time web based control of any open sound control enabled sound synthesis engine. + * `msn-gateway `_ - an msn messenger gateway for mobile phones using email and web access. + * `NXLucene `_ - a standalone multi-threaded Lucene-based text indexing server. + * `Palaver `_ - multi-user chat for Jabber. + * `PETMail `_ - permission based anti-spam replacement for SMTP. + * `Pgkbot `_ - a bot for monitoring mediawiki changes. + * `Poetry `_ - Poetry is a collection of simple command line tools for working with XMPP services. It aims to provide a set of tools similar to tools like dig, curl, and man, but for interacting, configuring, and querying XMPP services. + * `Purity `_ - Python library for Pure Data dynamic patching to create audio patches. + * `pymon `_ - pymon is an open source network and process monitoring solution implemented in Twisted. Both the user interface and the software configuration are designed to be easily and rapidly deployed, saving on time and overhead often associated with other monitoring solutions. + * `Pynfo `_ - extendable multi-function IRC bot. + * `PySMS `_ - This is a Short Message Server written in python. It provides the possibility to take Messages inserted into a Database and send them over a supported protocols (currently only UCP/EMI) to a SMS Provider. + * `PythonDirector `_ - load balancing for web servers. + * `pyvncviewer `_ - a simple VNC viewer implemented in Python. + * `RdbHost `_ - !RdbHost uses Twisted for a streaming web-server. The streaming server allows users to stream large SQL 'dump' files to and from the database host using a web browser. + * `Scenic `_ - Telepresence software for wide bandwidth networks and oriented toward live performances + * `SFTPGateway `_ - SFTP to FTP gateway, allowing secure access to FTP servers. + * `Shtoom `_ - a RTP/SIP VoIP phone. + * `Solipsis `_ - a pure peer-to-peer system for a massively shared virtual world. + * `svs `_ - a framework for supporting collaborative projects that combine coding with other media. + * `Tahoe-LAFS `_ - a secure, decentralized, fault-tolerant filesystem. + * `Toonloop `_ - Software suite for performing with live frame by frame animation creation + * `TouRSSt `_ - RSS delivery system. + * `Turtl `_ - HTTP proxy whose purpose is to throttle connections to specific hostnames to avoid breaking terms of usage of those API providers (like del.icio.us, technorati and so on). + * `txLoadBalancer `_ - This is a fork of Anthony Baxter's !PythonDirector. It removes all threading and asyncore code, replacing the admin UI and the remaining threading loops with the Twisted-based analogs. It also aims to provide a developer API for those who wish to provide load-balancing services from within their Twisted applications. + * `txOpenID `_ - A Twisted OpenID server. txOpenID is an implementation of the OpenID Identity Provider specification, written using Twisted Web and Divmod's Nevow. + * `Upstage `_ - a "cyberperformance" chat system. + * `Various Libraries `_ - pcap, SNMP integration, RSS to NNTP gateway, and other programs. + * WinDictator - Dictate in the MS Windows OS, have the text typed in Linux via X faked keystroke events. + * `Zenoss `_ - open source network/systems monitoring and management + +Games +===== + * `OGC `_ - MUD client. + * `Go Siege `_ - multiplayer Go game. + * `Beyond 2 `_ - high level framework for assembling, animating, and interacting with 3D virtual environments. + * `txSpace `_ - a pseudo-MUD engine. + * `GalaxyMage `_ - a cross-platform, open-source tactical RPG with online multiplayer play. + * `OpenRTS `_ - an open source real-time strategy game with multiplayer and scenario games. + * `PyScrabble `_ - an online, multiplayer Scrabble game. + * `Poker3d `_ - a 3d poker game server and client. + * `Buyasta `_ - a MUD engine. + * `London Law `_ - an online multiplayer adaptation of the classic Scotland Yard board game. + * `Castle Combat `_ - a multiplayer game designed after the arcade game "Rampart" + +Research Projects +================= + + * `LabRAD `_ is an RPC system designed for use in scientific research labs, presently in use by `more than a dozen academic and industrial labs `_ around the world. + * `Tycoon @ HP Labs `_ is a market-based system for managing compute resources in distributed clusters. + * `pyGridWare @ Lawrence Berkeley National Labs `_ is a Python implementation of the WS-Resource framework. It includes support for WS-Addressing, WS-Notification, WS-Lifetime management, and WS-Security. + * `VIFF @ University of Aarhus, Denmark `_ is an open source Python library for implementing secure multi-party computation. + * Dharma @ UPenn: Distributed Home Agent for Robust Mobile Access. + * PySense @ MIT is an open source python library devoted to first person sensing for robots and wearables. diff --git a/content/pages/PythonAdvantage.rst b/content/pages/PythonAdvantage.rst new file mode 100644 index 0000000..b28a255 --- /dev/null +++ b/content/pages/PythonAdvantage.rst @@ -0,0 +1,13 @@ +The Python Advantage +#################### + + +According to `the web site for it `_ , which has a pretty good chance of being correct... + + Python is an interpreted, interactive, object-oriented programming language. It incorporates modules, exceptions, dynamic typing, very high level dynamic data types, and classes. Python combines remarkable power with very clear syntax. It has interfaces to many system calls and libraries, as well as to various window systems, and is extensible in C or C++. It is also usable as an extension language for applications that need a programmable interface. Finally, Python is portable: it runs on many brands of UNIX, on the Mac, and on PCs under MS-DOS, Windows, Windows NT, and OS/2. + +The advantages of using Python are too many and varied to cover them all here, and if you don't already know about it, I highly encourage you to go to the site and read about them. + +However, the chief advantage of using Python for Twisted's development is that it has enabled us to keep the code incredibly small. Python's high-level features let us express very concisely the intent of almost all of the Twisted codebase. Less code means less bugs, which means a more stable server infrastructure for you. + +All of the developers we recommend for Twisted consulting are extremely well-versed in Python. diff --git a/content/pages/ReviewProcess.rst b/content/pages/ReviewProcess.rst new file mode 100644 index 0000000..3ad5861 --- /dev/null +++ b/content/pages/ReviewProcess.rst @@ -0,0 +1,276 @@ +Twisted Code Review Process +########################### + + +`Contribute `_ > `Development `_ > Review Process + +.. contents:: + +All commits to Twisted's trunk must follow this review process. The only exception is for the `Twisted Quotes `_ file. There are no other exceptions! + +Both authors and reviewers should be intimately familiar with all requirements on this page. + +Authors: Before you get started +=============================== + +For the most part, we'd love for you to jump right in and start writing code! The code review process should catch any serious problems with your contribution, and the continuous integration system should catch most tricky cross-platform issues. It's easy to get too caught up in trying to do everything perfectly the first time and never get any code written, so you should usually err on the side of just trying something out rather than waiting for someone to tell you if it's OK. That being said, there are a few things that you should really be aware of before you write your first line of code: + +.. _ReleaseProcess: http://twisted.readthedocs.org/en/latest/core/development/policy/release-process.html +.. |ReleaseProcess| replace:: **a current pre-release** + +* Make sure you have a *clear idea of what work needs doing*. Write down your idea first; `file a ticket `_ before you write a patch. A really good ticket will give a precise description of what needs to change and why it needs changing; it avoids giving precise details of exactly *how* the code needs to change, because the patch should supply those details. A really *bad* ticket will say "here is a patch I wrote, apply it". If you're just getting started with contributing to Twisted, it would be good to find an existing ticket rather than come up with something yourself, so you have an idea how to go through the process before you start making difficult changes. You'll need to have a good description of your work for other parts of the process as well (the NEWS file, the commit message) which is another reason thinking about what you're trying to do helps. + + * Note: **if you're filing a bug because you noticed a regression in** |ReleaseProcess|_ **, make sure to mark it as a regression, add it to the release milestone, and to post something to the mailing list as well**. It's very important for us to spot regressions before they make it into a final release, so redundant communication is better in this case! + +* Try **not** to *write too much code at once* A good change really needs to be be under 1000 lines of diff for a reviewer to be able to deal with it before getting fatigued and missing things. Really, you should be aiming for things in the neighborhood of 200 lines. This is for your benefit as well as the reviewer's; we don't want you to spend weeks on a 10,000-line monster of a feature, only to have it rejected because we're not interested in having such a feature at all. + +Authors: Things your branch or patch must contain +================================================= + +* Code which follows the `coding standard `_ +* 100% unit test coverage for all modified and new code (even if it didn't have tests before) +* 100% API docstring coverage for all modified and new code (even if it didn't have docs before) +* No `CompatibilityPolicy `_ backwards-incompatible changes. Please also be sparing when adding 'public' names to the API, as they must be supported in the future. If it can start with an underscore and not be exposed publicly, it probably should. +* Appropriate new or modified "End User" guide documentation (in the form of rst files in the `docs/ `_ directory) +* A file in all relevant "newsfragments" directories describing changes which affect users (See `below <#news-files>`__) + +Authors: How to get your change reviewed +======================================== + +.. _Security: /content/pages/Security.html + +* There must be a bug in the Twisted bug tracker describing the desired outcome (See `below <#filing-bugs-and-writing-review-requests>`__). + + * **Note** For security issues, see Security_ +* Add the "review" keyword to the ticket. +* Remove the owner field by selecting the blank option next to "Assign to". + + * Alternatively, assign it to someone who has already agreed to review it. +* Write a comment with any relevant information for the reviewer. +* If you are a Twisted committer: + + * Make sure your code is in a branch. + * Make sure the 'branch' field on the ticket corresponds to the branch where the code is checked in. + * `Force a build of your branch `_. Make sure that it's **green**! + +Reviewers: How to review a change +================================= + +* Be familiar with the Twisted codebase, coding standard, and these review requirements. +* Don't be the author of the change (See `below <#who-can-review>`__). +* Make sure that it's **green**! `Trigger a build if it was not done yet `_. + + * There is one caveat to this rule. If one of the tools that we use to verify the code, such as ``pydoctor``, ``twistedchecker`` or ``pyflakes``, causes a build to fail, but for a reason that has to do with a bug in the tool rather than a problem with the code, file the bug in the tool, and then link from the bug report to the twisted ticket where you saw the spurious failure. You can `file bugs in twistedchecker here `_ , `pydoctor here `_ , or `pyflakes here `_. Don't block a branch on a tool bug, but also, don't let any spurious failures go without filing an appropriate bug on the relevant tool first. + * If the contributor lacks permission to create branches in the official Twisted repository on github (``twisted/twisted``), you will need to push it to the official Twisted repository -- after a security review -- to cause all of the CI builders to process the branch. After verifying the change is not an attack on the CI system, use ``admin/pr_as_branch`` to push the changes into the official Twisted repository. The remaining builds will be started and the results will eventually appear on the original PR. If new commits are pushed to the branch, repeat the process. + * Note any unreliable tests on the `build reliability placeholder ticket `_. +* Assign the ticket to yourself. +* Review the change, and write a detailed comment about all potential improvements to the branch (See `below <#how-to-be-a-good-reviewer>`__). +* Remove the "review" keyword from the ticket. +* Assign the ticket back to the author. +* If the change is ready for trunk, indicate so by writing "please merge" or "+1". + + * Alternatively, if the author does not have commit access to trunk, merge the change for them or add the "Cleared to land" label. + + +Authors: How to merge the change to trunk +========================================= + +* Check in the GitHub PR that all tests are green (or the failed one are just unrelated/spurious failures) +* Use the GitHub merge button to merge the request, using the GitHub default commit subject, and with the standard commit format required by Twisted. See below for details. +* Alternatively, you can use the command line and merge the change into a checkout of Twisted trunk (as a merge commit, using ``git merge --no-ff``!) and commit it. + +The commit message, when using both the GitHub button or the CLI commit, must follow this format (See `below <#the-commit-message>`__). + +.. raw:: html + + 
+  Merge pull request #123 from twisted/4356-branch-name-with-trac-id
+
+  Author: <comma_separated_github_usernames>
+  Reviewer: <comma_separated_github_usernames>
+  Fixes: ticket:<ticket number>
+
+  Long description (as long as you wish)
+
+ +.. _ReleaseProcess2: http://twisted.readthedocs.org/en/latest/core/development/policy/release-process.html +.. |ReleaseProcess2| replace:: **pre-release in progress** + +* After the change is merged wait for the `buildbots for trunks `_ to finish running. +* If there is a regression on a supported builder you should `revert your merge <#reverting-a-change>`_. +* **If this fix has implications for an ongoing** |ReleaseProcess2|_, please announce it on the mailing list so that the release manager will know. A change definitely has implications for the release process if: + * a pre-release has been issued for which there is no final release + * this ticket was a known regression and is now closed, so another pre-release should be issued + * this ticket was in the release milestone and is now closed, so another pre-release should be issued + * as part of the final review, the reviewer noticed that this is fixing something that could be considered a regression. + +In general, if there's any doubt, communicate to the mailing list. The mailing list is fairly low traffic, and so a little extra noise about interesting developments is much better than letting an important fix slip through the cracks. If you're not sure whether something qualifies as a regression or not, let the release manager know so they can decide. +* If no regression appears, you can delete the source branch. + +Details +======= + +News files +---------- + +**NB: If your pull request contains news fragments in** ``topfiles`` **directories, please run** ``admin/fix-for-towncrier.py`` **and then commit the result.** + +It is up to the authors of individual changes to write high-level descriptions for their changes. These descriptions will be aggregated into the release notes distributed with Twisted releases. If we just let each author add to the `NEWS `_ file on every commit, though, we would run into lots of spurious conflicts. To avoid this, we use `towncrier `_ to manage separate news fragments for each change. + +Changes must be accompanied by a file whose content describes that change in at least one ``newsfragments`` directory. There are ``newsfragments`` directories for each subproject (*e.g.* `src/twisted/web/newsfragments, `_ `src/twisted/names/newsfragments `_, `src/twisted/words/newsfragments `_), and one root directory (`src/twisted/newsfragments `_) for core Twisted changes. If a change affects multiple areas of Twisted, then each affected area can have a newsfragments entry to detail the relevant changes. An entry must be a file named ``.`` (eg. ``1234.bugfix``). You should replace ```` with the ticket number which is being resolved by the change (if multiple tickets are resolved, multiple files with the same contents should be added). The ```` extension is replaced by one of the following literal strings: + +============ ===== +Type Scope +============ ===== +**feature** Tickets which are adding a new feature +**bugfix** Tickets which are fixing a bug +**doc** Tickets primarily about fixing or improving documentation (any variety) +**removal** Tickets which are deprecating something or removing something which was already deprecated +**misc** Tickets which are very minor and not worth summarizing outside of the git changelog. These should be empty (their contents will be ignored) +============ ===== + +To get a sense of how the text in these files is presented to users, take a look at `the real overall news file `_ . The goal when writing the content for one of these files is to produce text that will fit well into the overall news files. + +Here are a few which should help you write good news fragments: + +* The entry SHOULD contain a high-level description of the change suitable for end users. +* When the changes touch Python code, the grammatical subject of the sentence SHOULD be a Python class/method/function/interface/variable/etc, and the verb SHOULD be something that the object does. The verb MAY be prefixed with "now". +* For bugfix, it MAY contain a reference to the version in which the bug was introduced. + +Here are some examples. Check out the root `NEWS` file for more inspiration.: + +Features: + +.. code-block:: console + + twisted.protocols.amp now raises InvalidSignature when bad arguments are passed to Command.makeArguments + +.. code-block:: console + + The new module twisted.internet.endpoints provides an interface for specifying address families separately from socket types. + +Bugfix: + +.. code-block:: console + + twisted.internet.ssl.Certificate(...).getPublicKey().keyHash() now produces a stable value regardless of OpenSSL version. Unfortunately this means that it is different than the value produced by older Twisted versions. + +.. code-block:: console + + twisted.names.secondary.SecondaryAuthority can now answer queries again (broken since 13.2.0). + +.. code-block:: console + + The SSL server string endpoint parser (twisted.internet.endpoints.serverFromString) now constructs endpoints which, by default, disable the insecure SSLv3 protocol. + +Deprecations: + +.. code-block:: console + + twisted.trial.util.findObject is now deprecated. + +.. code-block:: console + + twisted.conch.insults.colors is now deprecated in favor of twisted.conch.insults.helper. + +.. code-block:: console + + twisted.runner.procmon.ProcessMonitor's active, consistency, and consistencyDelay attributes are now deprecated. + +Removals: + +.. code-block:: console + + twisted.internet.interfaces.IReactorTime.cancelCallLater, deprecated since Twisted 2.5, has been removed. + +.. code-block:: console + + Support for versions of pyOpenSSL older than 0.10 has been removed. + +Documentation: + +.. code-block:: console + + The documentation for twisted.internet.defer.DeferredSemaphore now describes the actual usage for `limit` and `tokens` instance attributes. + +.. code-block:: console + + The docstring for twisted.conch.ssh.userauth.SSHUserAuthClient is now clearer on how the preferredOrder instance variable is handled. + +.. code-block:: console + + twisted.mail.alias now has full API documentation. + +.. code-block:: console + + The howto document page of Deferred now has documentation about cancellation. + +You don't need to worry about newlines in the file; the contents will be rewrapped when added to the NEWS files. + +Filing bugs and writing review requests +--------------------------------------- + +Tickets should be described well enough that the change is already justified and the new code should be easy enough to read that further explanations aren't necessary to understand it, but sometimes diffs themselves can be more difficult to read than either the old or new state of the code, so comments like *the implementation of foo moved from bar.py to baz.py* can sometimes make a reviewer's job easier. + +If you're a committer, please always make sure the "branch" field is current and force a build; this helps decrease review latency if the reviewer can see the diff and build results from the convenient links at the top of the ticket without waiting. + +Who can review ? +---------------- + +Changes must be reviewed by a developer other than the author of the changes. If changes are paired on, a third party must review them. If changes constitute the work of several people who worked independently, a non-author must review them. + +A reviewer need not necessarily be familiar with the specific area of Twisted being changed, but he or she should feel confident in his or her abilities to spot problems in the change. + +Twisted committers may review anyone's tickets; those submitted by other committers or those submitted by non-committer contributors. If a non-committer contributor submits a ticket that is acceptable to merge, it is the committer's responsibility to commit and merge the branch. When a committer reviews a ticket, they are responsible if there are any problems with the review. + +Non-committer contributors may review tickets which committers have submitted. When a non-committer views `review queue `_, it will ghost the rows submitted by other non-committers so they know not to review those. When a non-committer does a passing review, the committer may accept it and land their change, but they are then responsible for the adequacy of the review. So, if a non-committer does a review you feel might be incomplete, put it back into review and explain what they might have missed - this kind of reviewing-the-review is important to make sure that more people learn how to do reviews well! + + +How to be a good reviewer +------------------------- + +First, make sure all of the obvious things are accounted for. Check the "Things your branch or patch must contain" list above, and make sure each point applies to the branch. + +Use `pyflakes `_ to check the basic quality of the code. The following command will check all the files modified and added by a branch merge: + +.. code-block:: console + + git diff --staged --name-only | xargs pyflakes + +A reviewer may reject a change for various reasons, many of which are hard to quantify. Basically, use your best judgement, and don't be afraid to point out problems which don't fit into the list of branch requirements laid out in this document. + +Here are some extra things to consider while reviewing a change: +* Is the code written in a straightforward manner which will allow it to be easily maintained in the future, possibly by a developer other than the author? +* If it introduces a new feature, is that feature generally useful and have its long term implications been considered and accounted for? + + * Will it result in confusion to application developers? + * Does it encourage application code using it to be well factored and easily testable? + * Is it similar to any existing feature offered by Twisted, such that it might make sense as an extension or modification to some other piece of code, rather than an entirely new functional unit? + +* Does it require new documentation and examples? + +When you're done with the review, always say what the next step should be: for example, if the author is a committer, can they commit after making a few minor fixes? If your review feedback is more substantial, should they re-submit for another review? + +If you are officially "doing a review" - in other words, removing the review keyword - please make sure you do a complete review and look for *all* of these things, so that the author has as much feedback as possible to work with while their ticket is out of the review state. If you don't have time to do a complete review, and you just notice one or two things about the ticket, just make a comment to help the future reviewer, and don't remove the review keyword, so another reviewer might have a look. For example, say, "I just checked for a news file and I noticed there wasn't one", or, "I saw some trailing whitespace in these methods". If you remove the review keyword, you may substantially increase the amount of time that the author has to wait for a real, comprehensive review, which is very frustrating. + +The commit message +------------------ + +Several tools exist which parse commit messages to trunk, so the *Author*, *Reviewer*, and *Fixes* lines should conform to this format exactly. Multiple *Fixes* lines will close multiple tickets. *Refs* may also be used to attach the commit message to another ticket which is not being closed. The commit message should also describe the change being made in a modest amount of detail. + +Reverting a change +------------------ + +If a change set somehow introduces a test suite regression or is otherwise found to be undesirable, it is to be reverted. Any developer may revert a commit which introduces a test suite regression on a supported platform. The revert message should be as explicit as possible. If it's a failure, put the message of the error in the commit message, possibly with the identifier of the buildbot slave. If there are too many failures, it can be put in the tracker, with a reference in the message. Use the "Reopens" tag to automatically reopen the ticket: + +.. raw:: html + + 
+  Revert r<revision number>: Brief description
+
+  A description of the problem, or a traceback if pertinent
+
+  Reopens: ticket:<ticket number>
+
+ +Reverted branches are to be reviewed again before being merged. diff --git a/content/pages/ReviewingDocumentation.rst b/content/pages/ReviewingDocumentation.rst new file mode 100644 index 0000000..fd5e763 --- /dev/null +++ b/content/pages/ReviewingDocumentation.rst @@ -0,0 +1,63 @@ +Reviewing and Adding Documentation +################################## + + +The documentation may need help if: + +* Explanations are unclear +* Examples don't work or have become outdated +* The overall structure or the order in which information is presented is unintuitive +* Examples for major concepts are missing + +Note that the `example and howto documentation on the website `_ may be outdated, as it is only updated from trunk on releases. The `latest build on Read the Docs reflects current trunk `_. + +Editing example and howto documentation +======================================= + +These narrative docs live in `reStructuredText `_ (``.html``) files in subdirectories of `docs/ `_. Twisted uses the document generator `Sphinx `_ to generate the HTML files you see on the web from these ``.html`` files. After adding your changes, it's important to review your changes for correctness and to preview how they will look on the website. + +#. If you haven't already, `create your Twisted work environment `_. + +#. Make sure you have the latest version of the code + +#. Edit away! + +#. Preview your changes with Sphinx + +For example, if I made changes to `docs/core/howto/choosing-reactor.html`, I should + +``tox -e narrativedocs`` + +This generates `docs/_build/core/howto/choosing-reactor.html`, which you can view in a web browser with the command: + +``python -m webbrowser docs/_build/core/howto/choosing-reactor.html`` + +If everything looks good, submit a patch to the `.html` as described `here `_. + +Editing API Docs +================ + +The API docs are generated from the doc strings in the code by `pydoctor `_ , so to update what will be displayed in the API docs just update the doc strings. After making your changes, generate a test set of API docs to preview how they will look. + +#. If you haven't already, `create your Twisted work environment `_. + +#. Make sure you have the latest version of the code + +#. Edit away! Be sure to adhere to the docstring guidelines in the `Twisted coding standard `_. + +#. Preview your changes with pydoctor + +Generate the docs with the build-apidocs admin script like so: + +``tox -e apidocs`` + +The above produces a folder called `apidocs` in your current working directory. You can then open the docs in a web browser with the command: + +``python -m webbrowser apidocs/index.html`` + +If everything looks good, submit a patch as described `here `_. + +More +==== + +See also `DocumentationAnalysis `_ from an old Twisted documentation sprint. diff --git a/content/pages/Security.rst b/content/pages/Security.rst new file mode 100644 index 0000000..d3e6f45 --- /dev/null +++ b/content/pages/Security.rst @@ -0,0 +1,407 @@ +We appreciate your concern +########################## + + +We take security very seriously. Your input and feedback on our security is always appreciated. + +Reporting Security Issues +========================= + +**Send urgent or sensitive reports directly to security@twistedmatrix.com.** + +---- + +You may use our public key (below) to keep your message safe and please provide us with a secure way to respond. We'll get back to you as soon as we can; please bear in mind that Twisted is an all volunteer project and there may be some delay before we can respond. But please feel free to follow up if you think an unreasonable amount of time has elapsed without a response! + +Security Procedure for Developers +================================= + +The goal of the normal Twisted development procedure is to make all steps transparent and record all information at all times in a public location - either the issue tracker or a branch. + +The goal of the security variation of the Twisted development procedure is to keep track of progress resolving security issues while minimizing the window of time where information useful to attackers is available before a fix for the issue is available to Twisted users. + +This process is intended as a helpful recommendation; elements of it may be followed more or less strictly depending on the severity of the issue in question. + +#. Begin by filing a ticket which does not describe the issue and simply says 'security issue, description pending' and has the 'security' keyword. + +#. Unfortunately, we are not aware of a way to securely transmit our code to our public continuous integration systems and our code review process on Github without making the branch public. To minimize the time that this branch is available, perform some notifications first via private email. + + #. Try to find a reviewer ahead of time; agree upon a time to do the review, and push your code up such that continuous integration will be roughly complete by the time they're looking at it (roughly an hour in advance). + + #. Find a release manager to issue the security release, and coordinate with them around this time window as well; be sure they're aware that this is happening in advance. + +#. Push your code up, get it reviewed. While security fixes don't circumvent any of our usual processes, do be mindful of the fact that users are vulnerable while security fixes are pending, so as much as possible review feedback should be deferred. + +#. Backport the patch and perform the security release of the most recently released version. + +Aside from hiding the details of the issue while development is ongoing, all of the normal policies apply; security fixes require unit tests, etc. See `ReviewProcess `_ for further details. + +Our PGP key +=========== + +.. code-block:: console + + -----BEGIN PGP PUBLIC KEY BLOCK----- + Version: GnuPG v2.0.22 (Darwin) + + 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 + 2pOVp6XTYdUW + =HDSq + -----END PGP PUBLIC KEY BLOCK----- diff --git a/content/pages/SuccessStories.rst b/content/pages/SuccessStories.rst new file mode 100644 index 0000000..86a3af7 --- /dev/null +++ b/content/pages/SuccessStories.rst @@ -0,0 +1,275 @@ +SuccessStories +############## + + +**Have a success story for Twisted? Let us know! Contact success at twistedmatrix dot com** + +`ZONT Online `_ +======================================== + +ZONT Online is an online platform for monitoring and control of internet-connected smart devices. We use Twisted from the first days in 2011 to power our fully-asynchronous python backend. + +Twisted powers a wide range of our server-side tasks: user-facing and API web servers, websockets, queue workers, custom TCP/IP servers, email and push sending, 3rd-party API integrations and so on. + +We found Twisted to be mature, well-designed and having batteries included. Its networking primitives are flexible enough to build a wide range of services and to integrate with both blocking and non-blocking libraries. + +Special mention should be made about how carefully Twisted team documents its releases and maintains backward-compatibility. During the 10 years of our work with Twisted we continuously migrated through almost all Python versions from 2.7 to 3.9 and Twisted versions from 11.0.0 to 21.7.0 without notable surprises. + +-- Ilya Skriblovsky, Lead of Online Services Development, ZONT Online Ltd. + +`Battlehouse Games `_ +================================================== + +Battlehouse creates and operates massively-multiplayer strategy games for browser and desktop platforms. Our most popular titles are nearly 10 years old and have served over 4 million users. + +Twisted plays an important role in our Python-based server stack. We use Twisted to handle many protocols including HTTP, WebSockets, and SQL. The asynchronous coroutine model helps us deliver low-latency gameplay without adding too much complexity to the codebase. Across 10 years of continuous evolution, Twisted has proven to be the most stable, well-documented, and flexible low-level networking library for Python. + +-- Dan Maas, CTO, Battlehouse Games + +`LabRAD `_ +===================================== + +`LabRAD `_ is an RPC system designed for use in scientific research labs, presently in use by `more than a dozen academic and industrial labs around the world `_. + +The labrad python API has used Twisted for networking and asynchrony since around 2005, and Twisted continues to serve our needs well. Most of our servers use Python, and most LabRAD users use Python to run experiments; Twisted is an essential component for us on both the client and server sides. We particularly like the explicit coroutine style of asynchronous code made possible by the @inlineCallbacks decorator. + +-- Daniel Sank, LabRAD Project + +`Lucasfilm `_ +==================================== + +Lucasfilm has used Twisted in its business-critical production +processes since 2004. In 2009 we became sponsors of the project. + +We use Twisted to proxy database connections for our render farm, +which runs 24/7/365. In continuous deployment for six years, our +Twisted daemons have served many billions of queries. Twisted's +process spawning and monitoring capabilities are also used in numerous +automation and queuing services. In addition, its excellent, +full-featured Jabber implementation supports our person-to-person and +application-to-application messaging services. + +As a large and diverse enterprise, a key to our success with Twisted +is the professional way in which it is maintained. With a large body +of unit tests and rigorous code reviews, Twisted provides a smooth +upgrade path so that old features to continue to work and new ones +are production ready and rock-solid. + +-- Dave Peticolas, Lead Python Developer, Lucasfilm Entertainment Company Limited + +`FluidDB `_ +================================== + +At Fluidinfo, we're heavy users of Twisted. All of our infrastructure depends on it. FluidDB, our social database, is entirely built on Twisted, and we've released several core parts of it as open source: `txAMQP `_ , `txRDQ `_ and `txThrift `_. Not only that, but we have contributed to Twisted both with code and (albeit small) personal donations. + +It's not just that sponsoring was the fair the thing to do, it has also produced tremendous results in a framework crucial to our business. When you donate to the TSF it's simple math that more bugs get fixed, but also the quality of the entire Twisted project is enhanced. And when that happens, all of our products are enhanced automatically without us writing one line of code. So sponsoring is not just an act of generosity, it's an investment in Fluidinfo. Using and sponsoring Twisted has been an indispensable "force multiplier" for a growing start-up like us. + +-- Esteve Fernandez, CTO, Fluidinfo Inc. + +At Fluidinfo we chose Twisted as the basis of all internal networking for our +distributed, shared, always-writable database, FluidDB. We threw out +a year's worth of working, debugged, tested C code in order to move to Twisted. As +I often tell people, we're using Python because of Twisted, not the other +way round. I'm an unabashed Twisted fanboy. In particular, +Twisted's Deferreds are one of the most elegant and flexible +programming constructs I've ever worked with. +Plus, the Twisted community is great - not only the core developers, +but also the 180+ people constantly in #twisted in IRC. + +-- Terry Jones, CEO, Fluidinfo Inc. + +`Launchpad `_ +==================================== + +Canonical has been using Twisted as key part of Launchpad.net for over +five years now. We use Twisted to run our SSH servers, our process +pools, our package build farms, our file storage system and many other +things. Practically every time we need to glue two systems together, +we use Twisted. When we don't, we regret it later. + +-- Jonathan Lange, Product Strategist, `Canonical Ltd `_ + +`HipChat `_ +=================================== + +HipChat is a hosted group chat and IM service for businesses that uses the XMPP protocol behind the scenes. We use Twisted to power our fully clustered chat server and run many important job queue workers. + +Twisted's built-in XML support via the Twisted.Words and xmlstream modules have been life savers since XMPP is very XML heavy. They've been rock-solid and keep us from having to work with with XML directly which is a wonderful thing. + +One of the greatest time savers is the combination of Deferreds and the @defer.inlineCallbacks decorator. These allow us to write code that is asynchronous but stays easy to read and maintain. No more getting lost in a sea of callback functions. I mention it because I truly miss them when playing with Node.js, particularly Python's 'yield' and Twisted's Deferreds! I feel crippled without them. + +Bottom line: we built and launched a successful business on Twisted & Python in 6 months with no prior knowledge of either. It's a very productive environment with great performance and maintainability. What more could you want? + +-- Garret Heaton, Co-founder, `HipChat `_ + +`Justin.tv `_ +===================================== + +Justin.tv is the largest live video site on the internet. We allow anyone to broadcast live video from their PC and chat with viewers. Every second of every broadcast is archived so it can later be browsed, searched, or made into highlight clips. + +Each of Justin.tv's half a billion monthly pageviews passes through a custom Twisted caching engine. "Twice" is a caching reverse proxy with a basic templating engine. It runs as a cluster of roughly 120 processes across a dozen machines and handles peak loads of 20,000 dynamic pageviews per second. The project has been `open sourced here `_ + +-- Kyle Vogt, VP Engineering, Justin.tv, Inc. + +`TweetDeck `_ +======================================= + +TweetDeck aims to build a browser for the +real-time web. Right now we're the biggest Twitter client after the +website itself, and are rolling out full integration with Facebook and +other services. With TweetDeck you can organize real-time streams of +information into a convenient grid format that allows easy digestion. + +We use Twisted to power our backend services, specifically our new +accounts system and sync functionality we introduced recently +(http://tweetdeck.com/beta/features/take-tweetdeck-with-you/). We've +deployed our Twisted services over the Amazon cloud - specifically, we +use EC2 and SimpleDB. Writing a REST api service used by hundreds of +thousands active users was a snap with Twisted. We'll continue to use +Twisted as we broaden our server-side processing goals. + +-- Reza Lotun, Software Engineer, TweetDeck, Inc. + +`Evennia `_ +==================================== + +Evennia is a modern Python MUD/MUX/MU* server, aimed at the easy creation of text-based massively multi-user online games. We use Twisted for all our networking needs, along with `Django `_ for database abstraction and web features. The two work beautifully together. + +When developing Evennia we have found that using Twisted not only gives us great performance advantages, but also helps us to easily expand on the ways people connect to Evennia-powered games. Whereas traditional MUD servers only speak telnet, Evennia additionally comes with its own browser-based client and allows for expanding with custom game protocols in any combination. Evennia also serves the MUD’s website, alleviating the need to install and set up a third-party web server. All of this is straightforward to implement and maintain thanks to Twisted! + +-- Griatch, Maintainer, Evennia project + +NASA +==== + +My team is developing a modular application to integrate CAD/CAE/CAM tools and data and to enable collaboration among distributed teams of engineers working on NASA projects. We have selected Twisted as our framework because of its pluggable, asynchronous protocols, support for multiple interfaces and protocols per service, integration with PostgreSQL, and just generally excellent layered architecture. + +-- Stephen C. Waterbury, NASA + +`Shared Solar `_ +============================================= + +`Shared Solar `_ is a rural electrification +project providing over 3000 people with electricity in sub-Saharan +Africa (Mali and Uganda) with proposed deployments in Kenya and Haiti. +Due to the nature of the physical environments, and the model of +distributed generation, we need to have local intelligence at our +sites for the distribution of prepaid electricity and management of +the deployed infrastructure. + +This distributed/local intelligence is built using Twisted. Twisted +has helped me prototype and deploy rapidly, learn and react quickly to +on-the-ground issues as they arise, and adapt the service to +configurations using different hardware and protocols. Without the +services built around Twisted, I'm certain the project would not be as +successful - it has helped us turn otherwise static infrastructure +into something much more in very short time. + +Huge thanks to the Twisted community for their great work and making +this possible. I'd also like to acknowledge the wonderful support by +the folks on irc:#twisted. + +-- Rajesh Menon, Software Engineer, SharedSolar + +`HybridLogic `_ +=============================================== + +`Hybrid Web Cluster `_ is a load-balanced and redundant web cluster built in Twisted which supports all standard LAMP websites. + +The web cluster uses ZFS on FreeBSD for its unique ability to efficiently send differential snapshots over a network. But it is Twisted that has enabled us to turn that capability into a cluster filesystem. Everything is asynchronous, for example: + +* polling "zfs list" and "zfs mount" for filesystem state +* communicating with other nodes via XML over Spread +* reconfiguring distributed servers on-the-fly +* handling thousands of internally proxied requests over thousands of sockets simultaneously. + +Without Twisted we'd have to rely on threads, or spend valuable time writing an event loop that wouldn't be anywhere near as spectacular as Twisted's. Twisted has enabled us to focus on building phenomenal features (like seamlessly moving websites and databases between servers) instead of wasting precious resources re-inventing wheels. + +Using Twisted has been massively beneficial for us. Not only have the +experts been always on-hand in real-time on IRC, but the code quality +and the expressive power of the library is unparalleled. In particular +the combination of Perspective Broker with Deferreds make expressing +otherwise tricky distributed algorithms a pleasure. + +Twisted has been crucial at Hybrid Logic for making an awesome Hybrid Web Cluster platform that guarantees our customers' sites are fast and their data is safe at all times. + +Thank you Twisted! + +-- Luke Marsden, CTO, HybridLogic Ltd. + +PowerCard +========= + +PowerCard is the software platform we developed for `PowerCard Rewards `_ and the Original Rewards program for `Original Restaurants `_. Original Restaurants promotes unique, local restaurants by providing cooperative marketing, customer sharing, and a distinctive Rewards Card program. + +We use Twisted extensively for back-end transaction services for the loyalty rewards and gift card programs. We also used Twisted in our client-side applications installed in demanding restaurant environments. Twisted was crucial in our ability to craft solutions to interoperate with multiple restaurant POS vendors (Micros, Aloha/Radiant, Squirrel, etc.), each with differing protocols and access methods. Our choice of Python and Twisted allows us to rather easily extend our system to support new features and requests with limited amount of developer time and budget. + +Key features for us: + +* Easy implementation of custom and existing network protocols +* Consistent APIs for code sharing between client and server implementations +* Windows integration +* Client GUI applications +* Services are a snap to implement +* Community support is very helpful + +-- Lucas Taylor, CTO, PowerCard + +`Botonomy LLC `_ +====================================== + +Botonomy LLC is a small software firm in the Philadelphia area. We help small teams solve large problems. + +Our first application, `ProjectPipe `_ , is a hosted project management solution that provides midsize teams with everything that they need to manage IT projects. We have built our hosted application infrastructure atop Twisted, Nevow, PostgreSQL, and Jabber/XMPP. Twisted's multi-protocol support has been one of the key enablers of the unique technical architecture that we employ in our product offerings. + +The core Twisted development team consistently demonstrates a strong commitment to delivering robust, high quality software. Twisted's documentation is accurate and concise, and the expertise and helpfulness of the larger developer community is second-to-none. + +When evaluating the technologies on which you are staking your business, you need to evaluate both the code and the community that surrounds it. Twisted passes with flying colors in both regards. + +-- Christian Simms, Botonomy LLC + +`Reflexions Data `_ +=================================================== + +At Reflexions Data, we provide custom development services for a wide variety of clients. We recently completed work on a project for a new client; the timeframe available required us to expedite every step of the development process. Twisted allowed us to quickly implement a custom client/server protocol with a wide variety of extra functionality for free. + +The quality of the Twisted networking core is unmatched in the open- or closed-source arenas. Due largely to its asynchronous networking model, we were able to ensure our clients scalability needs would be met. + +Our experiences with the Twisted developer community were top- notch; the turnaround time on questions posted to the developer mailing list was simply amazing. We were so pleased with the results of our first professional use of the Twisted core that we plan on investigating how we can make use of the other facets of the Twisted project. + +-- Phil Christensen, Senior Developer, Reflexions Data, LLC + +`Masters of Branding `_ +========================================================== + +At Masters of Branding we use Twisted as the networking core for all of our client and server RFID software. It was by far the easiest framework to develop with, debug under, and extend for our purposes to support protocols such as SOAP, HTTP, and Macromedia Flash-compatible XML Sockets. The API and event model are both very well thought out and has accommodated all of our networking needs from database-heavy server software on Linux to (py)OpenGL visualization applications on win32. + +The ease and power of Python and Twisted really showed through when we took one of our applications developed in and for Linux and ported it to run as a Windows NT service in less than day. New users to the framework will not only be impressed by the power of the software, but also that the developer/user community responsible for it are incredibly helpful and often provide much better support in minutes or hours than you'll see from commercial shops given days or weeks. + +-- Bob Ippolito, CTO, Masters of Branding Inc. + +`Adelux `_ +================================= + +Adelux develops custom internet applications such as portals, network security tools, communication-related programs, and software that leverages other systems. + +We discovered Twisted 10 months ago, and now it is a key element of our development strategy. We have successfully used Twisted on several projects, of very different problem domains. + +We developed a highly scalable realtime application for customer support, which serves web-based clients as well as clients implemented in any of the many protocols supported by Twisted. Twisted was also used to develop targeted proxies for various applications supporting more than 15.000 users. Twisted handles the charge with no problem. + +We intend to continue using Twisted on upcoming projects, especially since integrated support for databases and new services are being added very quickly. + +We found Twisted to be powerful, comprehensible, well documented, and backed by a good helpful community. We'll use it on our next products for sure! + +-- Luc Stepniewski, Head Engineer, Adelux, France + +MC-Foo and Ldaptor +================== + +I was writing `MC Foo `_ , a networked multiuser learning Ogg/MP3 jukebox application, in C, and was frustrated about the amount of time it took to debug. I decided I should use a higher-level language. I liked how Python felt, but had never written a single line of Python. I decided it was time to learn. Five hours later, the core of my application was rewritten in Python, using Twisted for main loop and networking. Another five hours later, I had replaced my oversimplistic line-based protocols with PB, the Twisted RPC protocol. Twisted has also enabled me to easily add features such as implicit persistence into MC Foo. And it even has nice GUI integration, allowing one to do sane networking in a GUI application. + +Since then, I have created `Ldaptor `_, a pure-Python LDAP library, utilities and a web interface, as a data structure library, Twisted protocol and Twisted applications. The way how the web interface plugs in with the LDAP protocol handling still manages to amaze me. + +The developer community behind Twisted is just great, and the IRC channel is a great source of information. All in all, I feel Twisted is one of the most interesting projects on the net. + +-- Tommi Virtanen diff --git a/content/pages/TSF/FoundingSponsors.rst b/content/pages/TSF/FoundingSponsors.rst new file mode 100644 index 0000000..3e00d4f --- /dev/null +++ b/content/pages/TSF/FoundingSponsors.rst @@ -0,0 +1,71 @@ +Founding Sponsors +################# + + +We'd like to acknowledge those companies and individuals who made critical contributions to Twisted during our infancy. Thanks for helping us get on our feet. + +Companies +========= + +.. raw:: html + +
+
+ + + +
+
+
+
+ +
+
+
+
+
+ +
+ +
+ +
+
+ +
+
+
+ +
+
+ +
+
+
+
+
+
+
+
+
+ +
+ +Individuals +=========== + +* Glenn Tarbox +* Drew Perttula +* Eino Makitalo +* David T Ripton III +* Alex Clemesha +* Karl Bartel +* Nicola Larosa +* Chris Armstrong +* Michel Pelletier +* Valentino Volonghi +* Hein-Pieter van Braam +* Ilya Novoselov +* N J Carriero diff --git a/content/pages/TheTwistedShow.rst b/content/pages/TheTwistedShow.rst new file mode 100644 index 0000000..00dbab1 --- /dev/null +++ b/content/pages/TheTwistedShow.rst @@ -0,0 +1,21 @@ +The Twisted Show +################ + + +`The Labs `_ is currently producing semi-regular podcasts that discuss the use of the Twisted networking framework within various businesses and projects around the world. We've been getting great feedback and we want to be able to share this with a wider audience. + +As part of the editing process, we will include contextual links to related material (both Twisted-centric as well as other, off-site content). Additionally, we will present "bonus" material at the end of each interview transcript (or podcast) that is intended to encourage curious readers in further play and exploration. + +**Want to be a Guest Star?** Send an email to oubiwann at adytum dot us! + +Interviews +========== + +* `Synthesis Studios `_ - Audio recording from interview on 2008.04.23 +* `Chesspark, Games and Twisted `_ - Audio recording from interview on 2008.02.25 +* `Renkoo talks Twisted `_ - Transcript from interview on 2006.12.07 + +Podcasts +======== + +Subscribe to our podcasts `here `_. diff --git a/content/pages/Twisted/TwistedAdvantage.rst b/content/pages/Twisted/TwistedAdvantage.rst new file mode 100644 index 0000000..b1c6e53 --- /dev/null +++ b/content/pages/Twisted/TwistedAdvantage.rst @@ -0,0 +1,50 @@ +The Twisted Advantage +##################### + + +Flexibility +=========== + +Twisted's codebase is small and it contains many hooks for dynamic content. With the source code and an open license, you know you'll never be in a position where you can't add a feature you need. + +Security +======== + +Twisted is written in `Python a high-level language `_, rendering it immune to the most common class of security flaw in network software, the "buffer overflow": buffer overflows have allowed worms and crackers to tamper with or disable internet servers. Twisted also takes advantage of operating-system security features whenever possible, delegating responsibility for tasks to the appropriate user to make the system more difficult to exploit. + +Stability +========= + +Thanks again to `Python's `_ error handling mechanisms, the Twisted server framework is extremely stable. Even the most bleeding-edge development servers -- those we run here at http://twistedmatrix.com -- don't crash, and rarely (if ever) need to be restarted. + +But where do these advantages help you directly? Twisted can do a lot, so it depends on what you're using it for. Let's take a look at some potential applications you might have in mind... + +Publish a Web Site +================== + +The twisted.web webserver is a scalable, small-footprint web server that's easy to configure. It's efficient enough to serve a high-traffic website, completely dynamic and reconfigureable on the fly, and simple enough to configure that you can have it set up and running in just minutes after you've downloaded it. It's also portable, so you can easily share your web content between Windows, Unix, Macintosh, and other systems, all running twisted.web. It also shares the security advantages of the rest of Twisted. + +Twisted Web scales down as well as up. Use it to share files with your friends at home or to publish large files on your enterprise intranet. + +Develop Servers at Lightning Speed... +===================================== + +Twisted integrates a large number of consistent APIs for developing new Internet services. This translates to a wide number of protocols and components that are ready to work with your new server before you've written the first line of code. + +In addition to legacy protocol support, the twisted.spread package allows developers to quickly develop new protocols and services with arbitrarily complex interfaces, prototyping new client functionality on the fly. + +What does this mean in terms of development time? If you're developing a new server, it could take literally a year off of your implementation time -- and that's just now. Twisted development is proceeding at a rapid pace, and by the time you've finished your development you may find a host of new features that you didn't have to spend a moment thinking about! + +Twisted comes under a relatively non-restrictive open-source license, making it suitable for both commercial and open-source development. + +... And Clients Too +=================== + +Unlike some other server frameworks, Twisted makes it simple to develop a client using the same code-base. Whether you are developing both a client and server in tandem with the twisted.spread package, or independently developing a client for an existing protocol, Twisted's integration with a wide variety of different graphical toolkits will allow you to run any common code completely unchanged from your server environment. + +Engage an Active Community +========================== + +Twisted has a knowledgeable, energetic, and growing developer community. Members of this community have concern over issues like those you will be facing in your custom server development and have solved those issues for themselves already within the Twisted framework. + +We (the developers of Twisted) try to use every piece of the software we write ourselves -- after all, the reason we wrote it was that we needed it! This means that if there's a bug, we're concerned about it. Twisted comes with a full set of automated acceptance tests and unit tests. diff --git a/content/pages/Twisted/TwistedCommunity.rst b/content/pages/Twisted/TwistedCommunity.rst new file mode 100644 index 0000000..ff977c1 --- /dev/null +++ b/content/pages/Twisted/TwistedCommunity.rst @@ -0,0 +1,45 @@ +Twisted Community +################# + + +For interacting with the twisted community members, you have several options: + +Mail Lists +========== + +If you want to participate in Twisted's community or development, you probably want to join the main mailing list: + +* `twisted-python `_ the main Twisted discussion list + +There are also more specific lists, if your interest is narrower: + +* `twisted-web `_ - web-specific technologies, including twisted as WSGI, twisted.web, klein, and treq +* `twisted-jabber `_ - xmpp-related projects, including twisted.words.protocols.jabber. + +You can subscribe to these mailing lists using the web interfaces linked above. + +Stack Overflow +============== + +Stack Overflow is a programming Q & A site. You can find Twisted-related questions there, often with answers: + +* https://stackoverflow.com/questions/tagged/twisted + +Real-Time Chat +============== + +Server: ``irc.libera.chat`` (more about `the Libera IRC network `_) + +For support, you can join one of several channels: + +- `#twisted `_ | `Logs `__ - support for Twisted and its ecosystem +- `#twisted.web `_ | `Logs `__ - support for Twisted Web, and ecosystem projects such as Treq, Klein and the Nevow templating system.; both for development with it and deploying it + +If you're working on Twisted, you should join the development channel. + +- `#twisted-dev `_ | `Logs `__ - for development of Twisted + +Blogs +===== + +Read `Planet Twisted `_. diff --git a/content/pages/Twisted/TwistedDevelopment.rst b/content/pages/Twisted/TwistedDevelopment.rst new file mode 100644 index 0000000..47ca21f --- /dev/null +++ b/content/pages/Twisted/TwistedDevelopment.rst @@ -0,0 +1,282 @@ +Twisted Development +################### + + +`Contribute `_ > Twisted Development + +.. contents:: + +Contributing +============ + +Twisted uses the `The Ultimate Quality Development System `_, in addition to this ReviewProcess. + +If you want to become a developer, it is important to understand that all your contributions (including those initial patches you send to the bug tracker) will have to be licenced under the `MIT License `_. + +Getting the source code +----------------------- + +You can get Twisted's source code here: + +``git clone https://github.com/twisted/twisted.git Twisted`` + +If you intend to contribute to Twisted via Git, but do not have write access to the Twisted repository, you should instead fork the project by going to https://github.com/twisted/twisted and clicking on "fork". +Then set up your local repository: + +.. code-block:: console + + git clone https://github.com//twisted.git Twisted + cd Twisted + git remote add upstream https://github.com/twisted/twisted.git + git fetch upstream + git branch -u upstream/trunk trunk + +NOTE for experienced Git users: for historical reasons, Twisted's main branch is currently named "trunk", instead of the usual "master". + +.. _creatingyourworkenvironment: + +Creating your work environment +------------------------------ + +Twisted development does not enforce any specific work/build environment. + +Twisted uses Tox for managing the environment used in the continuous testing systems (GitHub Actions, Circle CI, Travis-CI, Appveyor). + + +With Tox +~~~~~~~~ + +You will need Tox version at least 2.4. (On Ubuntu 16.04 you have 2.3.1). + +See README.md and tox.ini comments for more details. Note that some environments are for CI systems and not designed for local runs. + +Here is an example for running the test in a specific environment: + +.. code-block:: console + + $ tox -e alldeps-nocov twisted.conch.test.test_transport + $ tox -e lint,black,newsfragment,manifest-checker + +You can also use tox just to initialize the dev virtual environment and then manually active and use it: + +.. code-block:: console + + tox -e nodeps-nocov-posix --develop + . build/nodeps-nocov-posix/bin/active + trial twisted.conch.test.test_transport + + +Without Tox +~~~~~~~~~~~ + +For faster runs, you can skip tox and build a custom working environment. + +For your convenience, the setup.py file defined optional components, `dev` component being one of them. + +Here is an example of creating an environment using virtualenv. + +.. code-block:: console + + # Create base environment. + virtualenv build/ + # For Unix + . build/bin/activate + # For windows (replace .bat with .ps1 for powershell) + build/Scripts/activate.bat + pip install pypiwin32 + + # Install dev dependencies, also forcing upgrade of existing versions. + pip install -U -e '.[dev]' + # At least on my Ubuntu 16.06 the install_requires were not correctly installed, + # so I am doing a manual install based on the content of src/twisted/python/_setup.py. + pip install automat incremental constantly diff_cover + + # Use the dev tools. + # Prefix this with the path to python.exe on Windows + trial twisted.conch.test.test_transport + + # Using the coding standard guidelines validation tool... will get a lot of false positives + twistedchecker twisted.conch.ssh.transport + # On Linux/OSX there is a helper to only raise error for the diff + ./.travis/twistedchecker-trunk-diff.sh src/twisted/ + + # Static code analysis and checkers (see tox.ini for inspiration) + pyflakes twisted/conch/ssh/transport.py + git diff trunk... | admin/pycodestyle-twisted.py --diff + ./bin/admin/check-newsfragment src/twisted/ + check-manifest --ignore "docs/_build*,docs/historic/*,admin*,bin/admin*,twisted/topfiles/*.Old" + +Submitting a Patch +------------------ + +Here's a quick step-by-step guide to getting from an idea for an improvement to Twisted to something that we can integrate. First, I'll explain just the mechanics of getting your code into review, not what the code itself should do. If you actually want us to be able to use your code, you will also want to read the section below on getting your patch accepted, too! + +#. For the patch you are submitting, make sure that a `ticket exists using the "search" field above `_, and Google for the patch which you are submitting. + + #. If you can't find one, file a new ticket using the `new ticket `_ link above. See: `Tickets Management `__. + +#. Create a `fork on GitHub `_ and clone it (see `Getting the source code <#getting-the-source-code>`_ above). + +#. Create a branch in git for your code. If your ticket is **1234** and your GitHub ID is **myuserid**, you can create a branch like: + +.. code-block:: console + + git checkout trunk + git pull + git checkout -b 1234-myuserid-mychange + +#. Edit the code in the branch that you just checked out, making your awesome change to Twisted. + +#. Make sure that your patch fulfills all of the requirements of the `ReviewProcess `_, so you don't need to submit your patch many repeated times. Run ``tox -e black-reformat`` to automate the formatting. + +#. Every patch needs a `topfile news fragment `_ to tell the user what was changed + +#. Commit your changes + ``git commit -am "Changed some stuff"`` + +#. Push your changes to GitHub + ``git push 1234-myuserid-mychange`` + +#. Create a `GitHub pull request `_ for the **my-new-change** branch. Make sure that in the pull request, you put a link to the ticket that you filed above. + +#. In your ticket, put a link to the GitHub pull request. + +#. Put the ticket into review. This is accomplished by doing the following: + + #. enter the word **"review"** into the **"Keywords"** field of the ticket. (If there are other keywords already there, just add a space to separate the keyword.) + + #. Click on the "reassign to" radio button. + + #. Select the topmost, blank entry from the "reassign to" button. + + #. Optionally, add a comment explaining which patch you would like reviewed (if there are already other attached files), and explaining **what** your change does (as opposed to the **why** you want it done, which you should have put into the ticket's summary and description). + + #. Hit "submit changes". + +#. At this point, you need to wait for feedback. If your patch is very good, very simple, and obviously correct, we may just apply it, but it is ''very unlikely'' that the first draft of a patch will be accepted as-is. When a Twisted developer reviews your patch, they will re-assign the ticket to you; you can `see the list of tickets assigned to you by clicking here `_. Unfortunately, the time it takes us to deal with a ticket submitted for review is highly variable, and depends on how many other tickets are waiting review, the amount of free time that the Twisted core development team has, and how many resources we have available for `sponsored development `_. + +#. When you do receive a review comment, push changes to your branch which address that feedback, then place the ticket back in review. + +#. When placing the ticket back for review, make sure your branch is up to date with latest trunk, and that there will be no merge conflicts. + +#. Don't push your changes by rewriting the history, merge trunk into your branch. + + +Getting Your Patch Accepted +--------------------------- + +If you are interested in contributing to Twisted for the first time, consider working on an existing ticket rather than contributing a new feature. Fixes for existing problems or implementations of already-requested features will generally take priority over new ideas. Consider discussing the work you want to do with `other Twisted developers first `_. + +Familiarize yourself with project policies and coding standards and make sure your full contribution (code, test, documentation, design) adheres to it. See: `Policies <#policies>`__. + +There are a couple of tools to help with automatic policy checks. +Make sure there are no errors when running these tox environments (or equivalent checks): + +``$ tox -e lint,black,newsfragment,manifest-checker`` + +Make sure that you have written unit tests and docstrings for all code which has changed in your patch. It works best if you use test-driven development to write your patch initially, and write your tests before your code. (Believe me, if you write your tests after you write your code, we ''will'' know. It's more obvious than you think.) + +Run the full test suite ''before'' submitting your patch, and fix any problems you discover. If a reviewer notices failing tests, they may not give your code a deep look, and you may have to wait longer for a second review. See: `Tools for development <#tools-for-development>`__. + +Some users may discover that their system is unusual and Twisted's test suite **does not pass** "out of the box". If this is the case, just make sure that the **same** tests are failing for you in a pristine checkout of trunk and with your changes applied. Then, in addition to submitting your patch, please let us know about the problem with the test suite! + +Tools for Development +===================== + +There are a few useful tools for developing Twisted. Some of them are included with Twisted, some are third-party dependencies. + +Command from this section assume that you run them from withing Twisted source code checkout root. + +To run the tests, simply run `trial twisted`. Make sure you run trial command that comes with twisted source code and not the one provided by your operating system. + +To generate the narrative documentation or API documentation, see `the wiki page on Twisted documentation `_. + +After every commit to Twisted, the buildbot runs all the unit tests and reports `test results on several platforms `_. Here is a page showing only the `test results on supported platforms `_. All tests on supported platforms always pass. Watch the buildbot. Because sometimes, the buildbot watches back. + +Runtime and development dependencies +==================================== + +Required and optional dependencies are now documented inside the source code _EXTRAS_REQUIRE variable + +Some optional dependencies are not yet documented and they are presented here: + +* pygtk (or pygi or pygobject or something) is required for the gtk class of reactors +* wxpython is required for wxsupport / wxreactor +* gadfly, sqlite, pypgsql, psycopg, mysqldb, kinterbasdb (at least one) are required for twisted.enterprise.adbapi +* SOAPpy is required for Twisted Web's SOAP support +* pypam is required for twisted.cred PAM integration + +And there are some additional development tools: + +* subunit is required for trial's subunit output plugin +* cython is required to update iocpreactor and some Failure unit tests + +Tickets management +================== + +All changes to source code require a ticket. + +If you file a new ticket, please start with a clear description of **why** such a change is desirable. +We can read your attached code to find out **what** you are doing, but we can't read your mind to figure out why you want it done! + +A Twisted ticket can be of one of three types. + +* **Enhancements** are used for feature additions. These typically take the form of a new API or an expansion of an existing API. Enhancement tickets should clearly describe the desired feature. The more well specified a feature is, the more likely it is to be implemented (and importantly, the more likely it is that what is implemented will actually be what the reporter wanted!) and the easier it is to implement. Remember that the ticket is possibly the only persistent record of the feature request. If it is not self-contained and sufficiently detailed, then it will likely fail to communicate the reporter's idea, diminishing its value (possibly all the way down to zero). + +* **Defects** are used to track bugs in existing APIs. Defect tickets are easier to specify than enhancements. A defect should briefly describe the problem, but the bulk of the ticket should be a runnable program (ideally in the form of a unit test) which demonstrates the bug. + +* **Regressions** are similar to defects, but are for bugs which are introduced into APIs in newer releases of Twisted. Like defect tickets, regression tickets should have a runnable program attached to demonstrate the problem. + +* **Release blocker: regression** a ticket which blocks the release of the next Twisted version due to a regression. + +* **Release blocker: wrong release notes** a ticket which blocks the release of the next Twisted version due to a problem in the release notes. + +* **Release blocker: release process bug** a ticket which blocks the release of the next Twisted version due to a problem/issue/defect in the release process itself. + +A ticket can have attached the following official tags `BugKeywords `_. + +There are some UsefulQueries for finding issues in the tracker. + +.. _policies: + +Policies +======== + +This series of documents is designed for people who wish to contribute to the Twisted codebase. + +* `Development policies `_ + +* `Naming Conventions `_ + +* `Epytext `_ for docstrings format + +* `ReStructuredText and Sphinx `_ for narrative documentation. + +* `Security `_ + +* `Philosophy `_ + +* `Review Process `_ + +* `Contributor Advancement Path `_ + + +Wiki pages maintenance +====================== + +Changes to wiki pages don't require a ticket. + +To prevent spam-bots, newly registered accounts don't have write access for wiki pages. + +If you want to edit wiki pages, ask for write permission via one of `community communication channel `_ . Please mention your Trac username. + + +Win32 development +================= + +If you want to hack Twisted on Win32, see Ying Li's `short tutorial on setting up a Twisted win32 development environment `_; but note that it describes getting the code with Subversion and you will currently need to use Git. + +Twisted Maintenance +=================== + +You might be interested in learning about tasks related to maintaining this website? or for `releasing Twisted `_. diff --git a/content/pages/Twisted/TwistedMatrixLaboratories.rst b/content/pages/Twisted/TwistedMatrixLaboratories.rst new file mode 100644 index 0000000..580211a --- /dev/null +++ b/content/pages/Twisted/TwistedMatrixLaboratories.rst @@ -0,0 +1,83 @@ +Twisted Matrix Laboratories +########################### + + +... is a loosely-affiliated group of hackers from around the globe, working on software together. Much of this software is to facilitate interaction between geographically disparate people -- infrastructure for massively multiplayer games, personal information spaces, and other "places you can be" on the internet. Some of it is also used to target a wide array of powerful lasers in geosynchronous orbit, to prevent a massive outbreak of the whitespace-eating nanovirus from the future. + +Comprised of ninjas, rogue temporal authority enforcement agents, ancient greeks, and supernatural forces from Mesopotamia, the Labs is concerned with bringing you the highest-quality internet available anywhere south of Bordeaux (or north of Oulu). Therefore all Twisted developers are required to CLASSIFIED. + +The Matrix +========== + + **Glyph "Glyph" Lefkowitz** : glyph (at) twistedmatrix.com + electric violin + **Jean-Paul "exarkun" Calderone** : exarkun (at) twistedmatrix.com + geopolitical sociographic dissonance engine + **Christopher "radix" Armstrong** : radix (at) twistedmatrix.com + percussion + **Thomas "therve" Hervé**: therve (at) free.fr + nuclear ocarina + **Paul "z3p" Swartz** : z3p (at) twistedmatrix.com + oboe + **Allen "Dash" Short** : washort (at) twistedmatrix.com + vocals and guitar + **Jonathan "jml" Lange** : jml (at) twistedmatrix.com + pipe organ + **Ralph "ralphm" Meijer**: twisted (at) ralphm.ik.nu + vocals and timbales + **Pavel "!PenguinOfDoom" Pergamenshchik** : ppergame (at) gmail.com + electronic balalaika + **[wiki:People/DuncanMcGreggor Duncan "oubiwann" McGreggor]**: oubiwann (at) twistedmatrix.com + Calabi–Yau manifold-pipes + **Andrew "spiv" Bennetts** : andrew (at) bemusement.org + glockenspiel + **Itamar "itamar" Turner-Trauring** : itamar (at) itamarst.org + alto recorder + **Stephen "jerub" Thorne**: jerub (at) twistedmatrix.com + trumpet + **Kevin "Acapnotic" Turner** : acapnotic (at) twistedmatrix.com + trombone + **Donovan "fzZzy" Preston** : dp (at) twistedmatrix.com + bass and harmonium + **Jürgen "snibril" Hermann** : jh (at) twistedmatrix.com + synthesizer + **Moshe "vertical" Zadka** : moshez (at) twistedmatrix.com + accordion + **Benjamin Bruheim** : grolgh (at) online.no + kazoo + **Travis B. "Nafai" Hartwell** : nafai (at) twistedmatrix.com + keyboards + **Gavin "skreech" Cooper** : gavin.cooper (at) gmail.com + torque wrench + **Bob "etrepum" Ippolito** : bob (at) redivi.com + low frequency oscillator + **Jonathan D. "slyphon" Simms** : slyphon (at) twistedmatrix.com + theramin and drums + **Brian "warner" Warner** : warner (at) twistedmatrix.com + hertzian field renderer + **Mary Gardiner** : mary-twisted (at) puzzling.org + krummhorn + **Eric "teratorn" Mangold** : teratorn (at) twistedmatrix.com + serpentine bassoon + **Tommi "Tv" Virtanen** : tv (at) twistedmatrix.com + didgeridoo + **Justin "justinj" Johnson** : justinj (at) twistedmatrix.com + bass mandolin + **Sean "Riley" Riley** : sean (at) twistedmatrix.com + grand piano + **Thijs Triemstra** : info (at) collab.nl + TR-909 + **Jessica "jesstess" McKellar** : jesstess (at) mit.edu + Moog + **Laurens "lvh" Van Houtven** : lvh (at) twistedmatrix.com + SID 8580 R5 + **Amber "HawkOwl" Brown** : hawkowl (at) atleastfornow.net + kookaburra whistle + + +Extras +====== + + Jerry Hebert : jerry (at) cynics.org + Nick Moffit : nick (at) zork.org + Jeremy Fincher diff --git a/content/pages/Twisted/TwistedProject.rst b/content/pages/Twisted/TwistedProject.rst new file mode 100644 index 0000000..9c159a7 --- /dev/null +++ b/content/pages/Twisted/TwistedProject.rst @@ -0,0 +1,26 @@ +Twisted +####### + + +Twisted is a networking engine written in Python, supporting numerous protocols. It contains a web server, numerous chat clients, chat servers, mail servers, and more. + +Twisted is made up of a number of sub-projects which can be accessed individually through the `twisted projects index `_. + +Twisted is available under the `MIT Free Software licence `_. + +Downloads +========= + +See the `Downloads `_ page. + +Documentation +============= + +`All sorts of documentation `_ is available for Twisted, including a complete `API reference `_ of Twisted and all subprojects. + +Contact +======== + +Subscribe to the `twisted-python `_ mailing list or visit the #twisted channel on irc.libera.chat to ask questions. + +You can browse the `Twisted Core tickets `_. Furthermore, if you `login `_, then you can `report a bug `_ or `request a feature `_ using the issue tracker. diff --git a/content/pages/Twisted/TwistedSoftwareFoundation.rst b/content/pages/Twisted/TwistedSoftwareFoundation.rst new file mode 100644 index 0000000..3b9e57a --- /dev/null +++ b/content/pages/Twisted/TwistedSoftwareFoundation.rst @@ -0,0 +1,105 @@ +Twisted Software Foundation +########################### + + +.. _Software Freedom Conservancy: http://sfconservancy.com/ + +The name "Twisted Software Foundation" is a reference of convenience to our sponsorship by `Software Freedom Conservancy`_, a 501(c)3 non-profit organization. Conservancy has allowed us to pool organizational resources with other projects, such as Inkscape, Samba, and Wine, in order to reduce the management overhead associated with creating our own, dedicated legal entity. + +Background +========== + +At the end of January, 2008, the Twisted project finalized a sponsorship agreement with `Software Freedom Conservancy`_. For years prior to this, we had explored the options available to us for creating a foundation; due to our lack of resources, time and money, they were all prohibitively expensive. At the urging of individuals and organizations, we again explored other options. This most recent effort was a culmination of hard work over the last year between the Twisted project and the Conservancy, and we are delighted to present the results to the community: "Twisted Software Foundation". + +Goals +===== + +Our goals are simple: we want to be able to continue improving Twisted -- everything from code reviews to specialized bug fixes to paying hosting bills -- for the benefit of the community, the users of Twisted. We want sponsors to be able to make tax-deductible donations, and we want to provide a dedicated forum (initially, a sponsors-only mail list) where our sponsors can give voice to their own vision of how Twisted can be better. + +Sponsors +======== + +For a list of our current sponsors, visit here `out sponsorship page `_. + +Benefits of Sponsorship +======================= + +You (or your company) can become a Twisted Sponsor! Here are some of the benefits: + +* You (or your company) are contributing to an extraordinary open source project. + +* If you are a Silver Sidewinder or higher-level sponsor, your name and/or logo will be placed on the front page of Twisted's site for twelve months from the time of donation. + +* All sponsors will have their name and/or logo placed on Twisted's Sponsors page for twelve months from the time of donation. + +* Community consciousness of your company (and its use of Twisted) will be increased in the minds of the wider Twisted community. + +* Contributions are tax-deductible. + +Logos +===== + +Logos on the front page will only be there for the year that a sponsor has donated. Each year starts fresh again, with an opportunity to get your logo at the top by early sponsorship! + +Logo Requirements +================= + +Logos must be 160 pixels wide and 80 pixels tall. + +Sponsorship Levels +================== + +Below are the names and amounts associated with levels of sponsorship (as of May 1, 2013): + +* Diamondback: $20,000 and up + +* Platinum Python: $10,000 + +* Golden Tree Snake: $5,000 + +* Silver Sidewinder: $2,000 + +* Copperhead: $1,000 + +* Aluminum Adder: $100 + + +Non-Monetary Donations +====================== + +The Twisted Project will consider the value of non-monetary donations to the project - for example, donations of hardware, software licenses, or hosting - on a case-by-case basis. But, as a general rule, $5 worth of services will correspond to $1 of cash for sponsorship purposes. We note that non-monetary donations may not be tax-deductible; to confirm, you should seek the counsel of a qualified tax professional. In general, we suggest cash donations, as that process is much simpler. + +How to Donate +============= + +All donations to Twisted are collected by `Software Freedom Conservancy`_ , a tax-exempt 501(c)(3) organization and the corporate home of the Twisted Project. Conservancy maintains a restricted account for the Twisted Project's use. + +If you would like to participate in Twisted's Sponsorship program: please note that Aluminum Adder sponsorships are accepted only via the PayPal widget below. For sponsorships of Copperhead and higher, we welcome you to contact `accounting@sfconservancy.org` to coordinate payment methods by ACH or wire, so that we can avoid credit card fees and put more of your donation to work for Twisted! However, if you prefer PayPal, do feel free to use the PayPal widget to make your donation. + +.. raw:: html + +
+ + + + +
+ + + +
+ +If you would prefer to cut a check, you may do this as well. Make the check payable to "Software Freedom Conservancy" and write "Directed Donation for Twisted" or "Sponsorship Donation to Twisted" in the "memo" field. Checks should be sent to the following address: + +Software Freedom Conservancy, Inc. +137 MONTAGUE ST STE 380 +Brooklyn, NY 11201-3548 + +If you would prefer to make other arrangements (e.g., your corporation requires the use of a purchase order, even when donating to a charity), contact us at ``twistedsponsor@sfconservancy.org``. diff --git a/content/pages/Twisted/TwistedSponsors.rst b/content/pages/Twisted/TwistedSponsors.rst new file mode 100644 index 0000000..96d3a22 --- /dev/null +++ b/content/pages/Twisted/TwistedSponsors.rst @@ -0,0 +1,38 @@ +The Twisted Project Sponsorship Program +####################################### + + +We want to continue to invest in and improve Twisted -- for the benefit of our users, and the public at large. We can't do this without the support of our sponsors and, as a project, we want to publicly acknowledge certain donations through our revamped Twisted Project Sponsorship Program. + +For more information about becoming a Twisted Sponsor, click `here `__. + +Golden Tree Snake +================= + + +Silver Sidewinder +================= + +.. raw:: html + +

+ +Copperhead +========== + + +Aluminum Adder +============== + +.. raw:: html + +

+ +

+ +

+ +

+ + +For information on Twisted's founding sponsors, click `here `__. diff --git a/content/pages/UltimateQualityDevelopmentSystem.rst b/content/pages/UltimateQualityDevelopmentSystem.rst new file mode 100644 index 0000000..3426912 --- /dev/null +++ b/content/pages/UltimateQualityDevelopmentSystem.rst @@ -0,0 +1,174 @@ +Ultimate Quality Development System (UQDS) +########################################## + + +Divmod has been developing software for several years, and over the course of that time, we have developed a methodology, which involves a ticket discipline and a suggested use for a version control system. It is extremely lightweight and "agile", and can be combined as a component of any other methodology which breaks down work into individual tasks. + +The briefest summary of the requirements for UQDS is that every task has 3 absolutely required steps. + +* A task is created in an issue tracker and assigned to a worker. +* The worker does work, and creates a change-set to be applied to the mainline revision control system. (This can be represented as either a branch or a patch file.) +* A reviewer reviews the completed work, and provides feedback: at least one good thing about the work, at least one area that needs improvement, and a judgement as to whether the good qualities ultimately outweigh the bad, i.e. whether the branch should be merged. + +The principles involved are: + +* Most importantly, **all** work on a project must be reviewed by at least one person. In conjunction with XP's PairProgramming, this provides a minimum of 3 involved parties to every change. Especially on small teams, this eliminates the possibility of finger-pointing, and increases the whole team's awareness of the project in general. Also, it addresses an area of code-review that PairProgramming does not: i.e. a decision might make sense at the time in the microcosm of some problem being solved, but be hard to explain or justify in the context of the larger project. This provides an after-the-fact opportunity to verify that public methods are documented, debug prints are removed, and comments actually make sense to someone who wasn't present when the code is being written. +* **All** work on a project must be represented as changes to a version control system. This most popularly applies to code, but in an ideal application of this methodology, designs, documentation and even plans could be added to the repository. We are currently not quite so strict. +* **All** work on a project must be represented by tickets in a ticket tracker. If it's not in the tracker, you shouldn't be working on it. This provides a way to manage distractions and continuously re-focus on what's really important. +* **All** development is done on branches - no development is done on the ``trunk``. The ``trunk`` can be used to see branch differences, run test suites, build distributions, etc., but is not used for development. This may seem odd, but there are numerous reasons why it is a good idea (see below). + +The lifetime of a task in UQDS in practice (using `Git `_ and `Trac `_) looks something like this, with a developer ``dev`` and a reviewer ``rev``. + +* A ticket is created in the issue tracker. +* For features, a specification is attached to the ticket. For defects, reproduction instructions. +* The developer who is assigned the task "accepts" the task, by changing its state to "accepted". +* A branch is created in Git. The branch is named with the convention -[-]. (For smaller patches, or work done by non-committer developers, this and the next step can be omitted. The developer can attach a patch to the ticket instead of creating a branch.) + +.. code-block:: console + + dev@strange$ git checkout -b 123-sprocket-fire trunk + +* Development occurs to implement the feature or resolve the defect in the branch. +* When the code is deemed ready by the developer, the developer checks in their changes **on the branch** (not the trunk). +* The branch is then assigned to another developer for review. The ticket should be given the keyword "review", assigned to the reviewer and the priority set to "highest". +* The reviewer switches to the branch, then merges it locally, to review it in the context of how it will change trunk. + +.. code-block:: console + + rev@charm$ git checkout trunk + rev@charm$ git pull + rev@charm$ git merge --no-ff --no-commit 123-sprocket-fire + rev@charm$ git diff --staged + +* (If the patch does not merge cleanly, the reviewer may reassign to the developer to merge/rebase before reviewing again. Branches and patches must always be sufficiently recent that they will apply cleanly to trunk in order to be considered for review). +* The reviewer runs all automated tests. + +.. code-block:: console + + rev@charm$ trial twisted + +* The reviewer verifies that the code makes sense, has unit tests, has documentation, updates any existing documentation that is affected, and actually resolves the issue in question. +* If any more work is required, the reviewer reassigns to the developer explaining what else needs to be done in a ticket comment. The reviewer can use ``git merge --abort`` to back out of the merge if the branch changes are not acceptable. When this process has been repeated enough times that all the tests pass and the reviewer is satisfied, they re-assign to the developer for merging, and the developer merges. + +.. code-block:: console + + dev@strange$ git commit -m " + A brief description of the sprocket feature. + + Author: dev + + Reviewer: rev + + Fixes #123 + + A detailed description of the sprocket feature. + " + + dev@strange$ git branch -d 123-sprocket-fire + dev@strange$ git push -d origin 123-sprocket-fire + +* the "fixes" note in the commit message automatically resolves the ticket with a status of "fixed". Voila! Our feature is implemented and ready in trunk. + +Branch lifetimes should be short. If trunk moves very far from the branch, the branch should be rebased or merged to pick up bug fixes and feature enhancements which might be useful. Doing this also makes the final merge easier, by keeping conflicts small and bringing them to the developer's attention before they become unmanageable. + +Why Branches ? +============== + +The most recent version of source code in the repository should always be working. That makes it a lot easier to deploy fixes and tweaks quickly. However, sometimes you need to check in code to test it on a different machine, or show it to a different developer. A version control system is useful in many ways, and if you only have one branch, these purposes conflict. + +Here are some of its features. + +Keep ``trunk`` Working +---------------------- + +The most recent revision of a piece of software, that is, ``trunk@HEAD`` should always work. Any new developer should be able to check out the most recent version and immediately start working, without worrying that the build is broken this week. + +With branch-based development, features are only merged to trunk after they have been tested and reviewed by at least one other developer. + +Switch Developers Mid-Feature +----------------------------- + +If a developer gets stuck because it turns out that part of a feature is outside their expertise, they can easily put code that they know is broken into a branch, then indicate that branch to another developer and reassign the ticket, without breaking trunk. + +Provide Useful Progress Information to Management +------------------------------------------------- + +Branches directly correspond to user-facing tasks. A quick look at the list of branches should indicate to managers what is actually going on. If there are a lot of branches (more than twice the number of developers, let's say), that means that the team's efforts are getting diffuse and they need to focus more and get branches merged. If branches are being turned over quickly, it means that tasks are being completed quickly. + +Mechanism for Code Review +------------------------- + +Usually `CodeReview `_ is done by module, and only after the fact. While this practice is useful, it only raises problems that already exist, it doesn't prevent them. + +By reviewing each branch as a change, rather than a module, problems are spotted earlier on, and developers can work on any modules that are necessary for a particular task, with no worries that the maintainer won't notice - on a larger team, any module maintainers should be asked for review. + +This is also a low-friction review process. Rather than submitting a branch for review and discussing it interactively, a developer may accept a ticket, start a branch, commit a few times, finish, put the ticket into review, move on to an unrelated branch, repeat, put that branch into review, then check their assigned tickets at the end of the day and merge any branches which have been accepted before finishing for the day. + +Generate a Meaningful Changelog +------------------------------- + +Often, source control logs are riddled with nonsensical, tiny changes. "twiddled whitespace", "added a few docstrings", etc. Because it's good to commit frequently to avoid losing too much work or generating monolithic changes, this is hard to avoid. Commit messages generate a bottleneck to getting work into the repository, which is bad. + +If every branch has a clear purpose, then only ''merges'' need have useful, descriptive commit messages, and since no code is changing when a developer is doing a merge to trunk, they can take all the time they need to come up with a good message. This means that the changelog generated directly from a revision log of trunk (as opposed to the whole repository) is likely to be useful as a changelog. + +Tangentially related, commit messages for merges should include at least three pieces of information: + +* The author of the branch. +* The reviewer of the branch. +* The tickets which the branch resolves or relates to. + +Revert Useful Units +------------------- + +If something ''does'' break trunk, you can revert it with one command, rather than sifting through piles of related commit messages and trying to assemble a useful revert. It's "revision 1234", not "revision 1232, 1237, 1239, 1246, and I think maybe 1255 too, you should run the tests both ways". + +Merge When You're Merging, Not When You're Hacking +-------------------------------------------------- + +If you are working directly in trunk, any update may cause conflicts which you have to immediately resolve before you can continue working. With branches, a smaller number of developers can work on a branch, knowing that their changes won't conflict, and update regularly. + +That means you are never interrupted with an unpleasant required merge. Your code is always in the repository ''before'' you worry about merging it with other people's changes, so there is no concern that although your code was working before you were ready to commit, the merge went badly and you never committed in a working state. + +Develop on a Preferred Platform, Test on Another, Disturbing No-one +------------------------------------------------------------------- + +If a developer prefers to code in a Unix environment but needs to add a feature for Windows, they can create a branch, happily work on it under Unix, commit the changes (to the branch), go to a Windows machine and update the branch, test it, repeat etc. This allows one developer to work in private on several machines, using the revision control system in a disciplined and effective way that precludes accidents passing patches or updates between machines, and which has no impact on other developers. + +Cover yourself +-------------- + +If adding a feature or fixing a bug takes a significant amount of time, at some point you're going to want to make sure your changes so far +are backed up. If you're working on the trunk you clearly can't check them in. So you're forced to take a more manual and probably +more error-prone approach to make a backup of your local changes. If instead you're working in a branch, you can just check in your +changes so far - without disturbing the trunk. Of course if there are multiple developers working on one branch, you'll need to do something +else (like work on a branch of a branch). In the simple situation where you're alone on a branch, you can easily save your progress +so far back to the repository and have it be the backup of your work to date on the branch. + +Some Thoughts on Things I Don't Know Anything About +--------------------------------------------------- + +While this process works very well for us on Python code, more heavyweight development environments might find it even more valuable. For example, if it takes an hour-long build process and 20 minutes of testing to determine whether trunk is in a good state, branch-based development could be even more valuable. + +Even if you already have awesome automated tests, branches can speed things up immensely. Let's say Foo Co. has 30 developers and an hour long build and 20 minutes of unit tests. Jethro checks in some broken core header file to trunk and goes to lunch. The automated tests start building and running. Alice, preparing to commit, updates. She receives Jethro's broken changes. Alice, being a better developer than Jethro, runs the tests. She waits 20 minutes. The build is broken! She can't commit, since she doesn't want to break trunk. (All this while, precious hours of work are sitting on Alice's disk, not backed up in the repository...) + +Meanwhile, everyone else in the company has updated, and jethro returns from his early lunch. Thus far, 30 developers * (1 hour of build + 20 minutes of tests) = 40 man hours have been wasted. Everyone knows it was Jethro when he gets back because the build indicates failure on a revision he checks in, but now all 30 developers are standing behind his desk, waiting for him to get trunk back into a working state and test the fix so they can get back to work. That requires ''at least'' another 1:20 of time waiting for the automated tests before Alice can commit her changes. + +Much of this waiting could have been circumvented if Jethro had checked his changes into a branch, and then asked the automated test system to run tests for him, and maybe had one other developer review it for him. By the way, Buildbot has this feature, as do many other CI systems. + +Questions +========= + +* "Why branches" isn't as interesting to me (''meaning Jonathan Lange'') as "Why tickets". One of the things about UQDS that surprises people who do branch-based development is that it insists on putting all information about a change in a single ticket. Why not have feature discussion and code reviews on mailing lists, and then link to those discussions from the ticket? Or perhaps the ticket thing isn't as "core" to UQDS as branches? + * This needs to be integrated more clearly into the body of the document, but actually, tickets are ''more'' core to UQDS than branches. This is one of the reasons I changed the name from "branch based development" to "UQDS". Branches are just a mechanism for sharing work that's in progress; you can still more or less follow the ''process'' (while still taking the greater risk of losing work) just by exchanging and reviewing patches. The ticket/not-a-ticket distinction, however, is key; it's the way the whole process starts. + + At some point, someone in "management" needs to decide that it's worth spending development resources on a particular task. The particulars of who can make this decision, how it is made, when it is scheduled (etc, etc, etc) can differ in the extreme from project to project, but at some point it does need to be made. Tickets are an explicit way of recording "this is work that should happen". It's important to have an explicit, single mechanism for making this distinction, between "stuff we're just talking about" and "stuff somebody should really do some work on", specifically because of the huge number of differences between the way that these discussions are carried out on different projects. Mailing lists are good because at least the discussion is recorded, but when you are communicating with people via mailing lists, via comments on tickets, via commit messages, via IRC, via phone conversations and via in-person meetings, everyone can have a different interpretation of what should be worked on and when. + + A ticket tracker (whatever its form) is a single unambiguous place where a unit of work can be named and identified, committed to, and tracked. If your team has conventions for making these decisions on a mailing list crystal clear, and unambiguous terminology or conventions for identifying tasks, then your mailing list ''is'' a ticket tracker. On a consulting project, clarity becomes especially critical, because the client is always hoping that they can get a few extra features in for free, and will ambiguously talk in meetings about features that have not been agreed upon. In a community project it seems that vagueness is a problem that you can live with, since anyone can file tickets and decide to do some work on their own anyway; however, I've found that once you start doing the rest of UQDS, this clarity becomes especially important because it becomes more likely that someone will go off and implement something on their own, then file a ticket and not understand why it's getting rejected. A ticket provides a much clearer record of the proposal and the rejection for future developers to look at than a mailing list discussion, because structured information accompanies the comments. + + As far as your question about why to actually record these things in a specific ticket tracker, like Trac, rather than using mailing lists for the discussion and then linking to it, this is simply an issue with deficiencies of the technologies. Trac is a pain in the ass, Pipermail is a pain in the ass, bugzilla is a pain in the ass, launchpad is a pain in the ass, reviewboard is a pain in the ass, IRC log bots are a pain in the ass. Web browsers in general are a pain in the ass. These things have slightly varying levels of terribleness, but we can cope. However, the more of them that you pile on top of each other, the worse the tangle becomes. + + If you're running a UQDS project on SVN and Trac, let's say, your users must already be proficient with their web browser, the trac UI, SVN commands, 'patch' and 'diff', just to deal with the basics of the process, let alone the skills they need to actually work on the code. + + Adding a mailing list to this process means that you have now added ''at least'' an email client, the mailman UI, the pipermail UI, and a way to get from the email client UI to the message archive UI to generate links, plus some new magical markup in trac to generate appropriate-looking hyperlinks between ticket comments and email messages. (Plus, you need a new username and password!) Given a bunch of poor choices for what to do about reviews, putting discussions into the body of trac comments seems the least poor to me. + + As far as I'm concerned, though, you could follow UQDS to a T and get all the concomitant process benefits with separate technologies for tracking tasks, discussions, reviews, and specificationsm, and linking them all together. In fact, ideally, that is how it would be done, but building such a system is highly challenging, and doing it so that I'd actually think the UI was any good would probably involve being an IDE-integrated piece of client software with a very discoverable UI that offers frequent, subtle suggestions for the next thing to do. I would hope that web access to such a thing would be entirely read-only - if I fill out one more HTML form in my life, it will be too many times. --Glyph diff --git a/content/pages/Users/index.rst b/content/pages/Users/index.rst new file mode 100644 index 0000000..7a63ee4 --- /dev/null +++ b/content/pages/Users/index.rst @@ -0,0 +1,2 @@ +Placeholder for Users Directory +############################### diff --git a/content/pages/WebDevelopmentWithTwisted.rst b/content/pages/WebDevelopmentWithTwisted.rst new file mode 100644 index 0000000..4cbfef1 --- /dev/null +++ b/content/pages/WebDevelopmentWithTwisted.rst @@ -0,0 +1,50 @@ +Web Development with Twisted +############################ + + +There are a number of packages in and around Twisted that do things with the web: + +* `Twisted Web `_ provides a simple, stable HTTP server, suitable for all types of web apps and web services. It provides a flexible resource publishing API, and implements HTTP 1.0 with some 1.1 features. **Twisted Web is extremely stable.** +* `Divmod Nevow `_ is a templating toolkit that provides its own resource model and simple application server API. It requires Twisted, is fully integrated with the Twisted reactor, provides mechanisms for asynchronous page rendering, and an event-driven `COMET `_ /AJAX implementation called `"Nevow Athena" `_. Nevow uses Twisted Web, but provides its own request objects and resource model on top of it. +* `Divmod Mantissa `_ is a full-featured multi-protocol application server, with a built-in object database, authentication model based on Twisted Cred, a capability-based security model, and many more features. It integrates Nevow (and therefore Twisted Web) and a number of other Twisted-related technologies to provide a full-featured system. + +So You Want To Be A Web Developer +================================= + +Having reviewed this list, the obvious question is, *which of these tools should I use for my application???* The short answer is: "It depends." + +You can always ask about these kinds of issues on the `Twisted Web mailing list `_, but here's a cheat-sheet that you may want to read in advance, listing some of the things that you might want to be doing with Twisted and the consensus as to the correct (or multiple possible correct) solutions for each case. + + +I want a container for my WSGI application +------------------------------------------ + +In this case, **use the Twisted Web (8.2 or newer) WSGI module** (``twistd web --wsgi=application``). + +I want a web UI for my existing Twisted networking application +-------------------------------------------------------------- + +Assuming that your networking application has its own data persistence, or does not require persistence, and needs a web-based control panel or monitoring UI, you probably want to **use Nevow** Nevow provides backwards compatibility between releases (as does Twisted Web, on which it is built), just like all Twisted projects. It also provides a templating system which makes implementing user interfaces that integrate with the event loop much easier than coding directly to the Twisted Web API. Nevow also has support for the AJAX and COMET, via Nevow Athena. Athena lets you take advantage of the event loop on multiple levels; you can push events from network triggers straight out to a web page. + +I want to write a REST / WS-* interface to my Twisted application +----------------------------------------------------------------- + +In this case your best bet is to **use Twisted Web** directly. You won't need XHTML templating, so Nevow buys you little extra. + +Twisted Web already has basic support for XMLRPC and SOAP, and it is fairly straightforward to set up a web service. Twisted Web also provides various facilities for being set up behind a reverse-proxy, which is the suggested mechanism to integrate your Twisted application with an existing site. + +I Want a Web Framework +---------------------- + +AKA + +I want to write a Wiki +~~~~~~~~~~~~~~~~~~~~~~ +I want to write a blog +~~~~~~~~~~~~~~~~~~~~~~ +I want something to compare to Flask or Django or Ruby on Rails +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The short version is that this is more complicated in Twisted than in other tools at the moment. Sadly, you aren't going to find a straight-up competitor with the sort of polished web presence and easy instant integration with your SQL database and existing environment that the aforementioned products offer. + +`Divmod Mantissa `_ is a full-featured Twisted-powered application server and will likely appeal to you if you want an integrated database and other high-level framework support. diff --git a/content/pages/WhyShouldICare.rst b/content/pages/WhyShouldICare.rst new file mode 100644 index 0000000..acc0461 --- /dev/null +++ b/content/pages/WhyShouldICare.rst @@ -0,0 +1,29 @@ +What Twisted Is +############### + + +Twisted is an asynchronous framework designed specifically around networks and databases. This allows for concurrency without requiring the use of forking processes or spawning threads. Now, this obviously does not come without some additional work, especially if you're used to using one of the other methods. + +For a simple program that only is concerned about doing exactly one thing at one time, standard synchronous blocking programming will do just fine. + +Note: Getting/sending information from/to a server while displaying and repainting a GUI is actually two things. + +Python +------ + +Python is well known in the computer science industry for promoting readability, increased maintainability, and high levels of productivity. For more information see `python.org `_. + +Scalable +-------- + +On the other hand, if you put in a little more work upfront, things like scaling becomes a much easier issue. + +Note: This includes scaling up to more simultaneous requests or scaling down to lower powered systems. + +The Proof +========= + +Okay, you've made all these claims, but where's the proof? + +* `Success Stories `_ - See what others say about Twisted +* `Software that uses Twisted `_ - See who uses Twisted diff --git a/content/pages/WindowsBuilds.rst b/content/pages/WindowsBuilds.rst new file mode 100644 index 0000000..e31d4b2 --- /dev/null +++ b/content/pages/WindowsBuilds.rst @@ -0,0 +1,28 @@ +Building Twisted on Windows +########################### + + + +This contains information for building Twisted on Windows + + +Installation requirements +========================= + +You will need a standard Python 3 dev environment. See the official documentation at https://docs.python.org/3/using/windows.html + +Download Visual Studio Installer and get the following components for C++ build tools (might use newer versions): + +* MSVC v142 - VS 2019 C++ build tools +* Windows 10 SDK + +You can get Python 3 via nuget. + +Also get Git for Windows. + +Dev process +=========== + +Make sure pip script is installed with ``python -m pip install -U pip`` as the default python might be created with only the pip module and without the pip script. + +Then you can do the standard ``pip install -e .[dev]`` diff --git a/images/founding-sponsors-logos/Appropriate-Solutions-Inc.gif b/images/founding-sponsors-logos/Appropriate-Solutions-Inc.gif new file mode 100644 index 0000000..85a18d9 Binary files /dev/null and b/images/founding-sponsors-logos/Appropriate-Solutions-Inc.gif differ diff --git a/images/founding-sponsors-logos/Contentinople.jpg b/images/founding-sponsors-logos/Contentinople.jpg new file mode 100644 index 0000000..6fd9d3a Binary files /dev/null and b/images/founding-sponsors-logos/Contentinople.jpg differ diff --git a/images/founding-sponsors-logos/ExpanDrive.gif b/images/founding-sponsors-logos/ExpanDrive.gif new file mode 100644 index 0000000..f3a2476 Binary files /dev/null and b/images/founding-sponsors-logos/ExpanDrive.gif differ diff --git a/images/founding-sponsors-logos/ITA_logo_160x80.jpg b/images/founding-sponsors-logos/ITA_logo_160x80.jpg new file mode 100644 index 0000000..0706256 Binary files /dev/null and b/images/founding-sponsors-logos/ITA_logo_160x80.jpg differ diff --git a/images/founding-sponsors-logos/InternetEvolution.jpg b/images/founding-sponsors-logos/InternetEvolution.jpg new file mode 100644 index 0000000..fda5d2a Binary files /dev/null and b/images/founding-sponsors-logos/InternetEvolution.jpg differ diff --git a/images/founding-sponsors-logos/LightReading.jpg b/images/founding-sponsors-logos/LightReading.jpg new file mode 100644 index 0000000..eb6c7cc Binary files /dev/null and b/images/founding-sponsors-logos/LightReading.jpg differ diff --git a/images/founding-sponsors-logos/adytum.png b/images/founding-sponsors-logos/adytum.png new file mode 100644 index 0000000..aed0da2 Binary files /dev/null and b/images/founding-sponsors-logos/adytum.png differ diff --git a/images/founding-sponsors-logos/allmydata.jpg b/images/founding-sponsors-logos/allmydata.jpg new file mode 100644 index 0000000..72c3d56 Binary files /dev/null and b/images/founding-sponsors-logos/allmydata.jpg differ diff --git a/images/founding-sponsors-logos/bazaar2.png b/images/founding-sponsors-logos/bazaar2.png new file mode 100644 index 0000000..563f08b Binary files /dev/null and b/images/founding-sponsors-logos/bazaar2.png differ diff --git a/images/founding-sponsors-logos/canonical.png b/images/founding-sponsors-logos/canonical.png new file mode 100644 index 0000000..a96ddd4 Binary files /dev/null and b/images/founding-sponsors-logos/canonical.png differ diff --git a/images/founding-sponsors-logos/chesspark.png b/images/founding-sponsors-logos/chesspark.png new file mode 100644 index 0000000..b604bbd Binary files /dev/null and b/images/founding-sponsors-logos/chesspark.png differ diff --git a/images/founding-sponsors-logos/dcitlogo.png b/images/founding-sponsors-logos/dcitlogo.png new file mode 100644 index 0000000..c6a7fec Binary files /dev/null and b/images/founding-sponsors-logos/dcitlogo.png differ diff --git a/images/founding-sponsors-logos/divlogo4_8_w160_banner.jpg b/images/founding-sponsors-logos/divlogo4_8_w160_banner.jpg new file mode 100644 index 0000000..2200266 Binary files /dev/null and b/images/founding-sponsors-logos/divlogo4_8_w160_banner.jpg differ diff --git a/images/founding-sponsors-logos/flumotion-logo-160x50.gif b/images/founding-sponsors-logos/flumotion-logo-160x50.gif new file mode 100644 index 0000000..d58225d Binary files /dev/null and b/images/founding-sponsors-logos/flumotion-logo-160x50.gif differ diff --git a/images/founding-sponsors-logos/hwebtsf160x80.png b/images/founding-sponsors-logos/hwebtsf160x80.png new file mode 100644 index 0000000..12f478a Binary files /dev/null and b/images/founding-sponsors-logos/hwebtsf160x80.png differ diff --git a/images/founding-sponsors-logos/hydra.png b/images/founding-sponsors-logos/hydra.png new file mode 100644 index 0000000..166bbf9 Binary files /dev/null and b/images/founding-sponsors-logos/hydra.png differ diff --git a/images/founding-sponsors-logos/lucasfilm.jpg b/images/founding-sponsors-logos/lucasfilm.jpg new file mode 100644 index 0000000..c6295f9 Binary files /dev/null and b/images/founding-sponsors-logos/lucasfilm.jpg differ diff --git a/images/founding-sponsors-logos/microsoft.png b/images/founding-sponsors-logos/microsoft.png new file mode 100644 index 0000000..f707a84 Binary files /dev/null and b/images/founding-sponsors-logos/microsoft.png differ diff --git a/images/founding-sponsors-logos/onresolve3.png b/images/founding-sponsors-logos/onresolve3.png new file mode 100644 index 0000000..d6a2c21 Binary files /dev/null and b/images/founding-sponsors-logos/onresolve3.png differ diff --git a/images/founding-sponsors-logos/seafelt.png b/images/founding-sponsors-logos/seafelt.png new file mode 100644 index 0000000..d39be8a Binary files /dev/null and b/images/founding-sponsors-logos/seafelt.png differ diff --git a/images/founding-sponsors-logos/securitymetrics.png b/images/founding-sponsors-logos/securitymetrics.png new file mode 100644 index 0000000..bd78648 Binary files /dev/null and b/images/founding-sponsors-logos/securitymetrics.png differ diff --git a/images/founding-sponsors-logos/sun.png b/images/founding-sponsors-logos/sun.png new file mode 100644 index 0000000..85e39e3 Binary files /dev/null and b/images/founding-sponsors-logos/sun.png differ diff --git a/images/founding-sponsors-logos/tummy.png b/images/founding-sponsors-logos/tummy.png new file mode 100644 index 0000000..3067241 Binary files /dev/null and b/images/founding-sponsors-logos/tummy.png differ diff --git a/images/founding-sponsors-logos/zenoss.gif b/images/founding-sponsors-logos/zenoss.gif new file mode 100644 index 0000000..d79393c Binary files /dev/null and b/images/founding-sponsors-logos/zenoss.gif differ diff --git a/images/sponsors-logos/Atlassian-hipchat-logo.png b/images/sponsors-logos/Atlassian-hipchat-logo.png new file mode 100644 index 0000000..e2b82f3 Binary files /dev/null and b/images/sponsors-logos/Atlassian-hipchat-logo.png differ diff --git a/images/sponsors-logos/CouponDC.png b/images/sponsors-logos/CouponDC.png new file mode 100644 index 0000000..31ac79d Binary files /dev/null and b/images/sponsors-logos/CouponDC.png differ diff --git a/images/sponsors-logos/Variomedia-rescaled.png b/images/sponsors-logos/Variomedia-rescaled.png new file mode 100644 index 0000000..0ecf567 Binary files /dev/null and b/images/sponsors-logos/Variomedia-rescaled.png differ diff --git a/images/sponsors-logos/krismis.png b/images/sponsors-logos/krismis.png new file mode 100644 index 0000000..6094c32 Binary files /dev/null and b/images/sponsors-logos/krismis.png differ diff --git a/images/sponsors-logos/landingi-logo.png b/images/sponsors-logos/landingi-logo.png new file mode 100644 index 0000000..8fd5c00 Binary files /dev/null and b/images/sponsors-logos/landingi-logo.png differ diff --git a/images/sponsors-logos/videdressing-logo-160x40.jpg b/images/sponsors-logos/videdressing-logo-160x40.jpg new file mode 100644 index 0000000..b25a2ea Binary files /dev/null and b/images/sponsors-logos/videdressing-logo-160x40.jpg differ diff --git a/index.html b/index.html index a37ebdb..e11bc12 100644 --- a/index.html +++ b/index.html @@ -30,7 +30,7 @@

Twisted

  • - FAQ + FAQ
  • Docs @@ -248,7 +248,7 @@

    An event-driven networking engine written in Python

    for your IMAP4 server. You'll see the subject of the first message in your mailbox printed.

    - See the TwistedMail documentation for more information. + See the TwistedMail documentation for more information.

@@ -332,10 +332,10 @@

Community

Contribute

- Learn about the Twisted development process and how to contribute. + Learn about the Twisted development process and how to contribute.

- Help improve Twisted on Windows! + Help improve Twisted on Windows!

@@ -344,7 +344,7 @@

Contribute

Wiki

- Read about software using Twisted and their success stories. + Read about software using Twisted and their success stories.

@@ -353,7 +353,7 @@

Wiki

Sponsors

- Learn about the individuals and organisations that aid Twisted with donations of hardware, software, hosting and other things. + Learn about the individuals and organisations that aid Twisted with donations of hardware, software, hosting and other things.

@@ -362,7 +362,7 @@

Sponsors

Twisted Matrix Laboratories

- Find out what Twisted Matrix Laboratories is. + Find out what Twisted Matrix Laboratories is.

@@ -413,7 +413,7 @@

Follow us on Twitter

-

Report a security issue

+

Report a security issue

@@ -448,7 +448,7 @@

Join the tax-deductible. + tax-deductible.

@@ -511,10 +511,10 @@

Twisted Sponsors

- Participate in the Twisted Project Sponsorship Program! + Participate in the Twisted Project Sponsorship Program!

- For Silver Sidewinder and higher-level sponsors, we will display your logo here on the front page for one year. + For Silver Sidewinder and higher-level sponsors, we will display your logo here on the front page for one year.

diff --git a/index.rst b/index.rst new file mode 100644 index 0000000..598bd59 --- /dev/null +++ b/index.rst @@ -0,0 +1,20 @@ +.. Twisted documentation master file, created by + sphinx-quickstart on Sat Feb 19 17:21:47 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Twisted's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..153be5e --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd