Twisted development should always be
- test-driven. The complete test suite in trunk@HEAD is required to
+ test-driven. The complete test suite in the head of the SVN trunk is required to
be passing on
supported platforms at all times. Regressions in the test suite
are addressed by reverting whatever revisions introduced them. For
@@ -55,7 +55,7 @@
the test suite are generally better examples than older parts - check
when the code you are looking at was written before you use it as an
example of what you should write). The names of test modules should
- begin with test_
so that they are automatically discoverable by
+ begin with test_ so that they are automatically discoverable by
test runners such as Trial. Twisted's unit tests are written using
twisted.trial, an xUnit library which has been
extensively customized for use in testing Twisted and Twisted-based
@@ -527,10 +527,10 @@ myref.callRemote("addUser", name="bob", phone="555-1212")
In this case, callRemote (and any code that uses the
- **kwargs syntax) must be careful to not use name
, phone
, or
- any other name that might overlap with a user-provided named parameter.
- Therefore, callRemote is implemented with the following
- signature:
**kwargs syntax) must be careful to not use
+ name,
phone, or any other name that might overlap with + a user-provided named parameter. Therefore,
callRemote is
+ implemented with the following signature:
def callRemote(self, _name, *args, **kw):
@@ -545,7 +545,8 @@ def callRemote(self, _name, *args, **kw):
Special Methods
- The augmented assignment protocol, defined by __iadd__ and other
+
The augmented assignment protocol, defined by __iadd__ and other
similarly named methods, can be used to allow objects to be modified in
place or to rebind names if an object is immutable -- both through use
of the same operator. This can lead to confusing code, which in turn
diff --git a/doc/core/development/policy/doc-standard.xhtml b/doc/core/development/policy/doc-standard.xhtml
index 68ef7c4..ff0d4ce 100644
--- a/doc/core/development/policy/doc-standard.xhtml
+++ b/doc/core/development/policy/doc-standard.xhtml
@@ -12,7 +12,7 @@
Allowable Tags
- Please try to restrict your HTML usage to the following tags (all only for the original logical purpose, and not whatever visual effect you see): <html>, <title>, <head>, <body>, <h1>, <h2, <h3>, <ol>, <ul>, <dl>, <li>, <dt>, <dd>, <p>, <code>, <img>, <blockquote>, <a>, <cite>, <div>, <span>, <strong>, <em>, <pre>, <q>, <table>,<tr>, <td> and <th>.
+ Please try to restrict your HTML usage to the following tags (all only for the original logical purpose, and not whatever visual effect you see): <html>, <title>, <head>, <body>, <h1>, <h2, <h3>, <ol>, <ul>, <dl>, <li>, <dt>, <dd>, <p>, <code>, <img>, <blockquote>, <a>, <cite>, <div>, <span>, <strong>, <em>, <pre>, <q>, <table>, <tr>, <td> and <th>.
Please avoid using the quote sign (") for quoting, and use the relevant html tags (<q></q>) -- it is impossible to distinguish right and left quotes with the quote sign, and some more sophisticated output methods work better with that distinction.
@@ -24,20 +24,25 @@
and shell
. For example:
python
+ Original markup:
+
- <p>
- For example, this is how one defines a Resource:
- </p>
+<p>
+For example, this is how one defines a Resource:
+</p>
- <pre class="python">
+<pre class="python">
from twisted.web import resource
class MyResource(resource.Resource):
def render_GET(self, request):
return "Hello, world!"
- </pre>
+</pre>
+
+ Rendered result:
+
For example, this is how one defines a Resource:
from twisted.web import resource
@@ -47,24 +52,30 @@ class MyResource(resource.Resource):
return "Hello, world!"
+
Note that you should never have leading indentation inside a
<pre> block -- this makes it hard for readers to
copy/paste the code.
python-interpreter
+ Original markup:
+
- <pre class="python-interpreter">
- >>> from twisted.web import resource
- >>> class MyResource(resource.Resource):
- ... def render_GET(self, request):
- ... return "Hello, world!"
- ...
- >>> MyResource().render_GET(None)
- "Hello, world!"
- </pre>
+<pre class="python-interpreter">
+>>> from twisted.web import resource
+>>> class MyResource(resource.Resource):
+... def render_GET(self, request):
+... return "Hello, world!"
+...
+>>> MyResource().render_GET(None)
+"Hello, world!"
+</pre>
+
+ Rendered result:
+
>>> from twisted.web import resource
>>> class MyResource(resource.Resource):
@@ -74,17 +85,24 @@ class MyResource(resource.Resource):
>>> MyResource().render_GET(None)
"Hello, world!"
+
shell
+ Original markup:
+
<pre class="shell">
$ twistd web --path /var/www
</pre>
+
+ Rendered result:
+
$ twistd web --path /var/www
+
Code inside paragraph text
@@ -103,6 +121,8 @@ $ twistd web --path /var/www
to the module or classname. This is to help keep the documentation
clearer and less cluttered by allowing links to API docs that don't
need the module name.
+ Original markup:
+
<p>
To add a <code class="API">twisted.web.widgets.Widget</code>
@@ -120,8 +140,10 @@ $ twistd web --path /var/www
</p>
+
-
+ Rendered result:
+
To add a twisted.web.widgets.Widget
instance to a Gadget
@@ -135,8 +157,7 @@ $ twistd web --path /var/www
which is a
list.)
-
-
+
Headers
diff --git a/doc/core/development/policy/svn-dev.xhtml b/doc/core/development/policy/svn-dev.xhtml
index ae4ea97..0ee68f9 100644
--- a/doc/core/development/policy/svn-dev.xhtml
+++ b/doc/core/development/policy/svn-dev.xhtml
@@ -22,10 +22,10 @@ edge.
Checkout
-Subversion tutorials can be found elsewhere, see in particular
+
Subversion tutorials can be found elsewhere, see in particular
the Subversion homepage. The
relevant data you need to check out a copy of the Twisted tree is available on
-the development
+the development
page, and is as follows:
@@ -35,15 +35,15 @@ $ svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk Twisted
Alternate tree names
By using svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk
-otherdir, you can put the workspace tree in a directory other than
+otherdir, you can put the workspace tree in a directory other than
Twisted
. I do this (with a name like Twisted-Subversion
) to
remind myself that this tree comes from Subversion and not from a released
version (like Twisted-1.0.5
). This practice can cause a few problems,
because there are a few places in the Twisted tree that need to know where
the tree starts, so they can add it to sys.path without
requiring the user manually set their PYTHONPATH. These functions walk the
-current directory up to the root, looking for a directory named
-Twisted
(sometimes exactly that, sometimes with a
+current directory up to the root, looking for a directory named
+Twisted
(sometimes exactly that, sometimes with a
.startswith test). Generally these are test scripts or other
administrative tools which expect to be launched from somewhere inside the
tree (but not necessarily from the top).
@@ -58,31 +58,33 @@ problems.
Combinator
-In order to simplify the use of Subversion, we typically use
+
In order to simplify the use of Subversion, we typically use
Divmod Combinator.
You may find it to be useful, too. In particular, because Twisted uses
branches for almost all feature development, if you plan to contribute to
Twisted you will probably find Combinator very useful. For more details,
-see the Combinator website, as well as the
+see the Combinator website, as well as the
UQDS page.
Compiling C extensions
-There are currently several C extension modules in Twisted:
-twisted.protocols._c_urlarg, twisted.internet.cfsupport,
-twisted.internet.iocpreactor._iocp, and twisted.python._epoll. These modules
+There are currently several C extension modules in Twisted:
+twisted.protocols._c_urlarg,
+twisted.internet.cfsupport,
+twisted.internet.iocpreactor._iocp,
+and twisted.python._epoll. These modules
are optional, but you'll have to compile them if you want to experience their
features, performance improvements, or bugs. There are two approaches.
The first is to do a regular distutils ./setup.py build, which
-will create a directory under build/ to hold both the generated
+will create a directory under build/ to hold both the generated
.so files as well as a copy of the 600-odd .py files
that make up Twisted. If you do this, you will need to set your PYTHONPATH to
something like MyDir/Twisted/build/lib.linux-i686-2.5 in order to
-run code against the Subversion twisted (as opposed to whatever's installed in
+run code against the Subversion twisted (as opposed to whatever's installed in
/usr/lib/python2.5 or wherever python usually looks). In
addition, you will need to re-run the build command every
time you change a .py file. The build/lib.foo
@@ -95,7 +97,7 @@ PYTHONPATH at the top of the tree, like MyDir/Twisted. This way
you're using the .py files in place too, removing the confusion a forgotten
rebuild could cause with the separate build/ directory above. To build the C
modules in place, do ./setup.py build_ext -i. You only need to
-re-run this command when you change the C files. Note that
+re-run this command when you change the C files. Note that
setup.py is not Make, it does not always get the dependencies
right (.h files in particular), so if you are hacking on the
cReactor you may need to manually delete the .o files before
@@ -127,13 +129,13 @@ do one of:
This depends upon the .py file having an appropriate
test-case-name
tag that indicates which test cases provide coverage.
See the Test Standards document for
-details about using test-case-name
. In this example, the
+details about using test-case-name
. In this example, the
twisted.mail.test.test_imap test will be run.
Many tests create temporary files in /tmp or ./_trial_temp, but
everything in /tmp should be deleted when the test finishes. Sometimes these
-cleanup calls are commented out by mistake, so if you see a stray
-/tmp/@12345.1 directory, it is probably from test_dirdbm or test_popsicle.
+cleanup calls are commented out by mistake, so if you see a stray
+/tmp/@12345.1 directory, it is probably from test_dirdbm or test_popsicle.
Look for an rmtree that has been commented out and complain to
the last developer who touched that file.
@@ -154,7 +156,7 @@ the index file will be placed in doc/howto/index.html.
./bin/lore/lore -p --config template=doc/howto/template.tpl doc/howto/*.xhtml
-To run hlint over a single Lore document, such as
+
To run hlint over a single Lore document, such as
doc/development/policy/svn-dev.xhtml, do the following. This is
useful because the HTML conversion may bail without a useful explanation if
it sees mismatched tags.
@@ -164,7 +166,7 @@ it sees mismatched tags.
To convert it to HTML (including markup, interpolation of examples,
-footnote processing, etc), do the following. The results will be placed in
+footnote processing, etc), do the following. The results will be placed in
doc/development/policy/svn-dev.html:
@@ -176,13 +178,13 @@ footnote processing, etc), do the following. The results will be placed in include a--largument tobin/lore/lore. Links in the .xhtml file are to .xhtml targets: when the .xhtml is turned into .html, the link targets are supposed to be turned into .html also. In addition to this, -Lore markup of the form <code class="API"> is supposed to +Lore markup of the form<code class="API">is supposed to turn into a link to the corresponding API reference page. These links will probably be wrong unless the correct base URL is provided to Lore.Committing and Post-commit Hooks
-Twisted uses a customized +
Twisted uses a customized trac-post-commit-hook to enable ticket updates based on svn commit logs. When making a branch for a ticket, the branch name should end @@ -205,12 +207,12 @@ Fixes: #9999 My longer description of the changes made.
The Twisted Coding Standard +
The Twisted Coding Standard elaborates on commit messages and source control.
A minor mode for development with Twisted using Emacs is available. See +
A minor mode for development with Twisted using Emacs is available. See
emacs/twisted-dev.el for several utility functions which make
it easier to grep for methods, run test cases, etc.
Our support for building Debian packages has fallen into disrepair. We would very much like to restore this functionality, but until we do so, if -you are interested in this, you are on your own. See +you are interested in this, you are on your own. See stdeb for one possible approach to this.
diff --git a/doc/core/development/policy/test-standard.xhtml b/doc/core/development/policy/test-standard.xhtml index 8df03f6..e1efdfa 100644 --- a/doc/core/development/policy/test-standard.xhtml +++ b/doc/core/development/policy/test-standard.xhtml @@ -129,7 +129,7 @@ operating systems. The important common factor is that nobody considers these limitations to be a bug.To make it easy to test as much as possible, some tests may be skipped in
-certain situations. Individual test cases can raise the
+certain situations. Individual test cases can raise the
SkipTest exception to indicate that they should be skipped, and
the remainder of the test is not run. In the summary (the very last thing
printed, at the bottom of the test output) the test is counted as a
@@ -253,7 +253,7 @@ in the issue tracker would be more useful.
Trial provides line coverage information, which is very useful to ensure
old code has decent coverage. Passing the --coverage option to
-to Trial will generate the coverage information in a file called
+to Trial will generate the coverage information in a file called
coverage which can be found in the _trial_temp
folder. This option requires Python 2.3.3 or newer.
unittest module documentation, in the unittest module documentation, in the Python Library
Reference.